@marinoscar/platform-api 0.0.0-stage → 0.1.0-next.3

package/dist/otel-core/sdk/index.d.ts

@@ -0,0 +1,5 @@
+export { DEFAULT_IGNORED_INCOMING_PATHS, DEFAULT_OTLP_ENDPOINT, METRIC_EXPORT_INTERVAL_MS, initializeOtel, instrumentationConfig, type InitializeOtelOptions, } from './initialize-otel';
+export { GatedLogRecordExporter, GatedPushMetricExporter, GatedSpanExporter, stampResource, telemetryGate, type TelemetryGate, } from './telemetry-gate';
+export { DEFAULT_SERVICE_NAME, resolveServiceName } from './service-name';
+export { ATTR_APP_INSTANCE_ID, DEFAULT_INSTANCE_ID, resolveTelemetryInstanceId } from './instance-id';
+//# sourceMappingURL=index.d.ts.map

package/dist/otel-core/sdk/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/otel-core/sdk/index.ts"],"names":[],"mappings":"AAKA,OAAO,EACL,8BAA8B,EAC9B,qBAAqB,EACrB,yBAAyB,EACzB,cAAc,EACd,qBAAqB,EACrB,KAAK,qBAAqB,GAC3B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,sBAAsB,EACtB,uBAAuB,EACvB,iBAAiB,EACjB,aAAa,EACb,aAAa,EACb,KAAK,aAAa,GACnB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAC1E,OAAO,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,MAAM,eAAe,CAAC"}

package/dist/otel-core/sdk/index.js

@@ -0,0 +1,27 @@
+"use strict";
+// `@marinoscar/platform-api/otel-core/sdk`: the Nest-free half of the
+// otel-core slice (issue #700). Load it FIRST, before Nest or anything the
+// auto-instrumentation patches: it imports no `@nestjs/*` module
+// (test/otel-core/load-order.spec.ts). Documented in ../README.md.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveTelemetryInstanceId = exports.DEFAULT_INSTANCE_ID = exports.ATTR_APP_INSTANCE_ID = exports.resolveServiceName = exports.DEFAULT_SERVICE_NAME = exports.telemetryGate = exports.stampResource = exports.GatedSpanExporter = exports.GatedPushMetricExporter = exports.GatedLogRecordExporter = exports.instrumentationConfig = exports.initializeOtel = exports.METRIC_EXPORT_INTERVAL_MS = exports.DEFAULT_OTLP_ENDPOINT = exports.DEFAULT_IGNORED_INCOMING_PATHS = void 0;
+var initialize_otel_1 = require("./initialize-otel");
+Object.defineProperty(exports, "DEFAULT_IGNORED_INCOMING_PATHS", { enumerable: true, get: function () { return initialize_otel_1.DEFAULT_IGNORED_INCOMING_PATHS; } });
+Object.defineProperty(exports, "DEFAULT_OTLP_ENDPOINT", { enumerable: true, get: function () { return initialize_otel_1.DEFAULT_OTLP_ENDPOINT; } });
+Object.defineProperty(exports, "METRIC_EXPORT_INTERVAL_MS", { enumerable: true, get: function () { return initialize_otel_1.METRIC_EXPORT_INTERVAL_MS; } });
+Object.defineProperty(exports, "initializeOtel", { enumerable: true, get: function () { return initialize_otel_1.initializeOtel; } });
+Object.defineProperty(exports, "instrumentationConfig", { enumerable: true, get: function () { return initialize_otel_1.instrumentationConfig; } });
+var telemetry_gate_1 = require("./telemetry-gate");
+Object.defineProperty(exports, "GatedLogRecordExporter", { enumerable: true, get: function () { return telemetry_gate_1.GatedLogRecordExporter; } });
+Object.defineProperty(exports, "GatedPushMetricExporter", { enumerable: true, get: function () { return telemetry_gate_1.GatedPushMetricExporter; } });
+Object.defineProperty(exports, "GatedSpanExporter", { enumerable: true, get: function () { return telemetry_gate_1.GatedSpanExporter; } });
+Object.defineProperty(exports, "stampResource", { enumerable: true, get: function () { return telemetry_gate_1.stampResource; } });
+Object.defineProperty(exports, "telemetryGate", { enumerable: true, get: function () { return telemetry_gate_1.telemetryGate; } });
+var service_name_1 = require("./service-name");
+Object.defineProperty(exports, "DEFAULT_SERVICE_NAME", { enumerable: true, get: function () { return service_name_1.DEFAULT_SERVICE_NAME; } });
+Object.defineProperty(exports, "resolveServiceName", { enumerable: true, get: function () { return service_name_1.resolveServiceName; } });
+var instance_id_1 = require("./instance-id");
+Object.defineProperty(exports, "ATTR_APP_INSTANCE_ID", { enumerable: true, get: function () { return instance_id_1.ATTR_APP_INSTANCE_ID; } });
+Object.defineProperty(exports, "DEFAULT_INSTANCE_ID", { enumerable: true, get: function () { return instance_id_1.DEFAULT_INSTANCE_ID; } });
+Object.defineProperty(exports, "resolveTelemetryInstanceId", { enumerable: true, get: function () { return instance_id_1.resolveTelemetryInstanceId; } });
+//# sourceMappingURL=index.js.map

