@qlibs/apm 0.1.1

package/README.md

@@ -0,0 +1,151 @@
+# @qlibs/apm
+
+APM for NestJS apps: structured logging, distributed tracing, and error
+monitoring, built on [OpenTelemetry](https://opentelemetry.io/) (OTLP) +
+[Winston](https://github.com/winstonjs/winston).
+
+It is vendor-neutral: point `OTEL_EXPORTER_OTLP_ENDPOINT` at **SigNoz**,
+**Elastic APM Server** (has native OTLP ingestion), **Jaeger**, **Grafana
+Tempo**, or any generic **OpenTelemetry Collector** — no code changes needed,
+only env vars. If you don't set an endpoint, the app runs exactly as before
+with zero overhead (tracing/remote-log transports are simply skipped).
+
+What gets traced automatically (no business-logic changes required):
+- Inbound HTTP requests (Express/Nest)
+- Outbound HTTP calls (axios, fetch, node `http`/`https`)
+- Postgres queries (instruments the `pg` driver, so Sequelize/TypeORM queries show up too)
+- Redis (`ioredis` and `redis` clients)
+- RabbitMQ (`amqplib` publish/consume)
+
+Metrics (RED dashboards — latency, error rate, throughput) are intentionally
+**not** exported separately: SigNoz and Elastic APM both derive these from
+trace data automatically. If you need custom business metrics later, add an
+`@opentelemetry/sdk-metrics` + OTLP metrics exporter next to `tracing.ts` —
+the config/resource plumbing here already gives you everything needed to
+wire that in.
+
+## Install
+
+```bash
+yarn add @qlibs/apm
+```
+
+`@nestjs/common` and `rxjs` are peer dependencies (your Nest app already has
+them). Everything else (OpenTelemetry packages, Winston) ships as a real
+dependency of this package.
+
+## Usage
+
+1. **`main.ts`** — add as the literal first import, before anything else
+   (`module-alias/register`, `@nestjs/core`, etc. — the OTel SDK instruments
+   `http`/`pg`/`ioredis`/`amqplib` by patching them at require-time, so
+   anything imported earlier is invisible to tracing):
+   ```ts
+   import '@qlibs/apm/tracing';
+   import { NestFactory } from '@nestjs/core';
+   import { ApmLoggerService, ApmLoggingInterceptor, ApmExceptionFilter } from '@qlibs/apm';
+   // ...
+
+   async function bootstrap() {
+     const app = await NestFactory.create(AppModule, { bufferLogs: true });
+     app.useLogger(app.get(ApmLoggerService));
+     app.useGlobalInterceptors(new ApmLoggingInterceptor());
+     app.useGlobalFilters(new ApmExceptionFilter()); // skip if you have your own filter — see step 3
+     // ...
+   }
+   ```
+2. **`app.module.ts`** — add `ApmModule` to `imports` (makes `ApmLoggerService`
+   injectable into your own providers via constructor injection).
+3. **If your app already has a custom exception filter**, don't register
+   `ApmExceptionFilter`. Instead add one line to the existing filter's `catch()`:
+   ```ts
+   import { recordException } from '@qlibs/apm';
+   // inside catch(ex, host) { ... }
+   recordException(ex, 'YourFilterName');
+   ```
+4. **Env vars**: copy the block below into your project's env file and adjust
+   `APM_SERVICE_NAME`.
+
+## Env var reference
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `APM_ENABLED` | `true` | Master switch. `false` fully disables tracing + remote log transports (console logging still works). |
+| `APM_SERVICE_NAME` | `ats-be` | Service name shown in traces/logs — set per app, e.g. `my-app-api`. |
+| `APM_ENVIRONMENT` | `NODE_ENV` | `deployment.environment` resource attribute. |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | _(empty)_ | Base OTLP endpoint. Empty = tracing disabled. |
+| `OTEL_EXPORTER_OTLP_PROTOCOL` | `http/protobuf` | `http/protobuf` (port 4318 typically) or `grpc` (port 4317). Must match what your collector listens on. |
+| `OTEL_EXPORTER_OTLP_HEADERS` | _(empty)_ | Comma-separated `key=value` pairs, e.g. ingestion keys / auth tokens. |
+| `LOG_LEVEL` | `info` (`debug` locally) | Winston log level. |
+| `APM_LOG_FORMAT` | `pretty` locally, `json` otherwise | `pretty` = colorized console; `json` = structured stdout. |
+| `APM_LOG_TRANSPORT` | `stdout` | Comma list of `stdout`, `elasticsearch`, `otlp`. Multiple can be active at once. |
+| `ELASTICSEARCH_NODE` / `_USERNAME` / `_PASSWORD` / `_INDEX` | _(empty)_ | Only used when `APM_LOG_TRANSPORT` includes `elasticsearch`. |
+| `APM_HTTP_IGNORE_PATHS` | `/health,/favicon.ico` | Comma list of path prefixes excluded from the HTTP access log. |
+
+## Pointing at a specific backend
+
+**SigNoz** (self-hosted, OTLP-native collector):
+```
+OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
+OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
+```
+Traces, and — if `APM_LOG_TRANSPORT=otlp` — logs, both flow through the same
+collector endpoint. Nothing else to configure; SigNoz derives service
+dashboards (latency/error-rate/throughput) from the trace data.
+
+**Elastic APM Server / Elastic Cloud** (native OTLP ingestion since 8.x):
+```
+OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:8200
+OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
+OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer <secret-token>
+```
+For logs into plain Elasticsearch/Kibana (not via APM Server), use the
+`elasticsearch` transport instead:
+```
+APM_LOG_TRANSPORT=stdout,elasticsearch
+ELASTICSEARCH_NODE=https://localhost:9200
+ELASTICSEARCH_USERNAME=elastic
+ELASTICSEARCH_PASSWORD=changeme
+```
+
+**Generic OTel Collector / Jaeger / Tempo**: same as SigNoz — just point
+`OTEL_EXPORTER_OTLP_ENDPOINT` at the collector's OTLP receiver.
+
+**No collector running yet / local dev**: leave `OTEL_EXPORTER_OTLP_ENDPOINT`
+empty. Logs still print (pretty, to console); tracing and error-span
+recording are skipped with no crash and no retry noise.
+
+## Reference integration
+
+See [qbit-tech/ats-be](https://github.com/qbit-tech/ats-be) — `apps/base`,
+`apps/scheduler`, `apps/worker` all consume this package. `apps/base` is the
+worked example for wiring into a project that already has its own exception
+filter (`apps/base/src/core/output.filter.ts`); `apps/worker`/`apps/scheduler`
+are the simpler "no existing filter" case.
+
+## Troubleshooting
+
+- **No traces showing up**: confirm the app can reach `OTEL_EXPORTER_OTLP_ENDPOINT`
+  from wherever it's actually running (container networking — `localhost`
+  inside a container is not the host), and that `OTEL_EXPORTER_OTLP_PROTOCOL`
+  matches the port (4318 = http/protobuf, 4317 = grpc — sending http/protobuf
+  to a grpc-only port silently fails).
+- **Logs missing `trace_id`**: `trace_id`/`span_id` are only injected when
+  there's an active span — that requires `@qlibs/apm/tracing` to have
+  actually started (i.e. `OTEL_EXPORTER_OTLP_ENDPOINT` set) and the log call
+  to happen inside a traced context (an HTTP request, a traced RabbitMQ
+  handler, etc.).
+- **App fails to start after adding this**: check `@qlibs/apm/tracing`
+  really is the first import in `main.ts` — importing it after other modules
+  that require `pg`/`http`/etc. won't crash the app, but silently disables
+  instrumentation for those modules.
+
+## Development
+
+```bash
+yarn install
+yarn build   # compiles src/ -> dist/
+```
+
+Publishing is handled by CI (`.github/workflows/release.yml`) on push to
+`main`, or manually via `yarn release`.

package/dist/apm.config.d.ts

@@ -0,0 +1,30 @@
+export type LogFormat = 'pretty' | 'json';
+export type LogTransportKind = 'stdout' | 'elasticsearch' | 'otlp';
+export type OtlpProtocol = 'http/protobuf' | 'grpc';
+export interface ApmConfig {
+    enabled: boolean;
+    serviceName: string;
+    serviceVersion: string;
+    environment: string;
+    tracing: {
+        enabled: boolean;
+        otlpEndpoint?: string;
+        protocol: OtlpProtocol;
+        headers: Record<string, string>;
+    };
+    logging: {
+        level: string;
+        format: LogFormat;
+        transports: LogTransportKind[];
+        elasticsearch: {
+            node?: string;
+            username?: string;
+            password?: string;
+            index: string;
+        };
+    };
+    http: {
+        ignorePaths: string[];
+    };
+}
+export declare function getApmConfig(): ApmConfig;

package/dist/apm.config.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getApmConfig = getApmConfig;
+function parseBoolean(value, fallback) {
+    if (value === undefined || value === '')
+        return fallback;
+    return value.toLowerCase() === 'true';
+}
+function parseList(value) {
+    if (!value)
+        return [];
+    return value
+        .split(',')
+        .map((v) => v.trim())
+        .filter(Boolean);
+}
+function parseHeaders(value) {
+    const headers = {};
+    for (const pair of parseList(value)) {
+        const idx = pair.indexOf('=');
+        if (idx === -1)
+            continue;
+        headers[pair.slice(0, idx).trim()] = pair.slice(idx + 1).trim();
+    }
+    return headers;
+}
+let cachedConfig;
+function getApmConfig() {
+    if (cachedConfig)
+        return cachedConfig;
+    const env = process.env;
+    const nodeEnv = env.NODE_ENV || 'local';
+    const otlpEndpoint = env.OTEL_EXPORTER_OTLP_ENDPOINT || undefined;
+    const transports = parseList(env.APM_LOG_TRANSPORT);
+    cachedConfig = {
+        enabled: parseBoolean(env.APM_ENABLED, true),
+        serviceName: env.APM_SERVICE_NAME || 'ats-be',
+        serviceVersion: env.APM_SERVICE_VERSION || '0.0.0',
+        environment: env.APM_ENVIRONMENT || nodeEnv,
+        tracing: {
+            enabled: parseBoolean(env.APM_TRACING_ENABLED, !!otlpEndpoint),
+            otlpEndpoint,
+            protocol: env.OTEL_EXPORTER_OTLP_PROTOCOL || 'http/protobuf',
+            headers: parseHeaders(env.OTEL_EXPORTER_OTLP_HEADERS),
+        },
+        logging: {
+            level: env.LOG_LEVEL || (nodeEnv === 'local' ? 'debug' : 'info'),
+            format: env.APM_LOG_FORMAT ||
+                (nodeEnv === 'local' || nodeEnv === 'development' ? 'pretty' : 'json'),
+            transports: transports.length ? transports : ['stdout'],
+            elasticsearch: {
+                node: env.ELASTICSEARCH_NODE || undefined,
+                username: env.ELASTICSEARCH_USERNAME || undefined,
+                password: env.ELASTICSEARCH_PASSWORD || undefined,
+                index: env.ELASTICSEARCH_INDEX || `${env.APM_SERVICE_NAME || 'ats-be'}-logs`,
+            },
+        },
+        http: {
+            ignorePaths: parseList(env.APM_HTTP_IGNORE_PATHS).length
+                ? parseList(env.APM_HTTP_IGNORE_PATHS)
+                : ['/health', '/favicon.ico'],
+        },
+    };
+    return cachedConfig;
+}

package/dist/apm.module.d.ts

@@ -0,0 +1,2 @@
+export declare class ApmModule {
+}

package/dist/apm.module.js

@@ -0,0 +1,21 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApmModule = void 0;
+const common_1 = require("@nestjs/common");
+const apm_logger_service_1 = require("./logger/apm-logger.service");
+let ApmModule = class ApmModule {
+};
+exports.ApmModule = ApmModule;
+exports.ApmModule = ApmModule = __decorate([
+    (0, common_1.Global)(),
+    (0, common_1.Module)({
+        providers: [apm_logger_service_1.ApmLoggerService],
+        exports: [apm_logger_service_1.ApmLoggerService],
+    })
+], ApmModule);

package/dist/filters/apm-exception.filter.d.ts

@@ -0,0 +1,4 @@
+import { ArgumentsHost, ExceptionFilter } from '@nestjs/common';
+export declare class ApmExceptionFilter implements ExceptionFilter {
+    catch(err: Error, host: ArgumentsHost): void;
+}

package/dist/filters/apm-exception.filter.js

@@ -0,0 +1,33 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApmExceptionFilter = void 0;
+const common_1 = require("@nestjs/common");
+const record_exception_1 = require("../record-exception");
+let ApmExceptionFilter = class ApmExceptionFilter {
+    catch(err, host) {
+        (0, record_exception_1.recordException)(err, 'ApmExceptionFilter');
+        const ctx = host.switchToHttp();
+        const response = ctx.getResponse();
+        if (!(response === null || response === void 0 ? void 0 : response.status))
+            return;
+        const status = err instanceof common_1.HttpException ? err.getStatus() : 500;
+        const body = err instanceof common_1.HttpException
+            ? err.getResponse()
+            : {
+                code: 'err_general',
+                message: 'Please contact our administrator',
+                errors: [],
+            };
+        response.status(status).json(body);
+    }
+};
+exports.ApmExceptionFilter = ApmExceptionFilter;
+exports.ApmExceptionFilter = ApmExceptionFilter = __decorate([
+    (0, common_1.Catch)()
+], ApmExceptionFilter);

package/dist/http/apm-logging.interceptor.d.ts

@@ -0,0 +1,4 @@
+import { CallHandler, ExecutionContext, NestInterceptor } from '@nestjs/common';
+export declare class ApmLoggingInterceptor implements NestInterceptor {
+    intercept(context: ExecutionContext, next: CallHandler): import("rxjs").Observable<any>;
+}

package/dist/http/apm-logging.interceptor.js

@@ -0,0 +1,60 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApmLoggingInterceptor = void 0;
+const common_1 = require("@nestjs/common");
+const rxjs_1 = require("rxjs");
+const api_1 = require("@opentelemetry/api");
+const apm_config_1 = require("../apm.config");
+const winston_instance_1 = require("../logger/winston.instance");
+let ApmLoggingInterceptor = class ApmLoggingInterceptor {
+    intercept(context, next) {
+        if (context.getType() !== 'http') {
+            return next.handle();
+        }
+        const request = context.switchToHttp().getRequest();
+        const { method, originalUrl, url, ip } = request;
+        const path = originalUrl || url;
+        const ignorePaths = (0, apm_config_1.getApmConfig)().http.ignorePaths;
+        if (ignorePaths.some((p) => path === null || path === void 0 ? void 0 : path.startsWith(p))) {
+            return next.handle();
+        }
+        const start = Date.now();
+        const span = api_1.trace.getActiveSpan();
+        const traceId = span === null || span === void 0 ? void 0 : span.spanContext().traceId;
+        return next.handle().pipe((0, rxjs_1.tap)({
+            next: () => {
+                const response = context.switchToHttp().getResponse();
+                winston_instance_1.winstonLogger.http(`${method} ${path} ${response.statusCode}`, {
+                    context: 'HTTP',
+                    method,
+                    path,
+                    statusCode: response.statusCode,
+                    durationMs: Date.now() - start,
+                    ip,
+                    trace_id: traceId,
+                });
+            },
+            error: (err) => {
+                winston_instance_1.winstonLogger.http(`${method} ${path} failed`, {
+                    context: 'HTTP',
+                    method,
+                    path,
+                    durationMs: Date.now() - start,
+                    ip,
+                    trace_id: traceId,
+                    error: err === null || err === void 0 ? void 0 : err.message,
+                });
+            },
+        }));
+    }
+};
+exports.ApmLoggingInterceptor = ApmLoggingInterceptor;
+exports.ApmLoggingInterceptor = ApmLoggingInterceptor = __decorate([
+    (0, common_1.Injectable)()
+], ApmLoggingInterceptor);

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from './apm.config';
+export * from './apm.module';
+export * from './record-exception';
+export * from './logger/apm-logger.service';
+export * from './http/apm-logging.interceptor';
+export * from './filters/apm-exception.filter';

package/dist/index.js

@@ -0,0 +1,22 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./apm.config"), exports);
+__exportStar(require("./apm.module"), exports);
+__exportStar(require("./record-exception"), exports);
+__exportStar(require("./logger/apm-logger.service"), exports);
+__exportStar(require("./http/apm-logging.interceptor"), exports);
+__exportStar(require("./filters/apm-exception.filter"), exports);

package/dist/logger/apm-logger.service.d.ts

@@ -0,0 +1,9 @@
+import { LoggerService } from '@nestjs/common';
+export declare class ApmLoggerService implements LoggerService {
+    log(message: any, context?: string): void;
+    error(message: any, trace?: string, context?: string): void;
+    warn(message: any, context?: string): void;
+    debug(message: any, context?: string): void;
+    verbose(message: any, context?: string): void;
+    private stringify;
+}

package/dist/logger/apm-logger.service.js

@@ -0,0 +1,44 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApmLoggerService = void 0;
+const common_1 = require("@nestjs/common");
+const winston_instance_1 = require("./winston.instance");
+let ApmLoggerService = class ApmLoggerService {
+    log(message, context) {
+        winston_instance_1.winstonLogger.info(this.stringify(message), { context });
+    }
+    error(message, trace, context) {
+        winston_instance_1.winstonLogger.error(this.stringify(message), { trace, context });
+    }
+    warn(message, context) {
+        winston_instance_1.winstonLogger.warn(this.stringify(message), { context });
+    }
+    debug(message, context) {
+        winston_instance_1.winstonLogger.debug(this.stringify(message), { context });
+    }
+    verbose(message, context) {
+        winston_instance_1.winstonLogger.verbose(this.stringify(message), { context });
+    }
+    stringify(message) {
+        if (typeof message === 'string')
+            return message;
+        if (message instanceof Error)
+            return message.stack || message.message;
+        try {
+            return JSON.stringify(message);
+        }
+        catch (_a) {
+            return String(message);
+        }
+    }
+};
+exports.ApmLoggerService = ApmLoggerService;
+exports.ApmLoggerService = ApmLoggerService = __decorate([
+    (0, common_1.Injectable)()
+], ApmLoggerService);

package/dist/logger/otlp-log.transport.d.ts

@@ -0,0 +1,5 @@
+declare const OtlpLogTransport_base: any;
+export declare class OtlpLogTransport extends OtlpLogTransport_base {
+    log(info: Record<string, any>, callback: () => void): void;
+}
+export {};

package/dist/logger/otlp-log.transport.js

@@ -0,0 +1,102 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OtlpLogTransport = void 0;
+const Transport = __importStar(require("winston-transport"));
+const api_1 = require("@opentelemetry/api");
+const apm_config_1 = require("../apm.config");
+const SEVERITY_MAP = {
+    error: { number: 17, text: 'ERROR' },
+    warn: { number: 13, text: 'WARN' },
+    info: { number: 9, text: 'INFO' },
+    http: { number: 9, text: 'INFO' },
+    verbose: { number: 5, text: 'DEBUG' },
+    debug: { number: 5, text: 'DEBUG' },
+    silly: { number: 1, text: 'TRACE' },
+};
+let otelLogger;
+function getOtelLogger() {
+    if (otelLogger)
+        return otelLogger;
+    const config = (0, apm_config_1.getApmConfig)();
+    const { LoggerProvider, BatchLogRecordProcessor, } = require('@opentelemetry/sdk-logs');
+    const { OTLPLogExporter } = require('@opentelemetry/exporter-logs-otlp-http');
+    const { resourceFromAttributes } = require('@opentelemetry/resources');
+    const { ATTR_SERVICE_NAME } = require('@opentelemetry/semantic-conventions');
+    const base = (config.tracing.otlpEndpoint || '').replace(/\/$/, '');
+    const exporter = new OTLPLogExporter({
+        url: `${base}/v1/logs`,
+        headers: config.tracing.headers,
+    });
+    const provider = new LoggerProvider({
+        resource: resourceFromAttributes({
+            [ATTR_SERVICE_NAME]: config.serviceName,
+        }),
+    });
+    provider.addLogRecordProcessor(new BatchLogRecordProcessor(exporter));
+    otelLogger = provider.getLogger(config.serviceName);
+    return otelLogger;
+}
+class OtlpLogTransport extends Transport {
+    log(info, callback) {
+        setImmediate(() => this.emit('logged', info));
+        const { level, message } = info, rest = __rest(info, ["level", "message"]);
+        const severity = SEVERITY_MAP[level] || SEVERITY_MAP.info;
+        try {
+            getOtelLogger().emit({
+                severityNumber: severity.number,
+                severityText: severity.text,
+                body: message,
+                attributes: rest,
+                context: api_1.context.active(),
+            });
+        }
+        catch (_a) {
+        }
+        callback();
+    }
+}
+exports.OtlpLogTransport = OtlpLogTransport;

package/dist/logger/trace-context.format.d.ts

@@ -0,0 +1,2 @@
+import * as winston from 'winston';
+export declare const traceContextFormat: winston.Logform.FormatWrap;

package/dist/logger/trace-context.format.js

@@ -0,0 +1,47 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.traceContextFormat = void 0;
+const winston = __importStar(require("winston"));
+const api_1 = require("@opentelemetry/api");
+exports.traceContextFormat = winston.format((info) => {
+    const span = api_1.trace.getActiveSpan();
+    if (span) {
+        const ctx = span.spanContext();
+        info.trace_id = ctx.traceId;
+        info.span_id = ctx.spanId;
+    }
+    return info;
+});

package/dist/logger/winston.instance.d.ts

@@ -0,0 +1,2 @@
+import * as winston from 'winston';
+export declare const winstonLogger: winston.Logger;

package/dist/logger/winston.instance.js

@@ -0,0 +1,124 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.winstonLogger = void 0;
+const winston = __importStar(require("winston"));
+const apm_config_1 = require("../apm.config");
+const trace_context_format_1 = require("./trace-context.format");
+function buildConsoleTransport() {
+    const config = (0, apm_config_1.getApmConfig)();
+    const format = config.logging.format === 'pretty'
+        ? winston.format.combine((0, trace_context_format_1.traceContextFormat)(), winston.format.colorize(), winston.format.timestamp({ format: 'HH:mm:ss' }), winston.format.printf((_a) => {
+            var { timestamp, level, message, context, trace_id } = _a, meta = __rest(_a, ["timestamp", "level", "message", "context", "trace_id"]);
+            const ctx = context ? ` [${context}]` : '';
+            const trace = trace_id ? ` (trace=${trace_id})` : '';
+            const extra = Object.keys(meta).length
+                ? ` ${JSON.stringify(meta)}`
+                : '';
+            return `${timestamp} ${level}${ctx} ${message}${trace}${extra}`;
+        }))
+        : winston.format.combine((0, trace_context_format_1.traceContextFormat)(), winston.format.timestamp(), winston.format.json());
+    return new winston.transports.Console({ format });
+}
+function buildElasticsearchTransport() {
+    const config = (0, apm_config_1.getApmConfig)();
+    if (!config.logging.elasticsearch.node) {
+        console.warn('[apm] APM_LOG_TRANSPORT includes "elasticsearch" but ELASTICSEARCH_NODE is not set — skipping.');
+        return undefined;
+    }
+    const { ElasticsearchTransport } = require('winston-elasticsearch');
+    return new ElasticsearchTransport({
+        level: config.logging.level,
+        indexPrefix: config.logging.elasticsearch.index,
+        clientOpts: {
+            node: config.logging.elasticsearch.node,
+            auth: config.logging.elasticsearch.username &&
+                config.logging.elasticsearch.password
+                ? {
+                    username: config.logging.elasticsearch.username,
+                    password: config.logging.elasticsearch.password,
+                }
+                : undefined,
+        },
+        format: winston.format.combine((0, trace_context_format_1.traceContextFormat)(), winston.format.json()),
+    });
+}
+function buildOtlpTransport() {
+    const config = (0, apm_config_1.getApmConfig)();
+    if (!config.tracing.otlpEndpoint) {
+        console.warn('[apm] APM_LOG_TRANSPORT includes "otlp" but OTEL_EXPORTER_OTLP_ENDPOINT is not set — skipping.');
+        return undefined;
+    }
+    const { OtlpLogTransport } = require('./otlp-log.transport');
+    return new OtlpLogTransport({ level: config.logging.level });
+}
+function buildTransports() {
+    const config = (0, apm_config_1.getApmConfig)();
+    const transports = [];
+    for (const kind of config.logging.transports) {
+        if (kind === 'stdout')
+            transports.push(buildConsoleTransport());
+        else if (kind === 'elasticsearch') {
+            const t = buildElasticsearchTransport();
+            if (t)
+                transports.push(t);
+        }
+        else if (kind === 'otlp') {
+            const t = buildOtlpTransport();
+            if (t)
+                transports.push(t);
+        }
+    }
+    if (transports.length === 0)
+        transports.push(buildConsoleTransport());
+    return transports;
+}
+const config = (0, apm_config_1.getApmConfig)();
+exports.winstonLogger = winston.createLogger({
+    level: config.logging.level,
+    defaultMeta: { service: config.serviceName, environment: config.environment },
+    transports: buildTransports(),
+});

package/dist/record-exception.d.ts

@@ -0,0 +1 @@
+export declare function recordException(err: unknown, context?: string): void;

package/dist/record-exception.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recordException = recordException;
+const api_1 = require("@opentelemetry/api");
+const winston_instance_1 = require("./logger/winston.instance");
+function recordException(err, context) {
+    const error = err instanceof Error ? err : new Error(String(err));
+    const span = api_1.trace.getActiveSpan();
+    if (span) {
+        span.recordException(error);
+        span.setStatus({ code: api_1.SpanStatusCode.ERROR, message: error.message });
+    }
+    winston_instance_1.winstonLogger.error(error.message, {
+        context: context || 'ExceptionFilter',
+        stack: error.stack,
+        name: error.name,
+    });
+}

package/dist/tracing.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tracing.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const apm_config_1 = require("./apm.config");
+const config = (0, apm_config_1.getApmConfig)();
+if (config.enabled && config.tracing.enabled && config.tracing.otlpEndpoint) {
+    const { NodeSDK } = require('@opentelemetry/sdk-node');
+    const { getNodeAutoInstrumentations, } = require('@opentelemetry/auto-instrumentations-node');
+    const { OTLPTraceExporter, } = require('@opentelemetry/exporter-trace-otlp-http');
+    const { resourceFromAttributes } = require('@opentelemetry/resources');
+    const { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION, } = require('@opentelemetry/semantic-conventions');
+    const traceExporter = new OTLPTraceExporter({
+        url: config.tracing.protocol === 'grpc'
+            ? config.tracing.otlpEndpoint
+            : `${config.tracing.otlpEndpoint.replace(/\/$/, '')}/v1/traces`,
+        headers: config.tracing.headers,
+    });
+    const sdk = new NodeSDK({
+        resource: resourceFromAttributes({
+            [ATTR_SERVICE_NAME]: config.serviceName,
+            [ATTR_SERVICE_VERSION]: config.serviceVersion,
+            'deployment.environment': config.environment,
+        }),
+        traceExporter,
+        instrumentations: [
+            getNodeAutoInstrumentations({
+                '@opentelemetry/instrumentation-fs': { enabled: false },
+            }),
+        ],
+    });
+    sdk.start();
+    const shutdown = () => {
+        sdk
+            .shutdown()
+            .catch((err) => console.error('Error shutting down OTel SDK', err))
+            .finally(() => process.exit(0));
+    };
+    process.on('SIGTERM', shutdown);
+    process.on('SIGINT', shutdown);
+    console.info(`[apm] tracing enabled -> ${config.tracing.otlpEndpoint} (service: ${config.serviceName})`);
+}
+else {
+    console.info('[apm] tracing disabled (set OTEL_EXPORTER_OTLP_ENDPOINT to enable)');
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@qlibs/apm",
+  "version": "0.1.1",
+  "description": "Vendor-neutral APM for NestJS: OpenTelemetry tracing (OTLP) + structured logging + error monitoring. Works with SigNoz, Elastic/Kibana, Jaeger, or any OTel collector.",
+  "author": "QBIT Developer",
+  "license": "MIT",
+  "url": "https://github.com/qbit-tech/qlibs-apm",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "/dist",
+    "tracing.js",
+    "tracing.d.ts"
+  ],
+  "scripts": {
+    "build": "rimraf -rf dist && tsc -p tsconfig.json",
+    "format": "prettier --write \"**/*.ts\"",
+    "lint": "eslint \"{src,test}/**/*.ts\" --fix",
+    "prepublish:npm": "npm run build",
+    "publish:npm": "npm publish --access public",
+    "prepublish:next": "npm run build",
+    "publish:next": "npm publish --access public --tag next",
+    "prerelease": "npm run build",
+    "release": "release-it",
+    "prepare": "husky install && npm run build"
+  },
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/api-logs": "^0.221.0",
+    "@opentelemetry/auto-instrumentations-node": "^0.79.0",
+    "@opentelemetry/exporter-logs-otlp-http": "^0.221.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.221.0",
+    "@opentelemetry/resources": "^2.10.0",
+    "@opentelemetry/sdk-logs": "^0.221.0",
+    "@opentelemetry/sdk-node": "^0.221.0",
+    "@opentelemetry/semantic-conventions": "^1.43.0",
+    "winston": "^3.19.0",
+    "winston-elasticsearch": "^0.19.0"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^9.0.0 || ^10.0.0 || ^11.0.0",
+    "rxjs": "^7.0.0"
+  },
+  "devDependencies": {
+    "@nestjs/common": "^10.0.0",
+    "@types/express": "^4.17.17",
+    "@types/node": "^20.3.1",
+    "express": "^4.19.2",
+    "husky": "^8.0.3",
+    "reflect-metadata": "^0.1.13",
+    "release-it": "16.1.5",
+    "rimraf": "5.0.1",
+    "rxjs": "^7.8.1",
+    "typescript": "^5.1.3"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org"
+  }
+}

package/tracing.d.ts

@@ -0,0 +1,2 @@
+// Side-effect-only module — see tracing.js / dist/tracing.d.ts.
+export {};

package/tracing.js

@@ -0,0 +1,4 @@
+// Shim so consumers can `import '@qlibs/apm/tracing'` directly (needed since
+// this must be the very first import in main.ts, before the rest of the
+// package's barrel). See README.md.
+require('./dist/tracing');