plutin 1.7.6 → 1.7.10

package/dist/index.d.ts

@@ -1,9 +1,71 @@
 import { z } from 'zod';
-import { Express } from 'express';
-import { FastifyInstance, FastifyRequest, FastifyReply } from 'fastify';
-import { Logger } from '@opentelemetry/api-logs';
-import winston from 'winston';
+import { FastifyInstance } from 'fastify';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { LoggerProvider } from '@opentelemetry/sdk-logs';
 import { NodeSDK } from '@opentelemetry/sdk-node';
+import { Span, trace } from '@opentelemetry/api';
+
+declare const baseEnvSchema: z.ZodObject<{
+    NODE_ENV: z.ZodDefault<z.ZodEnum<["test", "development", "production"]>>;
+    ENVIRONMENT: z.ZodDefault<z.ZodEnum<["test", "development", "staging", "production"]>>;
+    PORT: z.ZodDefault<z.ZodNumber>;
+    DISCORD_WEBHOOK_URL: z.ZodOptional<z.ZodString>;
+    OTEL_ENABLE: z.ZodDefault<z.ZodEffects<z.ZodString, boolean, string>>;
+    OTEL_EXPORTER_OTLP_ENDPOINT: z.ZodOptional<z.ZodString>;
+    OTEL_SERVICE_NAME: z.ZodOptional<z.ZodString>;
+    OTEL_SERVICE_VERSION: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    NODE_ENV: "test" | "development" | "production";
+    ENVIRONMENT: "test" | "development" | "production" | "staging";
+    PORT: number;
+    OTEL_ENABLE: boolean;
+    DISCORD_WEBHOOK_URL?: string | undefined;
+    OTEL_EXPORTER_OTLP_ENDPOINT?: string | undefined;
+    OTEL_SERVICE_NAME?: string | undefined;
+    OTEL_SERVICE_VERSION?: string | undefined;
+}, {
+    NODE_ENV?: "test" | "development" | "production" | undefined;
+    ENVIRONMENT?: "test" | "development" | "production" | "staging" | undefined;
+    PORT?: number | undefined;
+    DISCORD_WEBHOOK_URL?: string | undefined;
+    OTEL_ENABLE?: string | undefined;
+    OTEL_EXPORTER_OTLP_ENDPOINT?: string | undefined;
+    OTEL_SERVICE_NAME?: string | undefined;
+    OTEL_SERVICE_VERSION?: string | undefined;
+}>;
+
+type LogParams = {
+    msg: string;
+    data?: {
+        correlationId?: string;
+        [key: string]: any;
+    };
+    error?: Error;
+};
+interface ILogger {
+    info(data: LogParams): void;
+    error(data: LogParams): void;
+    debug(data: LogParams): void;
+    fatal(data: LogParams): void;
+    warn(data: LogParams): void;
+}
+type OptionsNotifications = 'console' | 'discord' | 'otel';
+type Props$1 = {
+    development?: OptionsNotifications;
+    staging?: OptionsNotifications;
+    production?: OptionsNotifications;
+};
+declare class Logger {
+    static define(env: z.infer<typeof baseEnvSchema>, definitions?: Props$1): any;
+    private static defineProvider;
+}
+
+declare class GlobalListener {
+    private readonly callback;
+    protected readonly logger: ILogger;
+    constructor(callback: () => Promise<void>);
+    register(): void;
+}
 
 type AnyObject = Record<string, any>;
 type Request = {
@@ -34,7 +96,7 @@ type ContextError = {
     };
 };
 declare abstract class BaseController {
-    protected readonly errorNotifier: IErrorNotifier;
+    protected readonly logger: ILogger;
     abstract handle<T>(request: T | Request): Promise<Response>;
     constructor();
     protected success<T>(dto?: T): Response;
@@ -46,17 +108,6 @@ declare abstract class BaseController {
     execute(request: Request): Promise<Response>;
 }
 
-interface IErrorNotifier {
-    notify(error: Error, context: ContextError): Promise<void>;
-}
-
-declare class GlobalErrorHandler {
-    readonly env: Record<string, any>;
-    protected readonly errorNotifier: IErrorNotifier;
-    constructor(env: Record<string, any>);
-    register(): void;
-}
-
 type ZodSchema = z.ZodObject<{
     headers: z.ZodObject<Record<string, any>>;
     params: z.ZodObject<Record<string, any>>;
@@ -73,12 +124,12 @@ interface IHttp {
     closeServer(): Promise<void>;
 }
 
-type Props$1 = {
+type Props = {
     method: MethodType;
     path: string;
     middlewares?: MiddlewareFunction[];
 };
-declare function Controller({ method, path, middlewares, }: Props$1): ClassDecorator;
+declare function Controller({ method, path, middlewares, }: Props): ClassDecorator;
 
 type Class<T = any> = new (...args: any[]) => T;
 type Registration = {
@@ -230,170 +281,295 @@ type RequestHttp = {
     query: Record<string, any>;
 };
 
-declare class ExpressAdapter implements IHttp {
-    readonly env: Record<string, any>;
-    readonly logger: any;
-    readonly instance: Express;
-    private server;
-    constructor(env: Record<string, any>, logger: any);
-    registerRoute(controllerClass: BaseController): void;
-    startServer(port: number): Promise<void>;
-    closeServer(): Promise<void>;
+interface IMetricsManager {
+    recordHttpRequest(params: {
+        method: string;
+        route: string;
+        statusCode: number;
+        durationSeconds: number;
+        responseSizeBytes?: number;
+    }): void;
+    recordDbQueryError(params: {
+        operation: string;
+        repository: string;
+        errorMessage: string;
+    }): void;
+    recordDbQuery(params: {
+        operation: string;
+        repository: string;
+        durationSeconds: number;
+    }): void;
+    recordDbTransaction(params: {
+        operation: string;
+        repository: string;
+        durationSeconds: number;
+    }): void;
+    recordDbDeadlock(params: {
+        operation: string;
+        repository: string;
+        errorMessage: string;
+    }): void;
+    recordHttpRequestBytes(bytes: number, attributes: {
+        method: string;
+        route: string;
+        statusCode: number;
+    }): void;
+    recordProcessingDuration(params: {
+        operation: string;
+        durationSeconds: number;
+    }): void;
+    recordProcessingError(params: {
+        operation: string;
+        errorType: string;
+    }): void;
+    recordHttpClientRequest(params: {
+        method: string;
+        url: string;
+        statusCode?: number;
+        durationSeconds: number;
+        error?: boolean;
+        timeout?: boolean;
+    }): void;
+    recordValidationError(params: {
+        field?: string;
+        errorType: string;
+    }): void;
+    startSystemMetricsCollection(intervalMs?: number): void;
+    stopSystemMetricsCollection(): void;
+}
+declare class MetricsManager implements IMetricsManager {
+    private meter;
+    private httpRequestsTotal;
+    private httpRequestDuration;
+    private httpRequestsErrors;
+    private httpResponseSize;
+    private dbQueryDuration;
+    private dbQueryErrors;
+    private dbTransactionsTotal;
+    private dbTransactionDuration;
+    private dbDeadlocksTotal;
+    private httpRequestBytesTotal;
+    private processingDuration;
+    private processingErrors;
+    private httpClientRequestsTotal;
+    private httpClientRequestDuration;
+    private httpClientErrors;
+    private httpClientTimeouts;
+    private validationErrors;
+    private processCpuSecondsTotal;
+    private processMemoryBytes;
+    private nodejsHeapSizeTotalBytes;
+    private nodejsHeapSizeUsedBytes;
+    private nodejsEventloopLagSeconds;
+    private nodejsEventloopDurationSeconds;
+    private nodejsGcDurationSeconds;
+    private processOpenFds;
+    private processUptimeSeconds;
+    private eventLoopMonitor;
+    private previousCpuUsage;
+    private collectionInterval?;
+    private gcObserver?;
+    recordHttpRequest(params: {
+        method: string;
+        route: string;
+        statusCode: number;
+        durationSeconds: number;
+        responseSizeBytes?: number;
+    }): void;
+    recordDbQueryError(params: {
+        operation: string;
+        repository: string;
+        errorMessage: string;
+    }): void;
+    recordDbQuery(params: {
+        operation: string;
+        repository: string;
+        durationSeconds: number;
+    }): void;
+    private isValidDbQueryErrorParams;
+    private isValidDbQueryParams;
+    recordDbTransaction(params: {
+        operation: string;
+        repository: string;
+        durationSeconds: number;
+    }): void;
+    recordDbDeadlock(params: {
+        operation: string;
+        repository: string;
+        errorMessage: string;
+    }): void;
+    recordHttpRequestBytes(bytes: number, attributes: {
+        method: string;
+        route: string;
+        statusCode: number;
+    }): void;
+    recordProcessingDuration(params: {
+        operation: string;
+        durationSeconds: number;
+    }): void;
+    recordProcessingError(params: {
+        operation: string;
+        errorType: string;
+    }): void;
+    recordHttpClientRequest(params: {
+        method: string;
+        url: string;
+        statusCode?: number;
+        durationSeconds: number;
+        error?: boolean;
+        timeout?: boolean;
+    }): void;
+    recordValidationError(params: {
+        field?: string;
+        errorType: string;
+    }): void;
+    startSystemMetricsCollection(intervalMs?: number): void;
+    stopSystemMetricsCollection(): void;
+    private collectSystemMetrics;
+    private collectPeriodicMetrics;
+    private setupGCObserver;
+    private getGCKindName;
+    private normalizeUrl;
+    private getStatusClass;
 }
 
 declare class FastifyAdapter implements IHttp {
-    readonly env: Record<string, any>;
-    readonly logger: any;
+    private logger;
+    private metrics?;
     readonly instance: FastifyInstance;
-    constructor(env: Record<string, any>, logger: any);
+    constructor(logger: ILogger, metrics?: IMetricsManager | undefined);
     registerRoute(controllerClass: BaseController): void;
     startServer(port: number): Promise<void>;
     closeServer(): Promise<void>;
+    private getNormalizedRoute;
 }
 
-type DiscordOptions = {
-    url: string;
-    env: string;
+declare const context: AsyncLocalStorage<unknown>;
+type Context = {
+    traceId: string;
 };
-declare class DiscordNotifier implements IErrorNotifier {
-    private readonly options;
-    private webhook;
-    constructor(options: DiscordOptions);
-    notify(error: Error, context: ContextError): Promise<void>;
-}
+declare function getContext(): Context;
 
-declare class NotificationErrorInMemory implements IErrorNotifier {
-    errors: any[];
-    notify(error: Error, context?: ContextError): Promise<void>;
+declare class OtelManager {
+    private readonly env;
+    private readonly resource;
+    private readonly loggerProvider;
+    private readonly sdk;
+    private readonly otlpLogExporter;
+    private readonly traceExporter;
+    private readonly metricExporter;
+    private readonly metricReader;
+    private readonly sampler;
+    constructor(env: Record<string, any>);
+    private createResource;
+    private createOtlpLogExporter;
+    private createLoggerProvider;
+    private configureLogProcessors;
+    private createTraceExporter;
+    private createSampler;
+    private createMetricExporter;
+    private createMetricReader;
+    private createSdk;
+    initialize(): void;
+    shutdown(): Promise<void>;
+    getLoggerProvider(): LoggerProvider;
+    getSdk(): NodeSDK;
 }
 
-declare const baseEnvSchema: z.ZodObject<{
-    NODE_ENV: z.ZodDefault<z.ZodEnum<["test", "development", "production"]>>;
-    ENVIRONMENT: z.ZodDefault<z.ZodEnum<["test", "development", "staging", "production"]>>;
-    PORT: z.ZodDefault<z.ZodNumber>;
-    SHOULD_NOTIFY_ERROR: z.ZodDefault<z.ZodBoolean>;
-    SENTRY_DSN: z.ZodOptional<z.ZodString>;
-    DISCORD_WEBHOOK_URL: z.ZodOptional<z.ZodString>;
-    LOG_LEVEL: z.ZodDefault<z.ZodEnum<["info", "error", "debug", "fatal", "warn"]>>;
-    OTEL_ENABLE: z.ZodDefault<z.ZodBoolean>;
-    OTEL_SERVICE_NAME: z.ZodOptional<z.ZodString>;
-    OTEL_SERVICE_VERSION: z.ZodOptional<z.ZodString>;
-    OTEL_OTLP_TRACES_EXPORTER_URL: z.ZodOptional<z.ZodString>;
-    OTEL_OTLP_LOGS_EXPORTER_URL: z.ZodOptional<z.ZodString>;
-    OTEL_OTLP_METRICS_EXPORTER_URL: z.ZodOptional<z.ZodString>;
-}, "strip", z.ZodTypeAny, {
-    ENVIRONMENT: "test" | "development" | "production" | "staging";
-    SHOULD_NOTIFY_ERROR: boolean;
-    NODE_ENV: "test" | "development" | "production";
-    PORT: number;
-    LOG_LEVEL: "error" | "fatal" | "warn" | "info" | "debug";
-    OTEL_ENABLE: boolean;
-    SENTRY_DSN?: string | undefined;
-    DISCORD_WEBHOOK_URL?: string | undefined;
-    OTEL_SERVICE_NAME?: string | undefined;
-    OTEL_SERVICE_VERSION?: string | undefined;
-    OTEL_OTLP_TRACES_EXPORTER_URL?: string | undefined;
-    OTEL_OTLP_LOGS_EXPORTER_URL?: string | undefined;
-    OTEL_OTLP_METRICS_EXPORTER_URL?: string | undefined;
-}, {
-    ENVIRONMENT?: "test" | "development" | "production" | "staging" | undefined;
-    SHOULD_NOTIFY_ERROR?: boolean | undefined;
-    NODE_ENV?: "test" | "development" | "production" | undefined;
-    PORT?: number | undefined;
-    SENTRY_DSN?: string | undefined;
-    DISCORD_WEBHOOK_URL?: string | undefined;
-    LOG_LEVEL?: "error" | "fatal" | "warn" | "info" | "debug" | undefined;
-    OTEL_ENABLE?: boolean | undefined;
-    OTEL_SERVICE_NAME?: string | undefined;
-    OTEL_SERVICE_VERSION?: string | undefined;
-    OTEL_OTLP_TRACES_EXPORTER_URL?: string | undefined;
-    OTEL_OTLP_LOGS_EXPORTER_URL?: string | undefined;
-    OTEL_OTLP_METRICS_EXPORTER_URL?: string | undefined;
-}>;
-
-type OptionsNotifications = 'console' | 'discord' | 'sentry';
-type EnvironmentEnum = z.infer<typeof baseEnvSchema>['ENVIRONMENT'];
-type Props = {
-    test?: OptionsNotifications;
-    development?: OptionsNotifications;
-    staging?: OptionsNotifications;
-    production?: OptionsNotifications;
-};
-declare class NotificationFactory {
-    static define(env: EnvironmentEnum, definitions?: Props): any;
-    private static defineProvider;
+declare class NullSpan {
+    setAttributes(): void;
+    setAttribute(): void;
+    setStatus(): void;
+    recordException(): void;
+}
+declare class SpanManager {
+    static getActiveSpan(): Span | NullSpan;
+    static isEnabled(): boolean;
 }
 
-type SentryOptions = {
-    dsn: string;
-    environment: string;
+declare const TRACER_NAME: string;
+declare const TRACER_VERSION: string;
+declare const OTEL_ENABLED: boolean;
+type Timer = {
+    getDurationSeconds(): number;
 };
-declare class SentryNotifier implements IErrorNotifier {
-    private readonly options;
-    constructor(options: SentryOptions);
-    notify(error: Error, context: ContextError): Promise<void>;
+type BaseExecutionContext = {
+    operation: string;
+    logger?: any;
+};
+interface IMetricsRecorder {
+    recordSuccess(context: BaseExecutionContext, durationSeconds: number): void;
+    recordError(context: BaseExecutionContext, error: Error): void;
 }
-
-interface ILogger {
-    info(data: any): void;
-    error(data: any): void;
-    debug(data: any): void;
-    fatal(data: any): void;
-    warn(data: any): void;
+interface ISpanBuilder {
+    createSpan(tracer: ReturnType<typeof trace.getTracer>, context: BaseExecutionContext): Span | undefined;
+    buildSpanName(context: BaseExecutionContext): string;
+    finalizeSpanSuccess(span: Span, durationSeconds: number): void;
+    finalizeSpanError(span: Span, durationSeconds: number, error: Error): void;
 }
-
-declare class WinstonOtelFastify implements ILogger {
-    logger: Logger | null;
-    consoleLogger: winston.Logger;
-    level: 'info' | 'error' | 'debug' | 'fatal' | 'warn';
-    private otelEnabled;
-    constructor();
-    private bodyIsFastifyRequest;
-    private bodyIsFastifyReply;
-    private buildMessage;
-    private logMessage;
-    info(body: string | {
-        req?: FastifyRequest;
-        res?: FastifyReply;
-    }): void;
-    error(body: string | {
-        req?: FastifyRequest;
-        res?: FastifyReply;
-    }): void;
-    debug(body: string | {
-        req?: FastifyRequest;
-        res?: FastifyReply;
-    }): void;
-    fatal(body: string | {
-        req?: FastifyRequest;
-        res?: FastifyReply;
-    }): void;
-    warn(body: string | {
-        req?: FastifyRequest;
-        res?: FastifyReply;
-    }): void;
-    trace(message: string): void;
-    child(): WinstonOtelFastify;
+interface ILogBuilder {
+    buildStartMessage(context: BaseExecutionContext): string;
+    buildStartLogData(context: BaseExecutionContext, args: any[]): Record<string, any>;
+    buildSuccessMessage(context: BaseExecutionContext): string;
+    buildSuccessLogData(context: BaseExecutionContext, durationMs: number): Record<string, any>;
+    buildErrorMessage(context: BaseExecutionContext): string;
+    buildErrorLogData(context: BaseExecutionContext, durationMs: number, error: Error): Record<string, any>;
 }
-
-declare class OpenTelemetry {
-    private readonly env;
-    sdk: NodeSDK;
-    constructor(env: Record<string, any>);
-    startSdk(): void;
-    shutdown(): Promise<void>;
+interface IInstrumentationStrategy {
+    instrumentMethod(originalMethod: (...args: any[]) => any, instance: any, context: BaseExecutionContext): (...args: any[]) => any;
 }
-
-declare function Span(): MethodDecorator;
-
-interface ITracerGateway {
-    addEvent(name: string, attributes?: Record<string, any>): void;
-    setAttribute(key: string, value: string | number | boolean): void;
+declare class Tracer {
+    private static instance;
+    static getTracer(): ReturnType<typeof trace.getTracer>;
 }
-
-declare class TracerGatewayOpentelemetry implements ITracerGateway {
-    addEvent(name: string, attributes?: Record<string, any>): void;
-    setAttribute(key: string, value: string | number | boolean): void;
+declare class Metrics {
+    private static instance;
+    static getMetrics(): IMetricsManager;
+}
+declare abstract class BaseFullInstrumentationStrategy implements IInstrumentationStrategy {
+    protected readonly tracer: ReturnType<typeof trace.getTracer>;
+    protected readonly metrics: IMetricsManager;
+    protected readonly metricsRecorder: IMetricsRecorder;
+    protected readonly spanBuilder: ISpanBuilder;
+    protected readonly logBuilder: ILogBuilder;
+    constructor(tracer: ReturnType<typeof trace.getTracer>, metrics: IMetricsManager, metricsRecorder: IMetricsRecorder, spanBuilder: ISpanBuilder, logBuilder: ILogBuilder);
+    instrumentMethod(originalMethod: (...args: any[]) => any, instance: any, context: BaseExecutionContext): (...args: any[]) => any;
+    private recordSuccess;
+    private logSuccess;
+    private recordFailure;
+    private logError;
+    private logOperationStart;
 }
+declare abstract class BaseLogsOnlyInstrumentationStrategy implements IInstrumentationStrategy {
+    protected readonly logBuilder: ILogBuilder;
+    constructor(logBuilder: ILogBuilder);
+    instrumentMethod(originalMethod: (...args: any[]) => any, instance: any, context: BaseExecutionContext): (...args: any[]) => any;
+    private logOperationStart;
+    private logSuccess;
+    private logError;
+}
+declare function createTimer(): Timer;
+declare function normalizeError(error: unknown): Error;
+declare function roundDuration(durationMs: number): number;
+declare function sanitizeArgs(args: any[]): any[];
+declare function resolveLogger(): any;
+declare function copyReflectMetadata(source: any, target: any): void;
+declare function preserveClassName(target: any, className: string): void;
+declare function getInstrumentableMethods(instance: object): string[];
+declare function instrumentInstanceMethods(instance: object, contextName: string, logger: any, strategy: IInstrumentationStrategy, createContext: (operation: string, logger?: any) => BaseExecutionContext): void;
+
+type InstrumentationOptions = {
+    serviceName?: string;
+};
+declare function Instrumentation(options?: InstrumentationOptions): <T extends {
+    new (...args: any[]): object;
+}>(constructor: T) => T;
+
+type RepositoryOtelOptions = {
+    dbSystem?: string;
+};
+declare function RepositoryInstrumentation(options?: RepositoryOtelOptions): <T extends {
+    new (...args: any[]): object;
+}>(constructor: T) => T;
 
-export { AggregateObjectRoot, AggregateRoot, BaseController, CommonDTO, ContextError, Controller, CreateCommonDTO, DependencyContainer, DiscordNotifier, DtoResponsePagination, Entity, EntityObject, ExpressAdapter, FastifyAdapter, GlobalErrorHandler, IErrorNotifier, IHealthCheckDB, IHttp, ILogger, ITracerGateway, Inject, MethodType, MiddlewareFunction, NotPagination, NotificationErrorInMemory, NotificationFactory, OpenTelemetry, Optional, Pagination, Replace, Request, RequestHttp, Response, SentryNotifier, Span, TracerGatewayOpentelemetry, UniqueEntityId, UniqueObjectId, ValueObject, WatchedList, WinstonOtelFastify, ZodSchema, baseEnvSchema, getTakeAndSkip, zodValidator };
+export { AggregateObjectRoot, AggregateRoot, BaseController, BaseExecutionContext, BaseFullInstrumentationStrategy, BaseLogsOnlyInstrumentationStrategy, CommonDTO, ContextError, Controller, CreateCommonDTO, DependencyContainer, DtoResponsePagination, Entity, EntityObject, FastifyAdapter, GlobalListener, IHealthCheckDB, IHttp, IInstrumentationStrategy, ILogBuilder, ILogger, IMetricsManager, IMetricsRecorder, ISpanBuilder, Inject, Instrumentation, LogParams, Logger, MethodType, Metrics, MetricsManager, MiddlewareFunction, NotPagination, NullSpan, OTEL_ENABLED, Optional, OtelManager, Pagination, Replace, RepositoryInstrumentation, Request, RequestHttp, Response, SpanManager, TRACER_NAME, TRACER_VERSION, Timer, Tracer, UniqueEntityId, UniqueObjectId, ValueObject, WatchedList, ZodSchema, baseEnvSchema, context, copyReflectMetadata, createTimer, getContext, getInstrumentableMethods, getTakeAndSkip, instrumentInstanceMethods, normalizeError, preserveClassName, resolveLogger, roundDuration, sanitizeArgs, zodValidator };