package/dist/otel-core/sdk/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/otel-core/sdk/index.ts"],"names":[],"mappings":";AAAA,sEAAsE;AACtE,2EAA2E;AAC3E,iEAAiE;AACjE,mEAAmE;;;AAEnE,qDAO2B;AANzB,iIAAA,8BAA8B,OAAA;AAC9B,wHAAA,qBAAqB,OAAA;AACrB,4HAAA,yBAAyB,OAAA;AACzB,iHAAA,cAAc,OAAA;AACd,wHAAA,qBAAqB,OAAA;AAGvB,mDAO0B;AANxB,wHAAA,sBAAsB,OAAA;AACtB,yHAAA,uBAAuB,OAAA;AACvB,mHAAA,iBAAiB,OAAA;AACjB,+GAAA,aAAa,OAAA;AACb,+GAAA,aAAa,OAAA;AAGf,+CAA0E;AAAjE,oHAAA,oBAAoB,OAAA;AAAE,kHAAA,kBAAkB,OAAA;AACjD,6CAAsG;AAA7F,mHAAA,oBAAoB,OAAA;AAAE,kHAAA,mBAAmB,OAAA;AAAE,yHAAA,0BAA0B,OAAA"}

package/dist/otel-core/sdk/initialize-otel.d.ts

@@ -0,0 +1,126 @@
+import type { NodeSDK } from '@opentelemetry/sdk-node';
+/**
+ * Incoming URL substrings the HTTP instrumentation never traces by default:
+ * the liveness and readiness probes, which an orchestrator calls every few
+ * seconds.
+ *
+ * @stability stable
+ */
+export declare const DEFAULT_IGNORED_INCOMING_PATHS: readonly string[];
+/**
+ * The OTLP/HTTP endpoint used when neither the option nor
+ * `OTEL_EXPORTER_OTLP_ENDPOINT` names one.
+ *
+ * @stability stable
+ */
+export declare const DEFAULT_OTLP_ENDPOINT = "http://localhost:4318";
+/**
+ * How often the metric reader collects and exports, in milliseconds.
+ *
+ * @stability stable
+ */
+export declare const METRIC_EXPORT_INTERVAL_MS = 60000;
+/**
+ * Options of {@link initializeOtel}. Every field is optional; the defaults
+ * reproduce the reference app's bootstrap exactly.
+ *
+ * @extensionPoint option
+ * @stability experimental
+ */
+export interface InitializeOtelOptions {
+    /**
+     * Whether to install the SDK at all.
+     *
+     * @defaultValue `process.env.OTEL_ENABLED === 'true'`
+     */
+    enabled?: boolean;
+    /**
+     * Base URL of the OTLP/HTTP collector; `/v1/traces`, `/v1/metrics` and
+     * `/v1/logs` are appended.
+     *
+     * @defaultValue `process.env.OTEL_EXPORTER_OTLP_ENDPOINT || 'http://localhost:4318'`
+     */
+    endpoint?: string;
+    /**
+     * The `service.name` resource attribute.
+     *
+     * @defaultValue `resolveServiceName()` (`OTEL_SERVICE_NAME`, else `DEFAULT_SERVICE_NAME`)
+     */
+    serviceName?: string;
+    /**
+     * The `service.version` resource attribute.
+     *
+     * @defaultValue `process.env.npm_package_version || '0.0.1'`
+     */
+    serviceVersion?: string;
+    /**
+     * The instance identifier the telemetry gate stamps until the app sets its
+     * own (`telemetryGate.setInstanceId`). Pass the app's slug so the first
+     * exported batch is never unlabelled. Left unchanged when omitted.
+     */
+    instanceId?: string;
+    /**
+     * Incoming URL substrings never traced.
+     *
+     * @defaultValue {@link DEFAULT_IGNORED_INCOMING_PATHS}
+     */
+    ignoreIncomingPaths?: readonly string[];
+    /**
+     * Extra auto-instrumentation configuration, by instrumentation package
+     * name, merged over the defaults (fs disabled, pino log sending on, the
+     * http ignore hook). An entry for a package with a default is merged into
+     * it field by field.
+     */
+    instrumentationOverrides?: Record<string, Record<string, unknown>>;
+    /**
+     * Whether to register a SIGTERM handler that shuts the SDK down (flushing
+     * what the gate lets through) and exits the process.
+     *
+     * @defaultValue `true`
+     */
+    shutdownOnSigterm?: boolean;
+}
+/**
+ * Installs and starts the OpenTelemetry Node SDK, or does nothing.
+ *
+ * Disabled (the default unless `OTEL_ENABLED=true`): logs
+ * `OpenTelemetry disabled (OTEL_ENABLED !== true)` and returns `null`; no SDK
+ * or exporter is constructed and no SDK package is loaded.
+ *
+ * Enabled: OTLP/HTTP trace, metric (every 60 s) and log exporters, each
+ * behind the closed-by-default telemetry gate; the Node auto-instrumentations
+ * (health probes ignored, fs off, pino log sending on); a SIGTERM handler
+ * that shuts the SDK down. Call it before anything else is required: import
+ * the `sdk` subpath, never the Nest-facing `otel-core` index, from the file
+ * the entry point loads first.
+ *
+ * When `OTEL_DEBUG=true` and `NODE_ENV=development`, OpenTelemetry's own
+ * diagnostics go to the console (both cases).
+ *
+ * @param options - See {@link InitializeOtelOptions}.
+ * @returns The started SDK, or `null` when disabled.
+ *
+ * @example
+ * ```ts
+ * // apps/api/src/instrumentation.ts, imported first by main.ts
+ * import { initializeOtel } from '@marinoscar/platform-api/otel-core/sdk';
+ * export const sdk = initializeOtel({ serviceName: resolveServiceName(), instanceId: APP_SLUG });
+ * ```
+ *
+ * @extensionPoint option
+ * @stability experimental
+ */
+export declare function initializeOtel(options?: InitializeOtelOptions): NodeSDK | null;
+/**
+ * The auto-instrumentation configuration: the defaults, with `overrides`
+ * merged over them per instrumentation (field by field). Exported for the
+ * spec; an app passes `instrumentationOverrides` instead.
+ *
+ * @param ignoreIncomingPaths - Incoming URL substrings the http instrumentation skips.
+ * @param overrides - Per-instrumentation fields merged over the defaults.
+ * @returns The object handed to `getNodeAutoInstrumentations`.
+ *
+ * @stability experimental
+ */
+export declare function instrumentationConfig(ignoreIncomingPaths: readonly string[], overrides?: Record<string, Record<string, unknown>>): Record<string, Record<string, unknown>>;
+//# sourceMappingURL=initialize-otel.d.ts.map

