From a2072c5facb4e74515f8ec58138d04d381f7d5d8 Mon Sep 17 00:00:00 2001 From: KernelDeimos Date: Thu, 5 Dec 2024 12:09:11 -0500 Subject: [PATCH] doc: move/clean ErrorService Some documentation comments were missing or inaccurate so these were also edited after moving. --- src/backend/src/CoreModule.js | 2 -- src/backend/src/modules/core/Core2Module.js | 3 ++ .../core}/ErrorService.js | 25 ++++++++++++++-- src/backend/src/modules/core/README.md | 30 +++++++++++++++++++ 4 files changed, 55 insertions(+), 5 deletions(-) rename src/backend/src/{services/runtime-analysis => modules/core}/ErrorService.js (78%) diff --git a/src/backend/src/CoreModule.js b/src/backend/src/CoreModule.js index 69edd725b..94b1938f5 100644 --- a/src/backend/src/CoreModule.js +++ b/src/backend/src/CoreModule.js @@ -87,7 +87,6 @@ const install = async ({ services, app, useapi, modapi }) => { // in a future PR. const { PagerService } = require('./services/runtime-analysis/PagerService'); - const { ErrorService } = require('./services/runtime-analysis/ErrorService'); const { CommandService } = require('./services/CommandService'); const { ExpectationService } = require('./services/runtime-analysis/ExpectationService'); const { HTTPThumbnailService } = require('./services/thumbnails/HTTPThumbnailService'); @@ -144,7 +143,6 @@ const install = async ({ services, app, useapi, modapi }) => { services.registerService('__gui', ServeGUIService); services.registerService('expectations', ExpectationService); services.registerService('pager', PagerService); - services.registerService('error-service', ErrorService); services.registerService('registry', RegistryService); services.registerService('__registrant', RegistrantService); services.registerService('fslock', FSLockService); diff --git a/src/backend/src/modules/core/Core2Module.js b/src/backend/src/modules/core/Core2Module.js index b2e8a9f0b..dc1a1f1d6 100644 --- a/src/backend/src/modules/core/Core2Module.js +++ b/src/backend/src/modules/core/Core2Module.js @@ -24,6 +24,9 @@ class Core2Module extends AdvancedBase { const { AlarmService } = require("./AlarmService.js"); services.registerService('alarm', AlarmService); + + const { ErrorService } = require("./ErrorService.js"); + services.registerService('error-service', ErrorService); } } diff --git a/src/backend/src/services/runtime-analysis/ErrorService.js b/src/backend/src/modules/core/ErrorService.js similarity index 78% rename from src/backend/src/services/runtime-analysis/ErrorService.js rename to src/backend/src/modules/core/ErrorService.js index 8ec2ea837..cef2064a4 100644 --- a/src/backend/src/services/runtime-analysis/ErrorService.js +++ b/src/backend/src/modules/core/ErrorService.js @@ -17,7 +17,7 @@ * You should have received a copy of the GNU Affero General Public License * along with this program. If not, see . */ -const BaseService = require("../BaseService"); +const BaseService = require("../../services/BaseService"); /** @@ -47,10 +47,11 @@ class ErrorContext { /** +* The ErrorService class is responsible for handling and reporting errors within the system. +* It provides methods to initialize the service, create error contexts, and report errors with detailed logging and alarm mechanisms. + * @class ErrorService * @extends BaseService -* @description The ErrorService class is responsible for handling and reporting errors within the system. -* It provides methods to initialize the service, create error contexts, and report errors with detailed logging and alarm mechanisms. */ class ErrorService extends BaseService { /** @@ -66,9 +67,27 @@ class ErrorService extends BaseService { this.alarm = services.get('alarm'); this.backupLogger = services.get('log-service').create('error-service'); } + + /** + * Creates an ErrorContext instance with the provided logging context. + * + * @param {*} log_context The logging context to associate with the error reports. + * @returns {ErrorContext} An ErrorContext instance. + */ create (log_context) { return new ErrorContext(this, log_context); } + + /** + * Reports an error with the specified location and details. + * The "location" is a string up to the callers discretion to identify + * the source of the error. + * + * @param {*} location The location where the error occurred. + * @param {*} fields The error details to report. + * @param {boolean} [alarm=true] Whether to raise an alarm for the error. + * @returns {void} + */ report (location, { source, logger, trace, extra, message }, alarm = true) { message = message ?? source?.message; logger = logger ?? this.backupLogger; diff --git a/src/backend/src/modules/core/README.md b/src/backend/src/modules/core/README.md index 67f613e43..130c46cfc 100644 --- a/src/backend/src/modules/core/README.md +++ b/src/backend/src/modules/core/README.md @@ -47,6 +47,36 @@ Method to get an alarm by its ID. - **id:** The ID of the alarm to get. +### ErrorService + +The ErrorService class is responsible for handling and reporting errors within the system. +It provides methods to initialize the service, create error contexts, and report errors with detailed logging and alarm mechanisms. + +#### Methods + +##### `init` + +Initializes the ErrorService, setting up the alarm and backup logger services. + +##### `create` + +Creates an ErrorContext instance with the provided logging context. + +###### Parameters + +- **log_context:** The logging context to associate with the error reports. + +##### `report` + +Reports an error with the specified location and details. +The "location" is a string up to the callers discretion to identify +the source of the error. + +###### Parameters + +- **location:** The location where the error occurred. +- **fields:** The error details to report. + ### LogService The `LogService` class extends `BaseService` and is responsible for managing and