@bymax-one/nest-logger 1.2.0 → 1.2.2

package/dist/server/index.d.cts

@@ -96,6 +96,99 @@ interface ServiceMetadata {
     readonly name: string;
     /** OTel attribute `service.version` — semver, commit SHA, or build tag. */
     readonly version: string;
+    /**
+     * OTel attribute `service.namespace` (**Stable**) — the group the service
+     * belongs to, e.g. a team, a bounded context or a tenant of the platform.
+     * Two services may share a `name` as long as their namespaces differ.
+     */
+    readonly namespace?: string;
+    /**
+     * OTel attribute `service.instance.id` (**Stable**) — identifies ONE running
+     * instance, so the triplet (namespace, name, instanceId) is globally unique.
+     *
+     * The library never generates this. A value minted here would be the logger's
+     * rather than the OpenTelemetry Resource's, so logs and traces would disagree
+     * about which instance served a request, and it would change on every restart
+     * while looking authoritative. Supply it from the platform — the Kubernetes
+     * pod UID, the ECS task ARN, the VM instance id — or through
+     * `OTEL_RESOURCE_ATTRIBUTES`, which is the same source the SDK reads.
+     *
+     * Treat it as HIGH cardinality: fine as a log field, not as a metric label.
+     */
+    readonly instanceId?: string;
+    /**
+     * OTel attribute `deployment.environment.name` (**Stable**) — `production`,
+     * `staging`, and so on. Falls back to `NODE_ENV` when omitted.
+     *
+     * The older `deployment.environment` spelling is **Deprecated** in the
+     * semantic conventions and is never emitted.
+     */
+    readonly environment?: string;
+}
+/**
+ * Service identity after precedence has been applied.
+ *
+ * Distinct from {@link ServiceMetadata} because the optional fields here mean
+ * "resolved to nothing" rather than "not configured": every source — options,
+ * `OTEL_SERVICE_NAME`, `OTEL_RESOURCE_ATTRIBUTES`, `NODE_ENV` — has already been
+ * consulted, and a field still absent will not appear on any entry.
+ */
+interface ResolvedServiceMetadata {
+    /** `service.name`, always present. */
+    name: string;
+    /** `service.version`, always present. */
+    version: string;
+    /** `service.namespace`, when any source supplied one. */
+    namespace?: string;
+    /** `service.instance.id`, when any source supplied one. */
+    instanceId?: string;
+    /** `deployment.environment.name`, when any source supplied one. */
+    environment?: string;
+}
+/**
+ * The `service` block as it appears in an EMITTED record, under the default
+ * `resourceFormat: 'nested'`.
+ *
+ * Distinct from {@link ServiceMetadata} on purpose, and the distinction is the
+ * kind of defect this library has already been bitten by once: a published type
+ * that describes something the runtime never emits. `ServiceMetadata` is what a
+ * consumer CONFIGURES — flat option names like `instanceId` and `environment`.
+ * What comes out is the flattened OTel attribute path: `service.instance.id`
+ * nests as `service: { instance: { id } }`, and the environment is not under
+ * `service` at all, it is `deployment.environment.name`. Typing the emitted
+ * record with the configuration interface would advertise `entry.service.instanceId`
+ * to every consumer, and that property does not exist on any entry.
+ *
+ * Under `resourceFormat: 'flat'` these values appear as dotted top-level keys
+ * (`"service.instance.id"`), which {@link LogEntry}'s index signature already
+ * admits — a flat record simply has no `service` object.
+ */
+interface EmittedServiceResource {
+    /** OTel `service.name`. */
+    readonly name: string;
+    /** OTel `service.version`. */
+    readonly version: string;
+    /** OTel `service.namespace`, when resolved. */
+    readonly namespace?: string;
+    /** OTel `service.instance.id`, nested as the attribute path spells it. */
+    readonly instance?: {
+        readonly id: string;
+    };
+    /** Consumer-supplied extras carried through from the `service` option. */
+    readonly [key: string]: unknown;
+}
+/**
+ * The `deployment` block as it appears in an EMITTED record under
+ * `resourceFormat: 'nested'`, carrying `deployment.environment.name`.
+ *
+ * Absent entirely when no source resolved an environment. The deprecated
+ * `deployment.environment` spelling is never emitted.
+ */
+interface EmittedDeploymentResource {
+    /** OTel `deployment.environment.name`, flattened from its attribute path. */
+    readonly environment: {
+        readonly name: string;
+    };
 }
 
 /**
@@ -191,6 +284,52 @@ interface BymaxLoggerModuleOptions {
      *     path-matching semantics; expect it to be removed in a future major.
      */
     redactStrategy?: 'names' | 'paths';