package/dist/otel-core/sdk/initialize-otel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"initialize-otel.d.ts","sourceRoot":"","sources":["../../../src/otel-core/sdk/initialize-otel.ts"],"names":[],"mappings":"AAmCA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAUvD;;;;;;GAMG;AACH,eAAO,MAAM,8BAA8B,EAAE,SAAS,MAAM,EAG1D,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,0BAA0B,CAAC;AAE7D;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,QAAS,CAAC;AAEhD;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC;;;;;OAKG;IACH,wBAAwB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACnE;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,cAAc,CAAC,OAAO,GAAE,qBAA0B,GAAG,OAAO,GAAG,IAAI,CA8FlF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACnC,mBAAmB,EAAE,SAAS,MAAM,EAAE,EACtC,SAAS,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAM,GACtD,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CA2BzC"}

package/dist/otel-core/sdk/initialize-otel.js

@@ -0,0 +1,204 @@
+"use strict";
+// =============================================================================
+// The OpenTelemetry SDK bootstrap (from apps/api/src/instrumentation.ts;
+// packaged and parameterised by issue #700)
+// =============================================================================
+//
+// LOAD ORDER IS THE WHOLE CONTRACT
+// -----------------------------------------------------------------------------
+//
+// Auto-instrumentation can only patch modules that are required AFTER
+// `sdk.start()`. So the app calls `initializeOtel()` from a file its entry
+// point imports FIRST (the reference app: `apps/api/src/instrumentation.ts`,
+// line 2 of `main.ts`), and this module, like everything in the `sdk`
+// subpath, imports no `@nestjs/*`, `http`, `pg` or `pino`
+// (`test/otel-core/load-order.spec.ts` proves the first).
+//
+// OFF COSTS NOTHING
+// -----------------------------------------------------------------------------
+//
+// With `OTEL_ENABLED` not `true` the function logs one line and returns
+// `null`: no SDK, no exporter, and the SDK packages (`sdk-node`, the
+// auto-instrumentation bundle, the OTLP exporters) are never even required.
+// They are loaded lazily, inside the enabled branch, for that reason. The
+// OpenTelemetry API then keeps its no-op providers, so every instrument and
+// span the app creates is a no-op.
+//
+// ON EXPORTS NOTHING UNTIL THE GATE OPENS
+// -----------------------------------------------------------------------------
+//
+// Every exporter is wrapped in a gated exporter (`telemetry-gate.ts`) that
+// starts CLOSED, so OTEL_ENABLED installs the SDK but nothing is exported
+// until the app opens the gate (the reference app: the `telemetry.enabled`
+// system setting, issue #532).
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.METRIC_EXPORT_INTERVAL_MS = exports.DEFAULT_OTLP_ENDPOINT = exports.DEFAULT_IGNORED_INCOMING_PATHS = void 0;
+exports.initializeOtel = initializeOtel;
+exports.instrumentationConfig = instrumentationConfig;
+const api_1 = require("@opentelemetry/api");
+const service_name_1 = require("./service-name");
+const telemetry_gate_1 = require("./telemetry-gate");
+/**
+ * Incoming URL substrings the HTTP instrumentation never traces by default:
+ * the liveness and readiness probes, which an orchestrator calls every few
+ * seconds.
+ *
+ * @stability stable
+ */
+exports.DEFAULT_IGNORED_INCOMING_PATHS = Object.freeze([
+    '/api/health/live',
+    '/api/health/ready',
+]);
+/**
+ * The OTLP/HTTP endpoint used when neither the option nor
+ * `OTEL_EXPORTER_OTLP_ENDPOINT` names one.
+ *
+ * @stability stable
+ */
+exports.DEFAULT_OTLP_ENDPOINT = 'http://localhost:4318';
+/**
+ * How often the metric reader collects and exports, in milliseconds.
+ *
+ * @stability stable
+ */
+exports.METRIC_EXPORT_INTERVAL_MS = 60_000;
+/**
+ * Installs and starts the OpenTelemetry Node SDK, or does nothing.
+ *
+ * Disabled (the default unless `OTEL_ENABLED=true`): logs
+ * `OpenTelemetry disabled (OTEL_ENABLED !== true)` and returns `null`; no SDK
+ * or exporter is constructed and no SDK package is loaded.
+ *
+ * Enabled: OTLP/HTTP trace, metric (every 60 s) and log exporters, each
+ * behind the closed-by-default telemetry gate; the Node auto-instrumentations
+ * (health probes ignored, fs off, pino log sending on); a SIGTERM handler
+ * that shuts the SDK down. Call it before anything else is required: import
+ * the `sdk` subpath, never the Nest-facing `otel-core` index, from the file
+ * the entry point loads first.
+ *
+ * When `OTEL_DEBUG=true` and `NODE_ENV=development`, OpenTelemetry's own
+ * diagnostics go to the console (both cases).
+ *
+ * @param options - See {@link InitializeOtelOptions}.
+ * @returns The started SDK, or `null` when disabled.
+ *
+ * @example
+ * ```ts
+ * // apps/api/src/instrumentation.ts, imported first by main.ts
+ * import { initializeOtel } from '@marinoscar/platform-api/otel-core/sdk';
+ * export const sdk = initializeOtel({ serviceName: resolveServiceName(), instanceId: APP_SLUG });
+ * ```
+ *
+ * @extensionPoint option
+ * @stability experimental
+ */
+function initializeOtel(options = {}) {
+    // Enable OTEL diagnostics in development.
+    if (process.env.NODE_ENV === 'development' && process.env.OTEL_DEBUG === 'true') {
+        api_1.diag.setLogger(new api_1.DiagConsoleLogger(), api_1.DiagLogLevel.INFO);
+    }
+    const log = (message) => console.log(message);
+    const enabled = options.enabled ?? process.env.OTEL_ENABLED === 'true';
+    if (!enabled) {
+        log('OpenTelemetry disabled (OTEL_ENABLED !== true)');
+        return null;
+    }
+    // Loaded only here: a disabled process never pays for the SDK, and nothing
+    // below is required before the app has decided to install it.
+    const { NodeSDK: NodeSdk } = require('@opentelemetry/sdk-node');
+    const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
+    const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http');
+    const { OTLPMetricExporter } = require('@opentelemetry/exporter-metrics-otlp-http');
+    const { OTLPLogExporter } = require('@opentelemetry/exporter-logs-otlp-http');
+    const { PeriodicExportingMetricReader } = require('@opentelemetry/sdk-metrics');
+    const { BatchLogRecordProcessor } = require('@opentelemetry/sdk-logs');
+    const { resourceFromAttributes } = require('@opentelemetry/resources');
+    const { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION, SEMRESATTRS_DEPLOYMENT_ENVIRONMENT } = require('@opentelemetry/semantic-conventions');
+    const endpoint = options.endpoint ?? (process.env.OTEL_EXPORTER_OTLP_ENDPOINT || exports.DEFAULT_OTLP_ENDPOINT);
+    const serviceName = options.serviceName ?? (0, service_name_1.resolveServiceName)();
+    const ignored = [...(options.ignoreIncomingPaths ?? exports.DEFAULT_IGNORED_INCOMING_PATHS)];
+    if (options.instanceId)
+        telemetry_gate_1.telemetryGate.setInstanceId(options.instanceId);
+    const resource = resourceFromAttributes({
+        [ATTR_SERVICE_NAME]: serviceName,
+        [ATTR_SERVICE_VERSION]: options.serviceVersion ?? (process.env.npm_package_version || '0.0.1'),
+        [SEMRESATTRS_DEPLOYMENT_ENVIRONMENT]: process.env.NODE_ENV || 'development',
+    });
+    const sdk = new NodeSdk({
+        resource,
+        traceExporter: new telemetry_gate_1.GatedSpanExporter(new OTLPTraceExporter({
+            url: `${endpoint}/v1/traces`,
+        })),
+        metricReader: new PeriodicExportingMetricReader({
+            exporter: new telemetry_gate_1.GatedPushMetricExporter(new OTLPMetricExporter({
+                url: `${endpoint}/v1/metrics`,
+            })),
+            exportIntervalMillis: exports.METRIC_EXPORT_INTERVAL_MS,
+        }),
+        // Registers the global LoggerProvider. The pino instrumentation below
+        // forwards every pino record to it ("log sending"); stdout is unchanged.
+        logRecordProcessors: [
+            new BatchLogRecordProcessor({
+                exporter: new telemetry_gate_1.GatedLogRecordExporter(new OTLPLogExporter({
+                    url: `${endpoint}/v1/logs`,
+                })),
+            }),
+        ],
+        instrumentations: [
+            getNodeAutoInstrumentations(instrumentationConfig(ignored, options.instrumentationOverrides)),
+        ],
+    });
+    sdk.start();
+    log(`OpenTelemetry initialized - exporting to ${endpoint} once the telemetry.enabled setting opens the gate`);
+    // Graceful shutdown
+    if (options.shutdownOnSigterm ?? true) {
+        process.on('SIGTERM', () => {
+            sdk
+                .shutdown()
+                .then(() => console.log('OpenTelemetry SDK shut down'))
+                .catch((err) => console.error('Error shutting down OTEL SDK', err))
+                .finally(() => process.exit(0));
+        });
+    }
+    return sdk;
+}
+/**
+ * The auto-instrumentation configuration: the defaults, with `overrides`
+ * merged over them per instrumentation (field by field). Exported for the
+ * spec; an app passes `instrumentationOverrides` instead.
+ *
+ * @param ignoreIncomingPaths - Incoming URL substrings the http instrumentation skips.
+ * @param overrides - Per-instrumentation fields merged over the defaults.
+ * @returns The object handed to `getNodeAutoInstrumentations`.
+ *
+ * @stability experimental
+ */
+function instrumentationConfig(ignoreIncomingPaths, overrides = {}) {
+    const defaults = {
+        '@opentelemetry/instrumentation-http': {
+            ignoreIncomingRequestHook: (request) => {
+                const url = request.url || '';
+                return ignoreIncomingPaths.some((path) => url.includes(path));
+            },
+        },
+        '@opentelemetry/instrumentation-fs': {
+            enabled: false, // Disable noisy FS instrumentation
+        },
+        // Log sending is the instrumentation's default (disableLogSending:
+        // false); spelled out so the OTLP log pipeline does not silently depend
+        // on an upstream default. It adds an OTel destination next to the
+        // logger's own stream via pino.multistream, so stdout output (and
+        // pino-pretty in development) is untouched. Requires `pino` to be
+        // required after `sdk.start()`, which the load order ensures.
+        '@opentelemetry/instrumentation-pino': {
+            disableLogSending: false,
+        },
+    };
+    const merged = { ...defaults };
+    for (const [name, config] of Object.entries(overrides)) {
+        merged[name] = { ...(defaults[name] ?? {}), ...config };
+    }
+    return merged;
+}
+//# sourceMappingURL=initialize-otel.js.map

