@eqxjs/nest-logger 3.1.0-beta.9 → 3.1.1-beta.0

package/dist/core/loggers/base-app.logger.d.ts

@@ -0,0 +1,299 @@
+import { CustomLogger } from './custom.logger';
+import { LoggerDto } from '../../models/logger.dto';
+import { LoggerOpt } from '../../interfaces/logger-opt.interface';
+/**
+ * BaseAppLogger extends CustomLogger to provide application-level logging with OpenTelemetry integration.
+ * Supports structured logging with telemetry metrics, distributed tracing, and standardized log formats.
+ */
+export declare class BaseAppLogger extends CustomLogger {
+    protected appName: string;
+    protected context?: string;
+    private ignoreAppResultCodeOnTelemetry;
+    private allMetric;
+    private histrogramMetric;
+    private tracer;
+    private otelLogger;
+    protected readonly cachedAppVersion: string;
+    /**
+     * Creates an instance of BaseAppLogger with optional application name and context.
+     * Initializes OpenTelemetry metrics (counter, histogram) and tracer for distributed tracing.
+     *
+     * @param appName - The name of the application (default: 'EQXJS')
+     * @param context - Optional context or component name for the logger
+     */
+    constructor();
+    constructor(appName?: string);
+    constructor(appName?: string, context?: string);
+    /**
+     * Converts undefined or empty metric attributes to the default 'none' value.
+     * Used to ensure telemetry attributes always have a valid string value.
+     *
+     * @param metricAttr - The metric attribute value to normalize
+     * @returns The normalized metric attribute or 'none' if undefined/empty
+     */
+    private setMetricAttrToNone;
+    /**
+     * Initializes and constructs a LoggerDto object with all necessary fields for structured logging.
+     * Uses the builder pattern to create a fully populated log entry.
+     *
+     * @param level - The log level (debug, info, warn, error, verbose)
+     * @param message - The log message (any type, will be formatted)
+     * @param action - The action being logged (default: 'none')
+     * @param originateServiceName - The originating service name (default: 'none')
+     * @param recordName - The record identifier (default: 'none')
+     * @param sessionId - The session identifier (default: 'none')
+     * @param transactionId - The transaction identifier (default: 'none')
+     * @param channel - The channel through which the request came (default: 'none')
+     * @param componentVersion - The version of the component (default: 'none')
+     * @param useCase - The use case being executed (default: 'none')
+     * @param useCaseStep - The specific step within the use case (default: 'none')
+     * @param user - The user identifier (default: 'none')
+     * @param device - The device identifier(s) (default: 'none')
+     * @param public_ - Public identifier (default: 'none')
+     * @param opt - Optional logging options for customization
+     * @returns A fully constructed LoggerDto object
+     */
+    initializeAppLogger(level: string, message: any, action?: string, originateServiceName?: string, recordName?: string, sessionId?: string, transactionId?: string, channel?: string, componentVersion?: string, useCase?: string, useCaseStep?: string, user?: string, device?: string | string[], public_?: string, opt?: LoggerOpt): LoggerDto;
+    /**
+     * Internal method to write a log entry at the specified level.
+     * Initializes the logger detail and flushes it to the output.
+     *
+     * @param level - The log level
+     * @param message - The log message
+     * @param action - The action being logged (default: 'none')
+     * @param originateServiceName - The originating service name (default: 'none')
+     * @param recordName - The record identifier (default: 'none')
+     * @param sessionId - The session identifier (default: 'none')
+     * @param transactionId - The transaction identifier (default: 'none')
+     * @param channel - The channel identifier (default: 'none')
+     * @param componentVersion - The component version (default: 'none')
+     * @param useCase - The use case (default: 'none')
+     * @param useCaseStep - The use case step (default: 'none')
+     * @param user - The user identifier (default: 'none')
+     * @param device - The device identifier(s) (default: 'none')
+     * @param public_ - Public identifier (default: 'none')
+     * @param opt - Optional logging options
+     */
+    private writeLog;
+    /**
+     * Logs a debug-level message. Debug logs are typically used for detailed diagnostic information.
+     * Only writes the log if the debug level is enabled in the configuration.
+     *
+     * @param message - The debug message to log
+     * @param action - The action being logged (default: 'none')
+     * @param originateServiceName - The originating service name (default: 'none')
+     * @param recordName - The record identifier (default: 'none')
+     * @param sessionId - The session identifier (default: 'none')
+     * @param transactionId - The transaction identifier (default: 'none')
+     * @param channel - The channel identifier (default: 'none')
+     * @param componentVersion - The component version (default: 'none')
+     * @param useCase - The use case (default: 'none')
+     * @param useCaseStep - The use case step (default: 'none')
+     * @param user - The user identifier (default: 'none')
+     * @param device - The device identifier(s) (default: 'none')
+     * @param public_ - Public identifier (default: 'none')
+     * @param opt - Optional logging options
+     */
+    debug(message: any, action?: string, originateServiceName?: string, recordName?: string, sessionId?: string, transactionId?: string, channel?: string, componentVersion?: string, useCase?: string, useCaseStep?: string, user?: string, device?: string | string[], public_?: string, opt?: LoggerOpt): void;
+    /**
+     * Logs an info-level message. This is an alias for the info() method.
+     * Used for general informational messages about application execution.
+     *
+     * @param message - The informational message to log
+     * @param action - The action being logged (default: 'none')
+     * @param originateServiceName - The originating service name (default: 'none')
+     * @param recordName - The record identifier (default: 'none')
+     * @param sessionId - The session identifier (default: 'none')
+     * @param transactionId - The transaction identifier (default: 'none')
+     * @param channel - The channel identifier (default: 'none')
+     * @param componentVersion - The component version (default: 'none')
+     * @param useCase - The use case (default: 'none')
+     * @param useCaseStep - The use case step (default: 'none')
+     * @param user - The user identifier (default: 'none')
+     * @param device - The device identifier(s) (default: 'none')
+     * @param public_ - Public identifier (default: 'none')
+     * @param opt - Optional logging options
+     */
+    log(message: any, action?: string, originateServiceName?: string, recordName?: string, sessionId?: string, transactionId?: string, channel?: string, componentVersion?: string, useCase?: string, useCaseStep?: string, user?: string, device?: string | string[], public_?: string, opt?: LoggerOpt): void;
+    /**
+     * Logs an info-level message. Info logs provide general information about application execution.
+     * Only writes the log if the info level is enabled in the configuration.
+     *
+     * @param message - The informational message to log
+     * @param action - The action being logged (default: 'none')
+     * @param originateServiceName - The originating service name (default: 'none')
+     * @param recordName - The record identifier (default: 'none')
+     * @param sessionId - The session identifier (default: 'none')
+     * @param transactionId - The transaction identifier (default: 'none')
+     * @param channel - The channel identifier (default: 'none')
+     * @param componentVersion - The component version (default: 'none')
+     * @param useCase - The use case (default: 'none')
+     * @param useCaseStep - The use case step (default: 'none')
+     * @param user - The user identifier (default: 'none')
+     * @param device - The device identifier(s) (default: 'none')
+     * @param public_ - Public identifier (default: 'none')
+     * @param opt - Optional logging options
+     */
+    info(message: any, action?: string, originateServiceName?: string, recordName?: string, sessionId?: string, transactionId?: string, channel?: string, componentVersion?: string, useCase?: string, useCaseStep?: string, user?: string, device?: string | string[], public_?: string, opt?: LoggerOpt): void;
+    /**
+     * Logs a warning-level message. Warning logs indicate potential issues or unusual conditions.
+     * Only writes the log if the warn level is enabled in the configuration.
+     *
+     * @param message - The warning message to log
+     * @param action - The action being logged (default: 'none')
+     * @param originateServiceName - The originating service name (default: 'none')
+     * @param recordName - The record identifier (default: 'none')
+     * @param sessionId - The session identifier (default: 'none')
+     * @param transactionId - The transaction identifier (default: 'none')
+     * @param channel - The channel identifier (default: 'none')
+     * @param componentVersion - The component version (default: 'none')
+     * @param useCase - The use case (default: 'none')
+     * @param useCaseStep - The use case step (default: 'none')
+     * @param user - The user identifier (default: 'none')
+     * @param device - The device identifier(s) (default: 'none')
+     * @param public_ - Public identifier (default: 'none')
+     * @param opt - Optional logging options
+     */
+    warn(message: any, action?: string, originateServiceName?: string, recordName?: string, sessionId?: string, transactionId?: string, channel?: string, componentVersion?: string, useCase?: string, useCaseStep?: string, user?: string, device?: string | string[], public_?: string, opt?: LoggerOpt): void;
+    /**
+     * Logs an error-level message. Error logs indicate failures or critical issues.
+     * Only writes the log if the error level is enabled in the configuration.
+     *
+     * @param message - The error message to log
+     * @param action - The action being logged (default: 'none')
+     * @param originateServiceName - The originating service name (default: 'none')
+     * @param recordName - The record identifier (default: 'none')
+     * @param sessionId - The session identifier (default: 'none')
+     * @param transactionId - The transaction identifier (default: 'none')
+     * @param channel - The channel identifier (default: 'none')
+     * @param componentVersion - The component version (default: 'none')
+     * @param useCase - The use case (default: 'none')
+     * @param useCaseStep - The use case step (default: 'none')
+     * @param user - The user identifier (default: 'none')
+     * @param device - The device identifier(s) (default: 'none')
+     * @param public_ - Public identifier (default: 'none')
+     * @param opt - Optional logging options
+     */
+    error(message: any, action?: string, originateServiceName?: string, recordName?: string, sessionId?: string, transactionId?: string, channel?: string, componentVersion?: string, useCase?: string, useCaseStep?: string, user?: string, device?: string | string[], public_?: string, opt?: LoggerOpt): void;
+    /**
+     * Logs a verbose-level message. Verbose logs provide the most detailed information.
+     * Only writes the log if the verbose level is enabled in the configuration.
+     *
+     * @param message - The verbose message to log
+     * @param action - The action being logged (default: 'none')
+     * @param originateServiceName - The originating service name (default: 'none')
+     * @param recordName - The record identifier (default: 'none')
+     * @param sessionId - The session identifier (default: 'none')
+     * @param transactionId - The transaction identifier (default: 'none')
+     * @param channel - The channel identifier (default: 'none')
+     * @param componentVersion - The component version (default: 'none')
+     * @param useCase - The use case (default: 'none')
+     * @param useCaseStep - The use case step (default: 'none')
+     * @param user - The user identifier (default: 'none')
+     * @param device - The device identifier(s) (default: 'none')
+     * @param public_ - Public identifier (default: 'none')
+     * @param opt - Optional logging options
+     */
+    verbose(message: any, action?: string, originateServiceName?: string, recordName?: string, sessionId?: string, transactionId?: string, channel?: string, componentVersion?: string, useCase?: string, useCaseStep?: string, user?: string, device?: string | string[], public_?: string, opt?: LoggerOpt): void;
+    /**
+     * Logs a successful operation summary with telemetry metrics.
+     * Creates a summary-type log entry and records OpenTelemetry metrics (counter, histogram, span).
+     *
+     * @param appResult - The result description of the operation (default: 'none')
+     * @param appResultCode - The result code of the operation (default: 'none')
+     * @param serviceTime - The service processing time in milliseconds (default: 0)
+     * @param originateServiceName - The originating service name (default: 'none')
+     * @param recordName - The record identifier (default: 'none')
+     * @param sessionId - The session identifier (default: 'none')
+     * @param transactionId - The transaction identifier (default: 'none')
+     * @param channel - The channel identifier (default: 'none')
+     * @param componentVersion - The component version (default: 'none')
+     * @param useCase - The use case (default: 'none')
+     * @param useCaseStep - The use case step (default: 'none')
+     * @param user - The user identifier (default: 'none')
+     * @param device - The device identifier(s) (default: 'none')
+     * @param public_ - Public identifier (default: 'none')
+     * @param opt - Optional logging options
+     * @returns The created LoggerDto object
+     */
+    summarySuccess(appResult?: string, appResultCode?: string, serviceTime?: number, originateServiceName?: string, recordName?: string, sessionId?: string, transactionId?: string, channel?: string, componentVersion?: string, useCase?: string, useCaseStep?: string, user?: string, device?: string | string[], public_?: string, opt?: LoggerOpt): LoggerDto;
+    /**
+     * Logs a failed operation summary with telemetry metrics and optional stack trace.
+     * Creates a summary-type error log entry and records OpenTelemetry metrics (counter, histogram, span).
+     *
+     * @param appResult - The result description of the failed operation (default: 'none')
+     * @param appResultCode - The error result code (default: 'none')
+     * @param serviceTime - The service processing time in milliseconds (default: 0)
+     * @param originateServiceName - The originating service name (default: 'none')
+     * @param recordName - The record identifier (default: 'none')
+     * @param sessionId - The session identifier (default: 'none')
+     * @param transactionId - The transaction identifier (default: 'none')
+     * @param channel - The channel identifier (default: 'none')
+     * @param componentVersion - The component version (default: 'none')
+     * @param useCase - The use case (default: 'none')
+     * @param useCaseStep - The use case step (default: 'none')
+     * @param user - The user identifier (default: 'none')
+     * @param device - The device identifier(s) (default: 'none')
+     * @param public_ - Public identifier (default: 'none')
+     * @param stack - Optional error stack trace array
+     * @param opt - Optional logging options
+     * @returns The created LoggerDto object
+     */
+    summaryError(appResult?: string, appResultCode?: string, serviceTime?: number, originateServiceName?: string, recordName?: string, sessionId?: string, transactionId?: string, channel?: string, componentVersion?: string, useCase?: string, useCaseStep?: string, user?: string, device?: string | string[], public_?: string, stack?: string[], opt?: LoggerOpt): LoggerDto;
+    /**
+     * Creates a summary log entry with specialized fields for operation results.
+     * Transforms the log structure by removing message/action fields and adding summary-specific fields.
+     *
+     * @param level - The log level (info for success, error for failure)
+     * @param appResult - The result description
+     * @param appResultCode - The result code
+     * @param serviceTime - The service processing time in milliseconds
+     * @param originateServiceName - The originating service name
+     * @param recordName - The record identifier
+     * @param sessionId - The session identifier
+     * @param transactionId - The transaction identifier
+     * @param channel - The channel identifier
+     * @param componentVersion - The component version
+     * @param useCase - The use case
+     * @param useCaseStep - The use case step
+     * @param user - The user identifier
+     * @param device - The device identifier(s)
+     * @param public_ - Public identifier
+     * @param opt - Optional logging options
+     * @param stack - Optional error stack trace array
+     * @returns The created summary LoggerDto object
+     */
+    private createSummaryLog;
+    /**
+     * Pushes log data to OpenTelemetry Logs API.
+     * Emits a log record with structured attributes for observability platforms.
+     *
+     * @param loggerDetail - The logger DTO containing log details
+     * @param severityNumber - The OpenTelemetry severity level
+     */
+    private pushLogToOpenTelemetry;
+    /**
+     * Records telemetry data to OpenTelemetry for monitoring and observability.
+     * Creates metrics (counter, histogram) and a distributed trace span with operation details.
+     * Skips recording if the result code is in the ignore list.
+     *
+     * @param appResultCode - The result code to record
+     * @param appResult - The result description
+     * @param recordName - The record identifier
+     * @param useCase - The use case being executed
+     * @param serviceTime - The service processing time in milliseconds
+     * @param originateServiceName - The originating service name
+     * @param success - Whether the operation was successful
+     * @param stack - Optional error stack trace array
+     */
+    private recordTelemetry;
+    /**
+     * Transforms JSON values during serialization by converting empty strings to 'none'.
+     * Used as a JSON.stringify replacer function to ensure consistent default values.
+     *
+     * @param key - The JSON key being processed
+     * @param value - The value to transform
+     * @returns The transformed value ('none' if empty string, otherwise the original value)
+     */
+    jsonTransformer(key: string, value: string): string;
+}