+    /**
+     * Shape of the resource/service identity on every entry. Default `'nested'`.
+     *
+     *   - `'nested'` — `{ service: { name, version, namespace, instance: { id } },
+     *     deployment: { environment: { name } } }`. The historical shape, extended;
+     *     no existing query breaks.
+     *   - `'flat'` — the dotted OTel attribute names verbatim (`service.name`,
+     *     `service.instance.id`, `deployment.environment.name`), which is what a
+     *     collector mapping log fields onto resource attributes reads directly.
+     *
+     * Both carry the same values; only the key shape differs.
+     */
+    resourceFormat?: 'nested' | 'flat';
+    /**
+     * Field carrying the machine-readable event name, mirroring `logKey`.
+     * Default `'event.name'`; `false` emits nothing.
+     *
+     * `logKey` stays exactly as it is — this is additive, never a rename.
+     *
+     * The value is meant to be mapped onto the **`EventName`** field of the
+     * OpenTelemetry LogRecord, which is Stable in the Logs Data Model. Note that
+     * the same-named `event.name` *attribute* is Deprecated in the semantic
+     * conventions precisely because the value belongs in that top-level field
+     * instead; the key here is the JSON carrier, not an OTLP attribute. The name is
+     * configurable so a pipeline that maps a different key can use it.
+     *
+     * Keep event names LOW cardinality — `payment.failed`, not
+     * `payment.failed.918231781`. Identifiers belong in their own fields.
+     */
+    eventNameField?: string | false;
+    /**
+     * Shape of the error fields on an entry. Default `'pino'`.
+     *
+     *   - `'pino'`   — only the legacy `err` object (`type`, `message`, `stack`,
+     *     plus the `cause` chain). What every existing query reads.
+     *   - `'semconv'` — only the OpenTelemetry attributes: `exception.type`,
+     *     `exception.message`, `exception.stacktrace` and `error.type`. The `err`
+     *     object is removed, so this is an explicit migration, never a default.
+     *   - `'both'`    — both shapes on the same entry. Recommended while moving
+     *     dashboards over: nothing breaks, and the new fields are already there.
+     *
+     * All four attributes are **Stable** in Semantic Conventions v1.44.0.
+     * `error.type` carries the error's class name and is LOW cardinality by
+     * construction — never a message, never an identifier.
+     */
+    errorFormat?: 'pino' | 'semconv' | 'both';
     /** Censor string written in place of redacted values. Default: `[REDACTED]`. */
     redactCensor?: string;
     /** Disable default redact paths (use with caution). Default: false. */
@@ -393,6 +532,11 @@ declare const RESERVED_LOG_KEYS_NOT_EMITTED: Readonly<{
      */
     readonly HTTP_REQUEST_COMPLETED: "reserved: superseded by the four status-specific terminal keys";
 }>;
+/**
+ * Strongly-typed union of every reserved log key value, derived from
+ * {@link RESERVED_LOG_KEYS}. Use this type to constrain log-key arguments.
+ */
+type ReservedLogKey = (typeof RESERVED_LOG_KEYS)[keyof typeof RESERVED_LOG_KEYS];
 
 /**
  * Name-based recursive redaction.
@@ -598,17 +742,6 @@ declare class PinoLoggerService implements LoggerService, OnApplicationShutdown
      * this service has no additional teardown work.
      */
     onApplicationShutdown(): void;
-    /**
-     * Serialize an Error into a plain, log-safe object matching Pino's built-in
-     * `err` serializer shape (`type`, `message`, `stack`).
-     *
-     * Reads `error.name` (NOT `error.constructor.name`) for `type`: native
-     * subclasses set `name` to their class name, and a sanitized plain-object error
-     * (from `sanitizeError`) carries the real class name on `name` — whereas its
-     * `constructor.name` would be the unhelpful `'Object'`, breaking `err.type`
-     * dashboards for every exception logged through `HttpExceptionFilter`.
-     */
-    private serializeError;
     /** Resolve the context: last string param wins, else the instance context. */
     private resolveContext;
     /** Emit a structured payload at info or warn level. */