package/dist/otel-core/sdk/initialize-otel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"initialize-otel.js","sourceRoot":"","sources":["../../../src/otel-core/sdk/initialize-otel.ts"],"names":[],"mappings":"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"}

package/dist/otel-core/sdk/instance-id.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The OTel resource attribute key the instance identifier is exported under.
+ *
+ * @stability stable
+ */
+export declare const ATTR_APP_INSTANCE_ID = "app.instance.id";
+/**
+ * The instance identifier used when neither the administrator nor the caller
+ * names one. The reference app always passes its `APP_SLUG`, so it never
+ * exports this value.
+ *
+ * @stability experimental
+ */
+export declare const DEFAULT_INSTANCE_ID = "unknown";
+/**
+ * The instance identifier telemetry is stamped with: `configured` (the
+ * administrator's choice) when set, else `fallback`.
+ *
+ * An empty string is treated like `null`: a label of `""` would be worse than
+ * the default in every backend.
+ *
+ * @param configured - The stored setting; `null`, `undefined` or `""` means "use the default".
+ * @param fallback - The app's own default (its slug). Defaults to {@link DEFAULT_INSTANCE_ID}.
+ * @returns The resolved identifier, never empty.
+ *
+ * @stability stable
+ */
+export declare function resolveTelemetryInstanceId(configured: string | null | undefined, fallback?: string): string;
+//# sourceMappingURL=instance-id.d.ts.map

