[OGUI-1748] QC should be using logging that has facility set per process env (#3052)

* [OGUI-1748] Logging to use process.env in QCG and documentation (#3008)

Author: graduta

QualityControl/README.md

@@ -12,6 +12,7 @@ QCG is a **Web-based graphical user interface (GUI)** designed for [**O<sup>2</s
 
 ## Table of Contents
 - [Installation](docs/Installation.md)
+- [QCG Developer Logging Conventions](./docs/QCG_Developer_Logging_Conventions.md)
 - [Architecture](docs/Architecture.md)
 - [Testing](docs/Testing.md)
 - [Features](docs/Features.md)

QualityControl/docs/QCG_Developer_Logging_Conventions.md

@@ -0,0 +1,41 @@
+# QCG Developer Logging Conventions
+
+## Introduction
+
+QCG (Quality Control GUI) is deployed in multiple production instances, each serving a separate QCDB database. To ensure clear separation of logs and traceability across deployments, developers must follow specific logging conventions.
+
+## Logging with LogManager and LOG_FACILITY
+
+Logging in QCG should use the O2 Logging application from the `@aliceo2/web-ui` framework. This wraps the Winston library and O2's InfoLogger project, providing a unified logging interface.
+
+### Why Use LOG_FACILITY?
+
+Each QCG deployment (e.g., `qcg`, `qcg-mc`, `qcg-async`) should have its own log label. This allows logs to be easily attributed to the correct deployment and QCDB instance.
+The standard for the log_facility is: `<application_name>/<file>`
+The standard for the log_facility is: `<application_name>/<service>`
+
+> **Note:** The `<service>` portion should be a descriptive name for the service, module, or controller (e.g., `bkp-service`, `obj-controller`). This helps make logs more readable and traceable. Avoid using generic filenames; prefer meaningful service names as shown in the examples below.
+### Setting the Log Facility
+
+The log facility string should be built using the `process.env.npm_config_log_label` environment variable. If not set, a sensible default (e.g., `qcg`) should be used.
+
+### Example: Setting Up Logging in BookkeepingService
+
+```js
+import { LogManager } from '@aliceo2/web-ui';
+
+// Use the environment variable or a default value
+const LOG_FACILITY = `${process.env.npm_config_log_label ?? 'qcg'}/bkp-service`;
+
+// Initialize the logger for this service
+this._logger = LogManager.getLogger(LOG_FACILITY);
+
+// Usage example
+this._logger.infoMessage('BookkeepingService started');
+```
+
+### Best Practices
+
+- **Always use the provided logger:** Do not use `console.log` or other logging libraries directly.
+- **Set the log label via environment variable:** This ensures logs are correctly attributed in multi-instance deployments.
+- **Log meaningful events:** Include context in log messages to aid debugging and monitoring.

QualityControl/lib/controllers/ObjectController.js

@@ -14,6 +14,8 @@
 'use strict';
 import { LogManager, updateAndSendExpressResponseFromNativeError } from '@aliceo2/web-ui';
 
+const LOG_FACILITY = `${process.env.npm_config_log_label ?? 'qcg'}/obj-controller`;
+
 /**
  * Gateway for all QC Objects requests
  * @class
@@ -35,7 +37,7 @@ export class ObjectController {
      * @type {RunMonitoringService}
      */
     this._runModeService = runModeService;
-    this._logger = LogManager.getLogger(`${process.env.npm_config_log_label ?? 'qcg'}/object-ctrl`);
+    this._logger = LogManager.getLogger(LOG_FACILITY);
   }
 
   /**

QualityControl/lib/controllers/UserController.js

@@ -13,14 +13,14 @@
  */
 
 import assert from 'assert';
-import { LogManager } from '@aliceo2/web-ui';
+import { LogLevel, LogManager } from '@aliceo2/web-ui';
+
+const LOG_FACILITY = `${process.env.npm_config_log_label ?? 'qcg'}/user-controller`;
 
 /**
  * @typedef {import('../repositories/UserRepository.js').UserRepository} UserRepository
  */
 
-const logger = LogManager.getLogger(`${process.env.npm_config_log_label ?? 'qcg'}/user`);
-
 /**
  * Gateway for all User data calls
  */
@@ -32,6 +32,7 @@ export class UserController {
  */
   constructor(userRepository) {
     assert(userRepository, 'Missing User Repository');
+    this._logger = LogManager.getLogger(LOG_FACILITY);
 
     /**
      * User repository for interacting with user data.
@@ -56,9 +57,11 @@ export class UserController {
       res.status(200).json({ ok: true });
     } catch (err) {
       if (err.stack) {
-        logger.trace(err);
+        this._logger.trace(err);
       }
-      logger.error('Unable to add user to memory');
+      this._logger.errorMessage('Unable to add user to memory', {
+        level: LogLevel.SUPPORT,
+      });
       res.status(502).json({ ok: false, message: 'Unable to add user to memory' });
     }
   }

QualityControl/lib/database/SequelizeDatabase.js

@@ -21,12 +21,14 @@ import { getDbConfig } from '../config/database.js';
 import models from './models/index.js';
 import { SequelizeStorage } from 'umzug';
 
+const LOG_FACILITY = `${process.env.npm_config_log_label ?? 'qcg'}/database`;
+
 /**
  * Sequelize implementation of the Database.
  */
 export class SequelizeDatabase {
   constructor(config) {
-    this._logger = LogManager.getLogger('qcg/database');
+    this._logger = LogManager.getLogger(LOG_FACILITY);
 
     if (!config) {
       this._logger.warnMessage('No configuration provided for SequelizeDatabase. Using default configuration.');

QualityControl/lib/database/index.js

@@ -14,13 +14,15 @@
 
 import { LogManager } from '@aliceo2/web-ui';
 
+const LOG_FACILITY = `${process.env.npm_config_log_label ?? 'qcg'}/database`;
+
 /**
  * Initializes the database connection and runs migrations.
  * @param {object} sequelizeDatabase - The Sequelize database instance.
  * @returns {Promise<void>} A promise that resolves when the database is initialized.
  */
 export const initDatabase = async (sequelizeDatabase) => {
-  const _logger = LogManager.getLogger('qcg/database');
+  const _logger = LogManager.getLogger(LOG_FACILITY);
   try {
     await sequelizeDatabase.connect();
     await sequelizeDatabase.migrate();

QualityControl/lib/database/migrations/20250424113921-add-default-options.mjs

@@ -15,7 +15,6 @@
 /**
  * Creates default options for drawing and display hints in the database.
  * @param {object} queryInterface - The Sequelize query interface.
- * @param {Sequelize} Sequelize - The Sequelize library.
  * @returns {Promise<void>} A promise that resolves when the options are created.
  */
 export const up = async (queryInterface) => {

QualityControl/lib/services/BookkeepingService.js

@@ -16,11 +16,12 @@ import { RunStatus } from '../../common/library/runStatus.enum.js';
 import { httpGetJson } from '../utils/httpRequests.js';
 import { LogManager } from '@aliceo2/web-ui';
 
-const logger = LogManager.getLogger(`${process.env.npm_config_log_label ?? 'bkp-service'}`);
 const GET_BKP_DATABASE_STATUS_PATH = '/api/status/database';
 const GET_RUN_TYPES_PATH = '/api/runTypes';
 const GET_RUN_PATH = '/api/runs';
 
+const LOG_FACILITY = `${process.env.npm_config_log_label ?? 'qcg'}/bkp-service`;
+
 /**
  * BookkeepingService class to be used to retrieve data from Bookkeeping
  */
@@ -34,6 +35,8 @@ export class BookkeepingService {
     this._port = null;
     this._token = '';
     this._protocol = '';
+
+    this._logger = LogManager.getLogger(LOG_FACILITY);
   }
 
   /**
@@ -69,12 +72,12 @@ export class BookkeepingService {
    */
   async connect() {
     if (!this.validateConfig()) {
-      logger.infoMessage(`Bookkeeping service will not be used. Reason: ${this.error}`);
+      this._logger.infoMessage(`Bookkeeping service will not be used. Reason: ${this.error}`);
       return;
     }
     this.active = await this.simulateConnection();
     if (!this.active) {
-      logger.infoMessage(`Bookkeeping service will not be used. Reason: ${this.error}`);
+      this._logger.infoMessage(`Bookkeeping service will not be used. Reason: ${this.error}`);
     }
   }
 
@@ -94,7 +97,7 @@ export class BookkeepingService {
         },
       );
       if (data && data?.status?.ok && data?.status?.configured) {
-        logger.infoMessage('Successfully connected to Bookkeeping');
+        this._logger.infoMessage('Successfully connected to Bookkeeping');
         return true;
       } else {
         this.error = 'Bookkeeping service is not configured or status is not OK';
@@ -133,7 +136,7 @@ export class BookkeepingService {
    */
   async retrieveRunStatus(runNumber) {
     if (!this.active) {
-      logger.warnMessage('Could not connect to bookkeeping');
+      this._logger.warnMessage('Could not connect to bookkeeping');
       return RunStatus.BOOKKEEPING_UNAVAILABLE;
     }
 
@@ -151,10 +154,10 @@ export class BookkeepingService {
     } catch (error) {
       const msg = error?.message ?? String(error);
       if (msg.includes('404')) {
-        logger.warnMessage(`Run number ${runNumber} not found in bookkeeping`);
+        this._logger.warnMessage(`Run number ${runNumber} not found in bookkeeping`);
         return RunStatus.NOT_FOUND;
       }
-      logger.errorMessage(`Error fetching run status: ${error.message || error}`);
+      this._logger.errorMessage(`Error fetching run status: ${error.message || error}`);
       return RunStatus.UNKNOWN;
     }
   }

QualityControl/lib/services/FilterService.js

@@ -14,7 +14,8 @@
 
 import { LogManager } from '@aliceo2/web-ui';
 import { RunStatus } from '../../common/library/runStatus.enum.js';
-const LOG_FACILITY = `${process.env.npm_config_log_label ?? 'qcg'}/filter-svc`;
+
+const LOG_FACILITY = `${process.env.npm_config_log_label ?? 'qcg'}/filter-service`;
 
 /**
  * High level service that composes, processes and maps data from the bookkeeping service
@@ -29,6 +30,7 @@ export class FilterService {
     this._logger = LogManager.getLogger(LOG_FACILITY);
     this._bookkeepingService = bookkeepingService;
     this._runTypes = [];
+    this.initFilters();
 
     this._runTypesRefreshInterval = config?.bookkeeping?.runTypesRefreshInterval ??
       (config?.bookkeeping ? 24 * 60 * 60 * 1000 : -1);

QualityControl/lib/services/JsonFileService.js

@@ -13,10 +13,11 @@
  */
 
 import { LogManager } from '@aliceo2/web-ui';
-const logger = LogManager.getLogger(`${process.env.npm_config_log_label ?? 'qcg'}/json`);
 import fs from 'fs';
 import path from 'path';
 
+const LOG_FACILITY = `${process.env.npm_config_log_label ?? 'qcg'}/json-service`;
+
 /**
  * Store layouts inside JSON based file with atomic write
  */
@@ -26,6 +27,8 @@ export class JsonFileService {
    * @param {string} pathname - path to JSON DB file
    */
   constructor(pathname) {
+    this._logger = LogManager.getLogger(LOG_FACILITY);
+
     // Path of the file to store data
     this.pathname = path.join(pathname);
     this.pathnameTmp = `${this.pathname}~tmp`;
@@ -41,7 +44,7 @@ export class JsonFileService {
   async _syncFileAndInternalState() {
     await this._readFromFile();
     await this.writeToFile();
-    logger.infoMessage(`Preferences will be saved in ${this.pathname}`);
+    this._logger.infoMessage(`Preferences will be saved in ${this.pathname}`);
   }
 
   /**
@@ -54,7 +57,7 @@ export class JsonFileService {
         if (err) {
           // File does not exist, it's ok, we will create it
           if (err.code === 'ENOENT') {
-            logger.info('DB file does not exist, will create one');
+            this._logger.infoMessage('DB file does not exist, will create one');
             return resolve();
           }
 
@@ -93,9 +96,9 @@ export class JsonFileService {
       const dataToFile = JSON.stringify(this.data, null, 1);
       await fs.promises.writeFile(this.pathnameTmp, dataToFile);
       await fs.promises.rename(this.pathnameTmp, this.pathname);
-      logger.infoMessage('DB file updated');
+      this._logger.infoMessage('DB file updated');
     } catch (err) {
-      logger.errorMessage('Error writing to DB file:', err);
+      this._logger.errorMessage('Error writing to DB file:', err);
       throw err;
     } finally {
       this.lock.release();