@@ -1179,8 +1312,25 @@ interface LogEntry {
     msg: string;
     /** Convention key — `MODULE_ACTION_RESULT` format. */
     logKey?: string;
-    /** Service metadata snapshot — see {@link ServiceMetadata}. */
-    service?: ServiceMetadata;
+    /**
+     * OTel event name derived from {@link logKey} (`PAYMENT_FAILED` →
+     * `payment.failed`), emitted on structured calls unless `eventNameField` is
+     * `false`. Declared explicitly because the index signature below would type
+     * it `unknown`: a documented field a consumer cannot read without a cast is
+     * not really published.
+     *
+     * The key is configurable, so a renamed field arrives through the index
+     * signature instead — this declaration describes the default only.
+     */
+    'event.name'?: string;
+    /**
+     * Service identity as EMITTED — see {@link EmittedServiceResource}. Not the
+     * configuration shape: `service.instance.id` nests, and the environment lives
+     * under `deployment`, not here.
+     */
+    service?: EmittedServiceResource;
+    /** Deployment identity as emitted — see {@link EmittedDeploymentResource}. */
+    deployment?: EmittedDeploymentResource;
     /** Optional NestJS context (typically the emitting class name). */
     context?: string;
     /** Optional correlation IDs propagated via AsyncLocalStorage. */
@@ -1223,4 +1373,4 @@ interface LogEntry {
  */
 declare const LOG_KEYS_CONVENTION_REGEX: RegExp;
 
-export { BymaxLoggerModule, type BymaxLoggerModuleAsyncOptions, type BymaxLoggerModuleOptions, type BymaxLoggerModuleOptionsFactory, DEFAULT_REDACT_PATHS, DefaultStdoutDestination, HttpExceptionFilter, HttpLoggingInterceptor, type HttpOptions, type ILogDestination, type IncomingHeaders, InjectLogger, LOGGER_DESTINATIONS_TOKEN, LOGGER_OPTIONS_TOKEN, LOGGER_PINO_INSTANCE_TOKEN, LOG_CONTEXT_METADATA_KEY, LOG_CONTEXT_TOKEN, LOG_KEYS_CONVENTION_REGEX, LogContext, type LogContext$1 as LogContextBag, LogContextService, type LogEntry, type LogLevel, LogPerformance, type LoggableRequest, type LoggableResponse, type NextHandler, type OtelOptions, PINO_LEVEL_NAMES, PINO_LEVEL_NUMBERS, PinoLoggerService, PrettyDevDestination, RESERVED_LOG_KEYS, RESERVED_LOG_KEYS_NOT_EMITTED, RequestIdMiddleware, type ResolvedBymaxLoggerModuleOptions, type ServiceMetadata, applyRequestIdMiddleware };
+export { BymaxLoggerModule, type BymaxLoggerModuleAsyncOptions, type BymaxLoggerModuleOptions, type BymaxLoggerModuleOptionsFactory, DEFAULT_REDACT_PATHS, DefaultStdoutDestination, type EmittedDeploymentResource, type EmittedServiceResource, HttpExceptionFilter, HttpLoggingInterceptor, type HttpOptions, type ILogDestination, type IncomingHeaders, InjectLogger, LOGGER_DESTINATIONS_TOKEN, LOGGER_OPTIONS_TOKEN, LOGGER_PINO_INSTANCE_TOKEN, LOG_CONTEXT_METADATA_KEY, LOG_CONTEXT_TOKEN, LOG_KEYS_CONVENTION_REGEX, LogContext, type LogContext$1 as LogContextBag, LogContextService, type LogEntry, type LogLevel, LogPerformance, type LoggableRequest, type LoggableResponse, type NextHandler, type OtelOptions, PINO_LEVEL_NAMES, PINO_LEVEL_NUMBERS, PinoLoggerService, PrettyDevDestination, RESERVED_LOG_KEYS, RESERVED_LOG_KEYS_NOT_EMITTED, RequestIdMiddleware, type ReservedLogKey, type ResolvedBymaxLoggerModuleOptions, type ResolvedServiceMetadata, type ServiceMetadata, applyRequestIdMiddleware };

package/dist/server/index.d.ts

@@ -96,6 +96,99 @@ interface ServiceMetadata {
     readonly name: string;
     /** OTel attribute `service.version` — semver, commit SHA, or build tag. */
     readonly version: string;
+    /**
+     * OTel attribute `service.namespace` (**Stable**) — the group the service
+     * belongs to, e.g. a team, a bounded context or a tenant of the platform.
+     * Two services may share a `name` as long as their namespaces differ.
+     */
+    readonly namespace?: string;
+    /**
+     * OTel attribute `service.instance.id` (**Stable**) — identifies ONE running
+     * instance, so the triplet (namespace, name, instanceId) is globally unique.
+     *
+     * The library never generates this. A value minted here would be the logger's
+     * rather than the OpenTelemetry Resource's, so logs and traces would disagree
+     * about which instance served a request, and it would change on every restart
+     * while looking authoritative. Supply it from the platform — the Kubernetes
+     * pod UID, the ECS task ARN, the VM instance id — or through
+     * `OTEL_RESOURCE_ATTRIBUTES`, which is the same source the SDK reads.
+     *
+     * Treat it as HIGH cardinality: fine as a log field, not as a metric label.
+     */
+    readonly instanceId?: string;
+    /**
+     * OTel attribute `deployment.environment.name` (**Stable**) — `production`,
+     * `staging`, and so on. Falls back to `NODE_ENV` when omitted.
+     *
+     * The older `deployment.environment` spelling is **Deprecated** in the
+     * semantic conventions and is never emitted.
+     */
+    readonly environment?: string;
+}
+/**
+ * Service identity after precedence has been applied.
+ *
+ * Distinct from {@link ServiceMetadata} because the optional fields here mean
+ * "resolved to nothing" rather than "not configured": every source — options,
+ * `OTEL_SERVICE_NAME`, `OTEL_RESOURCE_ATTRIBUTES`, `NODE_ENV` — has already been
+ * consulted, and a field still absent will not appear on any entry.
+ */
+interface ResolvedServiceMetadata {
+    /** `service.name`, always present. */
+    name: string;
+    /** `service.version`, always present. */
+    version: string;
+    /** `service.namespace`, when any source supplied one. */
+    namespace?: string;
+    /** `service.instance.id`, when any source supplied one. */
+    instanceId?: string;
+    /** `deployment.environment.name`, when any source supplied one. */
+    environment?: string;
+}
+/**
+ * The `service` block as it appears in an EMITTED record, under the default
+ * `resourceFormat: 'nested'`.
+ *
+ * Distinct from {@link ServiceMetadata} on purpose, and the distinction is the
+ * kind of defect this library has already been bitten by once: a published type
+ * that describes something the runtime never emits. `ServiceMetadata` is what a
+ * consumer CONFIGURES — flat option names like `instanceId` and `environment`.
+ * What comes out is the flattened OTel attribute path: `service.instance.id`
+ * nests as `service: { instance: { id } }`, and the environment is not under
+ * `service` at all, it is `deployment.environment.name`. Typing the emitted
+ * record with the configuration interface would advertise `entry.service.instanceId`
+ * to every consumer, and that property does not exist on any entry.
+ *
+ * Under `resourceFormat: 'flat'` these values appear as dotted top-level keys
+ * (`"service.instance.id"`), which {@link LogEntry}'s index signature already
+ * admits — a flat record simply has no `service` object.
+ */
+interface EmittedServiceResource {
+    /** OTel `service.name`. */
+    readonly name: string;
+    /** OTel `service.version`. */
+    readonly version: string;
+    /** OTel `service.namespace`, when resolved. */
+    readonly namespace?: string;
+    /** OTel `service.instance.id`, nested as the attribute path spells it. */
+    readonly instance?: {
+        readonly id: string;
+    };
+    /** Consumer-supplied extras carried through from the `service` option. */
+    readonly [key: string]: unknown;
+}
+/**
+ * The `deployment` block as it appears in an EMITTED record under
+ * `resourceFormat: 'nested'`, carrying `deployment.environment.name`.
+ *
+ * Absent entirely when no source resolved an environment. The deprecated
+ * `deployment.environment` spelling is never emitted.
+ */
+interface EmittedDeploymentResource {
+    /** OTel `deployment.environment.name`, flattened from its attribute path. */
+    readonly environment: {
+        readonly name: string;
+    };
 }
 
 /**
@@ -191,6 +284,52 @@ interface BymaxLoggerModuleOptions {
      *     path-matching semantics; expect it to be removed in a future major.
      */
     redactStrategy?: 'names' | 'paths';
+    /**
+     * Shape of the resource/service identity on every entry. Default `'nested'`.
+     *
+     *   - `'nested'` — `{ service: { name, version, namespace, instance: { id } },
+     *     deployment: { environment: { name } } }`. The historical shape, extended;
+     *     no existing query breaks.
+     *   - `'flat'` — the dotted OTel attribute names verbatim (`service.name`,
+     *     `service.instance.id`, `deployment.environment.name`), which is what a
+     *     collector mapping log fields onto resource attributes reads directly.
+     *
+     * Both carry the same values; only the key shape differs.
+     */
+    resourceFormat?: 'nested' | 'flat';
+    /**
+     * Field carrying the machine-readable event name, mirroring `logKey`.
+     * Default `'event.name'`; `false` emits nothing.
+     *
+     * `logKey` stays exactly as it is — this is additive, never a rename.
+     *
+     * The value is meant to be mapped onto the **`EventName`** field of the
+     * OpenTelemetry LogRecord, which is Stable in the Logs Data Model. Note that
+     * the same-named `event.name` *attribute* is Deprecated in the semantic
+     * conventions precisely because the value belongs in that top-level field
+     * instead; the key here is the JSON carrier, not an OTLP attribute. The name is
+     * configurable so a pipeline that maps a different key can use it.
+     *
+     * Keep event names LOW cardinality — `payment.failed`, not
+     * `payment.failed.918231781`. Identifiers belong in their own fields.
+     */
+    eventNameField?: string | false;
+    /**
+     * Shape of the error fields on an entry. Default `'pino'`.
+     *
+     *   - `'pino'`   — only the legacy `err` object (`type`, `message`, `stack`,
+     *     plus the `cause` chain). What every existing query reads.
+     *   - `'semconv'` — only the OpenTelemetry attributes: `exception.type`,
+     *     `exception.message`, `exception.stacktrace` and `error.type`. The `err`
+     *     object is removed, so this is an explicit migration, never a default.
+     *   - `'both'`    — both shapes on the same entry. Recommended while moving
+     *     dashboards over: nothing breaks, and the new fields are already there.
+     *
+     * All four attributes are **Stable** in Semantic Conventions v1.44.0.
+     * `error.type` carries the error's class name and is LOW cardinality by
+     * construction — never a message, never an identifier.
+     */
+    errorFormat?: 'pino' | 'semconv' | 'both';
     /** Censor string written in place of redacted values. Default: `[REDACTED]`. */
     redactCensor?: string;
     /** Disable default redact paths (use with caution). Default: false. */
@@ -393,6 +532,11 @@ declare const RESERVED_LOG_KEYS_NOT_EMITTED: Readonly<{
      */
     readonly HTTP_REQUEST_COMPLETED: "reserved: superseded by the four status-specific terminal keys";
 }>;
+/**
+ * Strongly-typed union of every reserved log key value, derived from
+ * {@link RESERVED_LOG_KEYS}. Use this type to constrain log-key arguments.
+ */
+type ReservedLogKey = (typeof RESERVED_LOG_KEYS)[keyof typeof RESERVED_LOG_KEYS];
 
 /**
  * Name-based recursive redaction.
@@ -598,17 +742,6 @@ declare class PinoLoggerService implements LoggerService, OnApplicationShutdown
      * this service has no additional teardown work.
      */
     onApplicationShutdown(): void;
-    /**
-     * Serialize an Error into a plain, log-safe object matching Pino's built-in
-     * `err` serializer shape (`type`, `message`, `stack`).
-     *
-     * Reads `error.name` (NOT `error.constructor.name`) for `type`: native
-     * subclasses set `name` to their class name, and a sanitized plain-object error
-     * (from `sanitizeError`) carries the real class name on `name` — whereas its
-     * `constructor.name` would be the unhelpful `'Object'`, breaking `err.type`
-     * dashboards for every exception logged through `HttpExceptionFilter`.
-     */
-    private serializeError;
     /** Resolve the context: last string param wins, else the instance context. */
     private resolveContext;
     /** Emit a structured payload at info or warn level. */
@@ -1179,8 +1312,25 @@ interface LogEntry {
     msg: string;
     /** Convention key — `MODULE_ACTION_RESULT` format. */
     logKey?: string;
-    /** Service metadata snapshot — see {@link ServiceMetadata}. */
-    service?: ServiceMetadata;
+    /**
+     * OTel event name derived from {@link logKey} (`PAYMENT_FAILED` →
+     * `payment.failed`), emitted on structured calls unless `eventNameField` is
+     * `false`. Declared explicitly because the index signature below would type
+     * it `unknown`: a documented field a consumer cannot read without a cast is
+     * not really published.
+     *
+     * The key is configurable, so a renamed field arrives through the index
+     * signature instead — this declaration describes the default only.
+     */
+    'event.name'?: string;
+    /**
+     * Service identity as EMITTED — see {@link EmittedServiceResource}. Not the
+     * configuration shape: `service.instance.id` nests, and the environment lives
+     * under `deployment`, not here.
+     */
+    service?: EmittedServiceResource;
+    /** Deployment identity as emitted — see {@link EmittedDeploymentResource}. */
+    deployment?: EmittedDeploymentResource;
     /** Optional NestJS context (typically the emitting class name). */
     context?: string;
     /** Optional correlation IDs propagated via AsyncLocalStorage. */
@@ -1223,4 +1373,4 @@ interface LogEntry {
  */
 declare const LOG_KEYS_CONVENTION_REGEX: RegExp;
 
-export { BymaxLoggerModule, type BymaxLoggerModuleAsyncOptions, type BymaxLoggerModuleOptions, type BymaxLoggerModuleOptionsFactory, DEFAULT_REDACT_PATHS, DefaultStdoutDestination, HttpExceptionFilter, HttpLoggingInterceptor, type HttpOptions, type ILogDestination, type IncomingHeaders, InjectLogger, LOGGER_DESTINATIONS_TOKEN, LOGGER_OPTIONS_TOKEN, LOGGER_PINO_INSTANCE_TOKEN, LOG_CONTEXT_METADATA_KEY, LOG_CONTEXT_TOKEN, LOG_KEYS_CONVENTION_REGEX, LogContext, type LogContext$1 as LogContextBag, LogContextService, type LogEntry, type LogLevel, LogPerformance, type LoggableRequest, type LoggableResponse, type NextHandler, type OtelOptions, PINO_LEVEL_NAMES, PINO_LEVEL_NUMBERS, PinoLoggerService, PrettyDevDestination, RESERVED_LOG_KEYS, RESERVED_LOG_KEYS_NOT_EMITTED, RequestIdMiddleware, type ResolvedBymaxLoggerModuleOptions, type ServiceMetadata, applyRequestIdMiddleware };
+export { BymaxLoggerModule, type BymaxLoggerModuleAsyncOptions, type BymaxLoggerModuleOptions, type BymaxLoggerModuleOptionsFactory, DEFAULT_REDACT_PATHS, DefaultStdoutDestination, type EmittedDeploymentResource, type EmittedServiceResource, HttpExceptionFilter, HttpLoggingInterceptor, type HttpOptions, type ILogDestination, type IncomingHeaders, InjectLogger, LOGGER_DESTINATIONS_TOKEN, LOGGER_OPTIONS_TOKEN, LOGGER_PINO_INSTANCE_TOKEN, LOG_CONTEXT_METADATA_KEY, LOG_CONTEXT_TOKEN, LOG_KEYS_CONVENTION_REGEX, LogContext, type LogContext$1 as LogContextBag, LogContextService, type LogEntry, type LogLevel, LogPerformance, type LoggableRequest, type LoggableResponse, type NextHandler, type OtelOptions, PINO_LEVEL_NAMES, PINO_LEVEL_NUMBERS, PinoLoggerService, PrettyDevDestination, RESERVED_LOG_KEYS, RESERVED_LOG_KEYS_NOT_EMITTED, RequestIdMiddleware, type ReservedLogKey, type ResolvedBymaxLoggerModuleOptions, type ResolvedServiceMetadata, type ServiceMetadata, applyRequestIdMiddleware };