package/dist/otel-core/sdk/instance-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance-id.d.ts","sourceRoot":"","sources":["../../../src/otel-core/sdk/instance-id.ts"],"names":[],"mappings":"AA+BA;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,oBAAoB,CAAC;AAEtD;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,YAAY,CAAC;AAE7C;;;;;;;;;;;;GAYG;AACH,wBAAgB,0BAA0B,CACxC,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACrC,QAAQ,GAAE,MAA4B,GACrC,MAAM,CAER"}

package/dist/otel-core/sdk/instance-id.js

@@ -0,0 +1,65 @@
+"use strict";
+// =============================================================================
+// The telemetry instance identifier (issue #565; packaged by issue #700)
+// =============================================================================
+//
+// WHAT IT IS, AND WHY IT IS NOT THE SERVICE NAME
+// -----------------------------------------------------------------------------
+//
+// `service.name` (`service-name.ts`) says WHICH PROGRAM produced a span:
+// `my-app-api`. It is fixed per deployment by `OTEL_SERVICE_NAME` and cannot
+// change without a restart, because it lives on the SDK resource.
+//
+// `app.instance.id` says WHICH DEPLOYMENT OF THE APPLICATION produced it. Two
+// forks of the template, or staging and production of one fork, can ship
+// into one shared telemetry store, and without a label of their own their
+// series and traces are indistinguishable. An administrator sets it at
+// runtime (the reference app's `telemetry.instanceId` setting), and the
+// telemetry gate stamps it on every exported batch.
+//
+// THE DEFAULT IS THE APP'S, RESOLVED ON EVERY CALL
+// -----------------------------------------------------------------------------
+//
+// The stored setting is `null` until an administrator overrides it, and `null`
+// means "follow the app's slug". Storing the slug literally on first write
+// would freeze it: a fork renamed afterwards would keep reporting under the
+// template's identity. The package knows no product identity, so the caller
+// passes the slug (`apps/api/src/common/otel/telemetry-identity.ts` binds
+// `APP_SLUG`).
+//
+// SAFE TO IMPORT BEFORE THE SDK STARTS: no side effects, no imports.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_INSTANCE_ID = exports.ATTR_APP_INSTANCE_ID = void 0;
+exports.resolveTelemetryInstanceId = resolveTelemetryInstanceId;
+/**
+ * The OTel resource attribute key the instance identifier is exported under.
+ *
+ * @stability stable
+ */
+exports.ATTR_APP_INSTANCE_ID = 'app.instance.id';
+/**
+ * The instance identifier used when neither the administrator nor the caller
+ * names one. The reference app always passes its `APP_SLUG`, so it never
+ * exports this value.
+ *
+ * @stability experimental
+ */
+exports.DEFAULT_INSTANCE_ID = 'unknown';
+/**
+ * The instance identifier telemetry is stamped with: `configured` (the
+ * administrator's choice) when set, else `fallback`.
+ *
+ * An empty string is treated like `null`: a label of `""` would be worse than
+ * the default in every backend.
+ *
+ * @param configured - The stored setting; `null`, `undefined` or `""` means "use the default".
+ * @param fallback - The app's own default (its slug). Defaults to {@link DEFAULT_INSTANCE_ID}.
+ * @returns The resolved identifier, never empty.
+ *
+ * @stability stable
+ */
+function resolveTelemetryInstanceId(configured, fallback = exports.DEFAULT_INSTANCE_ID) {
+    return configured || fallback || exports.DEFAULT_INSTANCE_ID;
+}
+//# sourceMappingURL=instance-id.js.map

