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

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

@@ -0,0 +1,298 @@
+"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).
+//
+// AN APP CAN EXTEND THE PIPELINE (PP-14.18)
+// -----------------------------------------------------------------------------
+//
+// `spanProcessors`, `logRecordProcessors` and `metricReaders` add outputs next
+// to the OTLP ones; `views`, `sampler`, `textMapPropagator` and
+// `resourceAttributes` shape what is measured. Every processor and reader the
+// app passes is wrapped in its Gated* twin before the SDK sees it, so NOTHING
+// reaches it while the gate is closed: an app cannot add an output that leaks
+// past the administrator's `telemetry.enabled` switch by forgetting to wrap it.
+// With none of these options the SDK is configured exactly as before.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RESOURCE_ATTRIBUTES_MAX = exports.METRIC_EXPORT_INTERVAL_MS = exports.DEFAULT_OTLP_ENDPOINT = exports.DEFAULT_IGNORED_INCOMING_PATHS = void 0;
+exports.validateResourceAttributes = validateResourceAttributes;
+exports.initializeOtel = initializeOtel;
+exports.instrumentationConfig = instrumentationConfig;
+const api_1 = require("@opentelemetry/api");
+const instance_id_1 = require("./instance-id");
+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;
+/**
+ * The most extra resource attributes `initializeOtel` accepts.
+ *
+ * @stability experimental
+ */
+exports.RESOURCE_ATTRIBUTES_MAX = 32;
+const RESERVED_RESOURCE_ATTRIBUTES = new Set(['service.name', 'service.version', instance_id_1.ATTR_APP_INSTANCE_ID]);
+/**
+ * Checks the extra resource attributes: plain, bounded, none of the reserved
+ * keys. Exported for the spec.
+ *
+ * @param attributes - the app's `resourceAttributes`.
+ * @returns the attributes, unchanged.
+ * @throws Error naming the offending key.
+ *
+ * @stability experimental
+ */
+function validateResourceAttributes(attributes) {
+    if (attributes === undefined)
+        return {};
+    if (attributes === null || typeof attributes !== 'object' || Array.isArray(attributes)) {
+        throw new Error('initializeOtel: `resourceAttributes` must be an object of attribute names and values.');
+    }
+    const keys = Object.keys(attributes);
+    if (keys.length > exports.RESOURCE_ATTRIBUTES_MAX) {
+        throw new Error(`initializeOtel: \`resourceAttributes\` has ${keys.length} attributes; at most ${exports.RESOURCE_ATTRIBUTES_MAX}.`);
+    }
+    for (const key of keys) {
+        if (key === '' || key.length > 256)
+            throw new Error('initializeOtel: a `resourceAttributes` key must be 1 to 256 characters.');
+        if (RESERVED_RESOURCE_ATTRIBUTES.has(key)) {
+            throw new Error(`initializeOtel: \`resourceAttributes\` may not set "${key}" ` +
+                `(${key === instance_id_1.ATTR_APP_INSTANCE_ID ? 'the telemetry gate stamps it' : 'it has its own option'}).`);
+        }
+        const value = attributes[key];
+        const ok = (typeof value === 'string' && value.length <= 1024) ||
+            (typeof value === 'number' && Number.isFinite(value)) ||
+            typeof value === 'boolean';
+        if (!ok)
+            throw new Error(`initializeOtel: \`resourceAttributes\` "${key}" must be a string (at most 1 024 characters), a finite number or a boolean.`);
+    }
+    return attributes;
+}
+/** `list` must be an array of objects: the SDK would fail later and further from the cause. */
+function assertList(name, list) {
+    if (list === undefined)
+        return [];
+    if (!Array.isArray(list) || list.some((item) => item === null || typeof item !== 'object')) {
+        throw new Error(`initializeOtel: \`${name}\` must be an array of objects.`);
+    }
+    return list;
+}
+/**
+ * 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 = {}) {
+    // A bad extension option fails here, enabled or not: it must not wait for the day OTEL_ENABLED flips.
+    const extraResourceAttributes = validateResourceAttributes(options.resourceAttributes);
+    const extraSpanProcessors = assertList('spanProcessors', options.spanProcessors);
+    const extraLogProcessors = assertList('logRecordProcessors', options.logRecordProcessors);
+    const extraMetricReaders = assertList('metricReaders', options.metricReaders);
+    const views = assertList('views', options.views);
+    // 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 { BatchSpanProcessor } = require('@opentelemetry/sdk-trace-base');
+    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);
+    // The platform's attributes win over the app's: service.name and service.version
+    // are reserved (validated above); only deployment.environment may be replaced.
+    const resource = resourceFromAttributes({
+        [SEMRESATTRS_DEPLOYMENT_ENVIRONMENT]: process.env.NODE_ENV || 'development',
+        ...extraResourceAttributes,
+        [ATTR_SERVICE_NAME]: serviceName,
+        [ATTR_SERVICE_VERSION]: options.serviceVersion ?? (process.env.npm_package_version || '0.0.1'),
+    });
+    const otlpTraceExporter = new telemetry_gate_1.GatedSpanExporter(new OTLPTraceExporter({
+        url: `${endpoint}/v1/traces`,
+    }));
+    const otlpMetricReader = new PeriodicExportingMetricReader({
+        exporter: new telemetry_gate_1.GatedPushMetricExporter(new OTLPMetricExporter({
+            url: `${endpoint}/v1/metrics`,
+        })),
+        exportIntervalMillis: exports.METRIC_EXPORT_INTERVAL_MS,
+    });
+    const sdk = new NodeSdk({
+        resource,
+        // The SDK takes EITHER `traceExporter` OR `spanProcessors`: with extra
+        // processors the OTLP one is built here the way the SDK builds its own, and
+        // the app's follow it, each behind the gate. Without any the configuration
+        // is exactly what it always was.
+        ...(extraSpanProcessors.length > 0
+            ? {
+                spanProcessors: [
+                    new BatchSpanProcessor(otlpTraceExporter),
+                    ...extraSpanProcessors.map((processor) => new telemetry_gate_1.GatedSpanProcessor(processor)),
+                ],
+            }
+            : { traceExporter: otlpTraceExporter }),
+        ...(extraMetricReaders.length > 0
+            ? { metricReaders: [otlpMetricReader, ...extraMetricReaders.map((reader) => new telemetry_gate_1.GatedMetricReader(reader))] }
+            : { metricReader: otlpMetricReader }),
+        ...(views.length > 0 ? { views: [...views] } : {}),
+        ...(options.sampler ? { sampler: options.sampler } : {}),
+        ...(options.textMapPropagator ? { textMapPropagator: options.textMapPropagator } : {}),
+        // 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`,
+                })),
+            }),
+            ...extraLogProcessors.map((processor) => new telemetry_gate_1.GatedLogRecordProcessor(processor)),
+        ],
+        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"}