@bymax-one/nest-logger 1.2.0 → 1.2.2

package/dist/shared/index.d.cts

@@ -25,6 +25,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;
+    };
 }
 
 /**
@@ -59,8 +152,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. */
@@ -159,4 +269,4 @@ declare const RESERVED_LOG_KEYS_NOT_EMITTED: Readonly<{
  */
 type ReservedLogKey = (typeof RESERVED_LOG_KEYS)[keyof typeof RESERVED_LOG_KEYS];
 
-export { LOG_KEYS_CONVENTION_REGEX, type LogEntry, type LogLevel, RESERVED_LOG_KEYS, RESERVED_LOG_KEYS_NOT_EMITTED, type ReservedLogKey, type ServiceMetadata };
+export { type EmittedDeploymentResource, type EmittedServiceResource, LOG_KEYS_CONVENTION_REGEX, type LogEntry, type LogLevel, RESERVED_LOG_KEYS, RESERVED_LOG_KEYS_NOT_EMITTED, type ReservedLogKey, type ResolvedServiceMetadata, type ServiceMetadata };

package/dist/shared/index.d.ts

@@ -25,6 +25,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;
+    };
 }
 
 /**
@@ -59,8 +152,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. */
@@ -159,4 +269,4 @@ declare const RESERVED_LOG_KEYS_NOT_EMITTED: Readonly<{
  */
 type ReservedLogKey = (typeof RESERVED_LOG_KEYS)[keyof typeof RESERVED_LOG_KEYS];
 
-export { LOG_KEYS_CONVENTION_REGEX, type LogEntry, type LogLevel, RESERVED_LOG_KEYS, RESERVED_LOG_KEYS_NOT_EMITTED, type ReservedLogKey, type ServiceMetadata };
+export { type EmittedDeploymentResource, type EmittedServiceResource, LOG_KEYS_CONVENTION_REGEX, type LogEntry, type LogLevel, RESERVED_LOG_KEYS, RESERVED_LOG_KEYS_NOT_EMITTED, type ReservedLogKey, type ResolvedServiceMetadata, type ServiceMetadata };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bymax-one/nest-logger",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "Structured JSON logging for NestJS based on Pino 10, with optional OpenTelemetry correlation.",
   "author": "Bymax One <support@bymax.one>",
   "license": "MIT",