package/dist/otel-core/sdk/instance-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance-id.js","sourceRoot":"","sources":["../../../src/otel-core/sdk/instance-id.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,yEAAyE;AACzE,gFAAgF;AAChF,EAAE;AACF,iDAAiD;AACjD,gFAAgF;AAChF,EAAE;AACF,yEAAyE;AACzE,6EAA6E;AAC7E,kEAAkE;AAClE,EAAE;AACF,8EAA8E;AAC9E,yEAAyE;AACzE,0EAA0E;AAC1E,uEAAuE;AACvE,wEAAwE;AACxE,oDAAoD;AACpD,EAAE;AACF,mDAAmD;AACnD,gFAAgF;AAChF,EAAE;AACF,+EAA+E;AAC/E,2EAA2E;AAC3E,4EAA4E;AAC5E,4EAA4E;AAC5E,0EAA0E;AAC1E,eAAe;AACf,EAAE;AACF,qEAAqE;AACrE,gFAAgF;;;AA+BhF,gEAKC;AAlCD;;;;GAIG;AACU,QAAA,oBAAoB,GAAG,iBAAiB,CAAC;AAEtD;;;;;;GAMG;AACU,QAAA,mBAAmB,GAAG,SAAS,CAAC;AAE7C;;;;;;;;;;;;GAYG;AACH,SAAgB,0BAA0B,CACxC,UAAqC,EACrC,WAAmB,2BAAmB;IAEtC,OAAO,UAAU,IAAI,QAAQ,IAAI,2BAAmB,CAAC;AACvD,CAAC"}

package/dist/otel-core/sdk/service-name.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The service name OpenTelemetry's own SDK reports when nothing names the
+ * service, used here when the caller passes no fallback either.
+ *
+ * @stability experimental
+ */
+export declare const DEFAULT_SERVICE_NAME = "unknown_service:node";
+/**
+ * The service name this process reports to OpenTelemetry: `OTEL_SERVICE_NAME`
+ * when set, else `fallback`.
+ *
+ * Resolved on every call rather than captured in a module-level constant, so a
+ * test that sets `process.env.OTEL_SERVICE_NAME` is not defeated by whichever
+ * module happened to be imported first.
+ *
+ * @param fallback - The app's own default, `${APP_SLUG}-api` in the reference
+ *   app. Defaults to {@link DEFAULT_SERVICE_NAME}.
+ * @returns The resolved service name, never empty.
+ *
+ * @example
+ * ```ts
+ * export const appServiceName = () => resolveServiceName(`${APP_SLUG}-api`);
+ * ```
+ *
+ * @stability stable
+ */
+export declare function resolveServiceName(fallback?: string): string;
+//# sourceMappingURL=service-name.d.ts.map

package/dist/otel-core/sdk/service-name.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-name.d.ts","sourceRoot":"","sources":["../../../src/otel-core/sdk/service-name.ts"],"names":[],"mappings":"AA8BA;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,yBAAyB,CAAC;AAE3D;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,GAAE,MAA6B,GAAG,MAAM,CAElF"}

package/dist/otel-core/sdk/service-name.js

@@ -0,0 +1,63 @@
+"use strict";
+// =============================================================================
+// The OpenTelemetry service name, resolved in exactly one place (issue #343;
+// packaged by issue #700)
+// =============================================================================
+//
+// WHY ONE SHARED EXPRESSION RATHER THAN SEVERAL FALLBACKS
+// -----------------------------------------------------------------------------
+//
+// Several surfaces name the service: the SDK resource (`initializeOtel`), the
+// app's configuration, the `service` field of every log line, the `@Trace()`
+// tracer, the AI adapters' spans. Before issue #343 each spelled the fallback
+// out for itself, and one read nothing at all, so setting `OTEL_SERVICE_NAME`
+// moved some of them and left the rest on the template's name: spans of one
+// process landed under two services in the same backend.
+//
+// One call makes them agree by construction. The FALLBACK is the app's to
+// give: the package knows no product identity (a slice never imports the
+// app's `@app/shared`), so the reference app binds it once, to
+// `${APP_SLUG}-api`, in `apps/api/src/common/otel/telemetry-identity.ts`, and
+// every app surface calls that binding. A renamed fork therefore never keeps
+// reporting as the template it was cloned from.
+//
+// SAFE TO IMPORT BEFORE THE SDK STARTS
+// -----------------------------------------------------------------------------
+//
+// The `sdk` subpath is loaded first thing by the app, before Nest exists, and
+// auto-instrumentation can only patch modules required AFTER `sdk.start()`.
+// This module reads `process.env` and nothing else. Keep it that way.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_SERVICE_NAME = void 0;
+exports.resolveServiceName = resolveServiceName;
+/**
+ * The service name OpenTelemetry's own SDK reports when nothing names the
+ * service, used here when the caller passes no fallback either.
+ *
+ * @stability experimental
+ */
+exports.DEFAULT_SERVICE_NAME = 'unknown_service:node';
+/**
+ * The service name this process reports to OpenTelemetry: `OTEL_SERVICE_NAME`
+ * when set, else `fallback`.
+ *
+ * Resolved on every call rather than captured in a module-level constant, so a
+ * test that sets `process.env.OTEL_SERVICE_NAME` is not defeated by whichever
+ * module happened to be imported first.
+ *
+ * @param fallback - The app's own default, `${APP_SLUG}-api` in the reference
+ *   app. Defaults to {@link DEFAULT_SERVICE_NAME}.
+ * @returns The resolved service name, never empty.
+ *
+ * @example
+ * ```ts
+ * export const appServiceName = () => resolveServiceName(`${APP_SLUG}-api`);
+ * ```
+ *
+ * @stability stable
+ */
+function resolveServiceName(fallback = exports.DEFAULT_SERVICE_NAME) {
+    return process.env.OTEL_SERVICE_NAME || fallback || exports.DEFAULT_SERVICE_NAME;
+}
+//# sourceMappingURL=service-name.js.map

package/dist/otel-core/sdk/service-name.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-name.js","sourceRoot":"","sources":["../../../src/otel-core/sdk/service-name.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,6EAA6E;AAC7E,0BAA0B;AAC1B,gFAAgF;AAChF,EAAE;AACF,0DAA0D;AAC1D,gFAAgF;AAChF,EAAE;AACF,8EAA8E;AAC9E,6EAA6E;AAC7E,8EAA8E;AAC9E,8EAA8E;AAC9E,4EAA4E;AAC5E,yDAAyD;AACzD,EAAE;AACF,0EAA0E;AAC1E,yEAAyE;AACzE,+DAA+D;AAC/D,8EAA8E;AAC9E,6EAA6E;AAC7E,gDAAgD;AAChD,EAAE;AACF,uCAAuC;AACvC,gFAAgF;AAChF,EAAE;AACF,8EAA8E;AAC9E,4EAA4E;AAC5E,sEAAsE;AACtE,gFAAgF;;;AA6BhF,gDAEC;AA7BD;;;;;GAKG;AACU,QAAA,oBAAoB,GAAG,sBAAsB,CAAC;AAE3D;;;;;;;;;;;;;;;;;;GAkBG;AACH,SAAgB,kBAAkB,CAAC,WAAmB,4BAAoB;IACxE,OAAO,OAAO,CAAC,GAAG,CAAC,iBAAiB,IAAI,QAAQ,IAAI,4BAAoB,CAAC;AAC3E,CAAC"}