@lokalise/opentelemetry-fastify-bootstrap 3.0.0 → 4.0.0

package/README.md

@@ -66,6 +66,8 @@ initOpenTelemetry()
 | `skippedPaths` | `string[]` | `['/health', '/metrics', '/']` | Paths to exclude from tracing |
 | `consoleSpans` | `boolean` | `false` | Enable console span exporter for debugging |
 | `spanProcessors` | `SpanProcessor[]` | `[]` | Additional span processors to register |
+| `dbNamespaceBySystem` | `Record<string, string>` | `undefined` | Maps `db.system` values to the `db.namespace` to report for them. When set, the Datadog-bound trace exporter is wrapped so matching outbound DB spans carry `db.namespace` in the export payload, joining them to Datadog's existing inferred-service entity for the cluster. The shared span is left untouched. See [Joining a Datadog inferred-service entity](#joining-a-datadog-inferred-service-entity). |
+| `skipStreamEndpoints` | `boolean` | `true` | Exclude streaming/SSE server spans from exported traces (detected via the `Accept: text/event-stream` request header), so their long keep-alive durations don't skew latency metrics/SLOs. See [Excluding streaming / SSE endpoints](#excluding-streaming--sse-endpoints). |
 
 ### Debugging with Console Spans
 
@@ -81,6 +83,46 @@ initOpenTelemetry({
 
 When enabled, spans are printed to the console in addition to being sent to the OTLP exporter. This is useful for verifying that instrumentation is working correctly without needing to run a full observability stack.
 
+### Joining a Datadog inferred-service entity
+
+Datadog's APM service catalog auto-creates inferred-service entities for downstream clusters from peer tags such as `peer.db.system` and `peer.db.name`, deriving `peer.db.name` from the OTel-canonical `db.namespace` (see the [peer-tags precedence list](https://docs.datadoghq.com/tracing/services/inferred_services/?tab=agentv7600#peer-tags) for the authoritative set). When no usable peer tag is present, Datadog falls back to `peer.hostname` — and downstream clusters reached by raw IP (e.g. an Elasticsearch cluster on EC2 addressed by IP) then surface as the synthetic `blocked-ip-address` service in the dependency map.
+
+Some instrumentations don't set `db.namespace`. Notably the Node.js `@elastic/transport` (v8 Elasticsearch client) sets `db.system: elasticsearch` but never `db.namespace`, so outbound ES calls don't join the existing cluster entity.
+
+Pass `dbNamespaceBySystem` to add `db.namespace` based on `db.system`:
+
+```ts
+initOpenTelemetry({
+  dbNamespaceBySystem: { elasticsearch: 'lokalise' },
+})
+```
+
+For every span where `db.system: elasticsearch`, the exported payload gains:
+
+- `db.namespace: lokalise` — the OTel-canonical, vendor-neutral attribute.
+
+Datadog adds the `peer.*` prefix itself, deriving `peer.db.name` from `db.namespace` and `peer.db.system` from `db.system`, so we only set the short-form attribute and never write `peer.*` tags directly. See [Datadog peer tags](https://docs.datadoghq.com/tracing/services/inferred_services/?tab=agentv7600#peer-tags).
+
+#### Why an exporter, not a span processor
+
+A constant such as `lokalise` is a Datadog entity-keying heuristic, not the span's true OTel `db.namespace`. Rather than mutate the single `ReadableSpan` shared by every processor and exporter — which would make any other consumer (a different dashboard, OTel-native tooling) read `lokalise` as the real namespace — `dbNamespaceBySystem` wraps **only** the Datadog-bound exporter. The attribute is added to that exporter's own payload via a non-mutating view of the span; the original is never written to, so it can't be broken by a future SDK that freezes span attributes, and every other consumer sees the unmodified span. An existing non-empty `db.namespace` is never replaced.
+
+`DbNamespaceSpanExporter` is exported from the package if you want to wrap an exporter directly.
+
+### Excluding streaming / SSE endpoints
+
+An SSE (Server-Sent Events) or other long-lived streaming response keeps the HTTP request open for the whole lifetime of the stream, so the auto-instrumented server span's duration reflects the keep-alive window (often minutes) rather than the time-to-first-byte. Any latency metric or SLO derived from that span's duration is then skewed by those multi-minute values.
+
+This filtering is enabled by default (`skipStreamEndpoints: true`), so those spans are dropped from the exported traces out of the box. Opt out by setting it to `false`:
+
+```ts
+initOpenTelemetry({
+  skipStreamEndpoints: false,
+})
+```
+
+Streaming requests are detected by the `Accept: text/event-stream` request header — the header browser `EventSource` clients are required to send, and the same signal SSE content-negotiation keys on. Matching spans are tagged and dropped before export, generically for every streaming endpoint (no per-route list to maintain). The span still starts, so trace context still propagates to child spans, and it stays visible to console / user-supplied span processors — only the exported traces omit it.
+
 ### Adding Custom Span Processors
 
 You can integrate additional span processors to send telemetry data to multiple destinations or add custom processing logic.
@@ -107,6 +149,7 @@ initOpenTelemetry({
 - Configurable path filtering
 - Optional console span exporter for debugging
 - Support for custom span processors
+- Optional `db.namespace` enrichment of the Datadog export payload to join inferred-service entities
 - Graceful shutdown support
 
 ## Graceful Shutdown

package/dist/dbNamespaceSpanExporter.d.ts

@@ -0,0 +1,63 @@
+import type { ReadableSpan, SpanExporter } from '@opentelemetry/sdk-trace-base';
+export interface DbNamespaceSpanExporterOptions {
+    /**
+     * Maps an OTel `db.system` value to the `db.namespace` to add on matching
+     * spans in the export payload. Example: `{ elasticsearch: 'lokalise' }`. See
+     * {@link DbNamespaceSpanExporter} for why and how.
+     *
+     * Keys and values must be non-empty strings; the constructor throws on
+     * misconfigured entries so typos surface at startup instead of silently
+     * no-op'ing in production.
+     *
+     * @see https://opentelemetry.io/docs/specs/semconv/database/database-spans/ for well-known `db.system` values
+     */
+    dbNamespaceBySystem: Readonly<Record<string, string>>;
+}
+/**
+ * A `SpanExporter` decorator that adds `db.namespace` to outbound DB spans in
+ * the export payload — based on the OTel `db.system` value — then delegates to
+ * the wrapped exporter. It exists so Datadog's APM catalog joins those spans to
+ * an existing inferred-service entity for the cluster.
+ *
+ * Why (per Datadog inferred-services behavior as of 2026-06): a cluster reached
+ * by raw IP can't be classified from `peer.hostname` and gets bucketed into the
+ * synthetic `blocked-ip-address` service. Datadog instead keys entities on the
+ * `peer.db.*` tags, which it derives from short-form OTel attributes
+ * (`peer.db.name` from `db.namespace`, `peer.db.system` from `db.system`). The
+ * Node `@elastic/transport` v8 client sets `db.system` but not `db.namespace`;
+ * this fills that one gap. An existing non-empty `db.namespace` is never
+ * replaced.
+ *
+ * Why an exporter rather than a span processor: a constant like `lokalise` is a
+ * Datadog entity-keying heuristic, not the span's true OTel `db.namespace`. A
+ * mutating processor would write it into the one `ReadableSpan` shared by every
+ * processor and exporter, so any other consumer (a different dashboard, OTel-
+ * native tooling) would read it as the real namespace. An exporter is instead
+ * contractually allowed to shape its own export payload, so we wrap only the
+ * Datadog-bound exporter and leave the shared span untouched. This also sheds
+ * the fragility of mutating SDK-internal state: the original object is never
+ * written to (we return a `Proxy` overriding only `attributes`), so a future
+ * SDK that freezes span attributes cannot break this.
+ */
+export declare class DbNamespaceSpanExporter implements SpanExporter {
+    private readonly delegate;
+    private readonly dbNamespaceBySystem;
+    private readonly loggedSystems;
+    constructor(delegate: SpanExporter, options: DbNamespaceSpanExporterOptions);
+    export(spans: ReadableSpan[], resultCallback: Parameters<SpanExporter['export']>[1]): void;
+    shutdown(): Promise<void>;
+    forceFlush(): Promise<void>;
+    /**
+     * Returns the span unchanged unless it is an unmapped/already-namespaced DB
+     * span; otherwise returns a non-mutating view with `db.namespace` added.
+     */
+    private withDbNamespace;
+}
+/**
+ * Validates a `db.system` -> `db.namespace` mapping and copies it into a `Map`
+ * so later mutation of the caller's object can't bypass validation and lookups
+ * can't hit `Object.prototype`. Throws on any empty key or non-empty-string
+ * value so typos fail at startup. Exported so the bootstrap can fail fast in
+ * every environment, not only when the exporter is constructed.
+ */
+export declare function assertValidDbNamespaceBySystem(dbNamespaceBySystem: Readonly<Record<string, string>>): Map<string, string>;

package/dist/dbNamespaceSpanExporter.js

@@ -0,0 +1,114 @@
+/**
+ * A `SpanExporter` decorator that adds `db.namespace` to outbound DB spans in
+ * the export payload — based on the OTel `db.system` value — then delegates to
+ * the wrapped exporter. It exists so Datadog's APM catalog joins those spans to
+ * an existing inferred-service entity for the cluster.
+ *
+ * Why (per Datadog inferred-services behavior as of 2026-06): a cluster reached
+ * by raw IP can't be classified from `peer.hostname` and gets bucketed into the
+ * synthetic `blocked-ip-address` service. Datadog instead keys entities on the
+ * `peer.db.*` tags, which it derives from short-form OTel attributes
+ * (`peer.db.name` from `db.namespace`, `peer.db.system` from `db.system`). The
+ * Node `@elastic/transport` v8 client sets `db.system` but not `db.namespace`;
+ * this fills that one gap. An existing non-empty `db.namespace` is never
+ * replaced.
+ *
+ * Why an exporter rather than a span processor: a constant like `lokalise` is a
+ * Datadog entity-keying heuristic, not the span's true OTel `db.namespace`. A
+ * mutating processor would write it into the one `ReadableSpan` shared by every
+ * processor and exporter, so any other consumer (a different dashboard, OTel-
+ * native tooling) would read it as the real namespace. An exporter is instead
+ * contractually allowed to shape its own export payload, so we wrap only the
+ * Datadog-bound exporter and leave the shared span untouched. This also sheds
+ * the fragility of mutating SDK-internal state: the original object is never
+ * written to (we return a `Proxy` overriding only `attributes`), so a future
+ * SDK that freezes span attributes cannot break this.
+ */
+export class DbNamespaceSpanExporter {
+    delegate;
+    dbNamespaceBySystem;
+    loggedSystems = new Set();
+    constructor(delegate, options) {
+        this.delegate = delegate;
+        this.dbNamespaceBySystem = assertValidDbNamespaceBySystem(options.dbNamespaceBySystem);
+    }
+    export(spans, resultCallback) {
+        this.delegate.export(spans.map((span) => this.withDbNamespace(span)), resultCallback);
+    }
+    shutdown() {
+        return this.delegate.shutdown();
+    }
+    forceFlush() {
+        return this.delegate.forceFlush?.() ?? Promise.resolve();
+    }
+    /**
+     * Returns the span unchanged unless it is an unmapped/already-namespaced DB
+     * span; otherwise returns a non-mutating view with `db.namespace` added.
+     */
+    withDbNamespace(span) {
+        const attrs = span.attributes;
+        const dbSystem = attrs['db.system'];
+        if (typeof dbSystem !== 'string' || dbSystem.length === 0)
+            return span;
+        const mapped = this.dbNamespaceBySystem.get(dbSystem);
+        if (!mapped)
+            return span;
+        const existing = attrs['db.namespace'];
+        if (typeof existing === 'string' && existing.length > 0)
+            return span;
+        // The source span is shared with every other processor/exporter, so we must
+        // not write to it. Return a Proxy that overrides only `attributes`; all
+        // other reads (spanContext(), resource, status, …) delegate to the original
+        // with `this` bound to it.
+        const attributes = { ...attrs, 'db.namespace': mapped };
+        const view = new Proxy(span, {
+            get(target, prop, _receiver) {
+                if (prop === 'attributes')
+                    return attributes;
+                const value = Reflect.get(target, prop, target);
+                return typeof value === 'function' ? value.bind(target) : value;
+            },
+        });
+        if (!this.loggedSystems.has(dbSystem)) {
+            this.loggedSystems.add(dbSystem);
+            logEntry('info', '[OTEL] DbNamespaceSpanExporter: added db.namespace to first matching span', {
+                dbSystem,
+                dbNamespace: mapped,
+            });
+        }
+        return view;
+    }
+}
+/**
+ * Validates a `db.system` -> `db.namespace` mapping and copies it into a `Map`
+ * so later mutation of the caller's object can't bypass validation and lookups
+ * can't hit `Object.prototype`. Throws on any empty key or non-empty-string
+ * value so typos fail at startup. Exported so the bootstrap can fail fast in
+ * every environment, not only when the exporter is constructed.
+ */
+export function assertValidDbNamespaceBySystem(dbNamespaceBySystem) {
+    const map = new Map();
+    for (const [system, value] of Object.entries(dbNamespaceBySystem)) {
+        if (system.length === 0 || typeof value !== 'string' || value.length === 0) {
+            throw new Error(`DbNamespaceSpanExporter: dbNamespaceBySystem[${JSON.stringify(system)}] must map a non-empty db.system key to a non-empty db.namespace string`);
+        }
+        map.set(system, value);
+    }
+    return map;
+}
+// Mirrors the JSON log shape used by `initOpenTelemetry` so all bootstrap
+// output is greppable with the same parser. Kept local to avoid coupling this
+// file to a logger module the package doesn't otherwise need.
+function logEntry(level, msg, data) {
+    const entry = { level, time: Date.now(), msg, ...data };
+    const output = JSON.stringify(entry);
+    if (level === 'error') {
+        // biome-ignore lint/suspicious/noConsole: bootstrap logger
+        console.error(output);
+    }
+    else {
+        // biome-ignore lint/suspicious/noConsole: bootstrap logger
+        console.log(output);
+    }
+}
+//# sourceMappingURL=dbNamespaceSpanExporter.js.map

package/dist/dbNamespaceSpanExporter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dbNamespaceSpanExporter.js","sourceRoot":"","sources":["../src/dbNamespaceSpanExporter.ts"],"names":[],"mappings":"AAiBA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,OAAO,uBAAuB;IACjB,QAAQ,CAAc;IACtB,mBAAmB,CAAqB;IACxC,aAAa,GAAG,IAAI,GAAG,EAAU,CAAA;IAElD,YAAY,QAAsB,EAAE,OAAuC;QACzE,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAA;QACxB,IAAI,CAAC,mBAAmB,GAAG,8BAA8B,CAAC,OAAO,CAAC,mBAAmB,CAAC,CAAA;IACxF,CAAC;IAED,MAAM,CAAC,KAAqB,EAAE,cAAqD;QACjF,IAAI,CAAC,QAAQ,CAAC,MAAM,CAClB,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,EAC/C,cAAc,CACf,CAAA;IACH,CAAC;IAED,QAAQ;QACN,OAAO,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,CAAA;IACjC,CAAC;IAED,UAAU;QACR,OAAO,IAAI,CAAC,QAAQ,CAAC,UAAU,EAAE,EAAE,IAAI,OAAO,CAAC,OAAO,EAAE,CAAA;IAC1D,CAAC;IAED;;;OAGG;IACK,eAAe,CAAC,IAAkB;QACxC,MAAM,KAAK,GAAG,IAAI,CAAC,UAAU,CAAA;QAE7B,MAAM,QAAQ,GAAG,KAAK,CAAC,WAAW,CAAC,CAAA;QACnC,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAA;QAEtE,MAAM,MAAM,GAAG,IAAI,CAAC,mBAAmB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;QACrD,IAAI,CAAC,MAAM;YAAE,OAAO,IAAI,CAAA;QAExB,MAAM,QAAQ,GAAG,KAAK,CAAC,cAAc,CAAC,CAAA;QACtC,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,IAAI,CAAA;QAEpE,4EAA4E;QAC5E,wEAAwE;QACxE,4EAA4E;QAC5E,2BAA2B;QAC3B,MAAM,UAAU,GAAG,EAAE,GAAG,KAAK,EAAE,cAAc,EAAE,MAAM,EAAE,CAAA;QACvD,MAAM,IAAI,GAAG,IAAI,KAAK,CAAC,IAAI,EAAE;YAC3B,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,SAAS;gBACzB,IAAI,IAAI,KAAK,YAAY;oBAAE,OAAO,UAAU,CAAA;gBAC5C,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,CAAA;gBAC/C,OAAO,OAAO,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,CAAA;YACjE,CAAC;SACF,CAAC,CAAA;QAEF,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;YACtC,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;YAChC,QAAQ,CACN,MAAM,EACN,2EAA2E,EAC3E;gBACE,QAAQ;gBACR,WAAW,EAAE,MAAM;aACpB,CACF,CAAA;QACH,CAAC;QAED,OAAO,IAAI,CAAA;IACb,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,UAAU,8BAA8B,CAC5C,mBAAqD;IAErD,MAAM,GAAG,GAAG,IAAI,GAAG,EAAkB,CAAA;IACrC,KAAK,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,mBAAmB,CAAC,EAAE,CAAC;QAClE,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC3E,MAAM,IAAI,KAAK,CACb,gDAAgD,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,yEAAyE,CAChJ,CAAA;QACH,CAAC;QACD,GAAG,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAA;IACxB,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC;AAED,0EAA0E;AAC1E,8EAA8E;AAC9E,8DAA8D;AAC9D,SAAS,QAAQ,CAAC,KAAuB,EAAE,GAAW,EAAE,IAA8B;IACpF,MAAM,KAAK,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,CAAA;IACvD,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAA;IACpC,IAAI,KAAK,KAAK,OAAO,EAAE,CAAC;QACtB,2DAA2D;QAC3D,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAA;IACvB,CAAC;SAAM,CAAC;QACN,2DAA2D;QAC3D,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;IACrB,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { type SpanProcessor } from '@opentelemetry/sdk-trace-base';
+export { DbNamespaceSpanExporter, type DbNamespaceSpanExporterOptions, } from './dbNamespaceSpanExporter.ts';
 export interface OpenTelemetryOptions {
     /**
      * Paths to exclude from tracing.
@@ -15,6 +16,38 @@ export interface OpenTelemetryOptions {
      * Additional span processors to register with the OpenTelemetry SDK.
      */
     spanProcessors?: SpanProcessor[];
+    /**
+     * When true, HTTP server spans for streaming / SSE responses are excluded
+     * from the exported traces — and therefore from any latency metric or SLO
+     * derived from their span duration. An SSE connection stays open for the
+     * whole stream lifetime, so its server span's duration reflects the keep-alive
+     * window (often minutes), not the time-to-first-byte, which otherwise skews
+     * those metrics.
+     *
+     * Streaming requests are detected by the `Accept: text/event-stream` request
+     * header (what browser `EventSource` clients are required to send, and the
+     * same signal SSE content-negotiation keys on); matching spans are tagged and
+     * dropped before export. The span still starts (so trace context propagates
+     * to child spans) and stays visible to console / user-supplied span
+     * processors.
+     *
+     * @default true
+     */
+    skipStreamEndpoints?: boolean;
+    /**
+     * Maps OTel `db.system` values to the `db.namespace` to report for them. When
+     * set, the Datadog-bound trace exporter is wrapped so matching outbound DB
+     * spans carry `db.namespace` in the export payload, joining them to Datadog's
+     * existing inferred-service entity for the cluster. Only the export payload is
+     * shaped — the shared span other processors/exporters see is left untouched.
+     * See {@link DbNamespaceSpanExporter} for the full mechanics.
+     *
+     * @example
+     * ```ts
+     * dbNamespaceBySystem: { elasticsearch: 'lokalise' }
+     * ```
+     */
+    dbNamespaceBySystem?: Readonly<Record<string, string>>;
 }
 /**
  * Initialize OpenTelemetry instrumentation.

package/dist/index.js

@@ -3,6 +3,9 @@ import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentation
 import { OTLPTraceExporter as OTLPTraceExporterGrpc } from '@opentelemetry/exporter-trace-otlp-grpc';
 import { NodeSDK } from '@opentelemetry/sdk-node';
 import { BatchSpanProcessor, ConsoleSpanExporter, SimpleSpanProcessor, } from '@opentelemetry/sdk-trace-base';
+import { assertValidDbNamespaceBySystem, DbNamespaceSpanExporter, } from './dbNamespaceSpanExporter.js';
+import { STREAM_ENDPOINT_SPAN_ATTRIBUTE, StreamSpanFilteringExporter, } from './streamSpanFilteringExporter.js';
+export { DbNamespaceSpanExporter, } from './dbNamespaceSpanExporter.js';
 function createLogEntry(level, msg, data) {
     return {
         level,
@@ -40,6 +43,68 @@ const logger = {
     debug: (msgOrData, msg) => log('debug', msgOrData, msg),
 };
 const DEFAULT_SKIPPED_PATHS = ['/health', '/metrics', '/'];
+/**
+ * Marks the request's HTTP server span as a streaming/SSE endpoint when the
+ * client negotiated SSE via `Accept: text/event-stream`. Runs as the
+ * FastifyOtel `requestHook`, so the span already exists; the marker is later
+ * consumed by {@link StreamSpanFilteringExporter} to drop the span before it is
+ * exported. Browser `EventSource` clients are required to send this header, and
+ * it is the same signal SSE content-negotiation keys on.
+ */
+const markStreamEndpointSpan = (span, request) => {
+    const accept = request.headers.accept;
+    // Media types are case-insensitive (RFC 7231 §3.1.1.1), so normalize before matching.
+    if (typeof accept === 'string' && accept.toLowerCase().includes('text/event-stream')) {
+        span.setAttribute(STREAM_ENDPOINT_SPAN_ATTRIBUTE, true);
+    }
+};
+/**
+ * Builds the Fastify OpenTelemetry instrumentation.
+ */
+const createFastifyOtelInstrumentation = (skippedPaths, skipStreamEndpoints) => new FastifyOtelInstrumentation({
+    registerOnInitialization: true,
+    ignorePaths: (req) => {
+        if (!req.url)
+            return false;
+        // Extract path without query string, normalize empty to '/'
+        const path = req.url.split('?')[0] || '/';
+        return skippedPaths.includes(path);
+    },
+    requestHook: skipStreamEndpoints ? markStreamEndpointSpan : undefined,
+});
+/**
+ * Builds the OTLP trace exporter, optionally wrapped to add `db.namespace`
+ * and/or to drop streaming/SSE spans. Extracted from {@link initOpenTelemetry}
+ * to keep its cognitive complexity in check. Each wrapper shapes only its own
+ * export payload, leaving the shared span (seen by console / user span
+ * processors) untouched.
+ */
+const buildTraceExporter = (exporterUrl, validatedDbNamespaceBySystem, skipStreamEndpoints) => {
+    // Default url is grpc://localhost:4317 (see OTLPTraceExporter docs).
+    const otlpExporter = new OTLPTraceExporterGrpc({ url: exporterUrl });
+    // db.namespace is added to the export payload, not the shared span, so other
+    // processors/exporters still see the unmodified span.
+    const withDbNamespace = validatedDbNamespaceBySystem
+        ? new DbNamespaceSpanExporter(otlpExporter, {
+            dbNamespaceBySystem: validatedDbNamespaceBySystem,
+        })
+        : otlpExporter;
+    // Drop SSE/streaming server spans so their multi-minute keep-alive durations
+    // don't pollute span-duration latency metrics/SLOs.
+    return skipStreamEndpoints ? new StreamSpanFilteringExporter(withDbNamespace) : withDbNamespace;
+};
+function resolveDbNamespaceBySystem(dbNamespaceBySystem) {
+    if (!dbNamespaceBySystem)
+        return undefined;
+    if (Object.keys(dbNamespaceBySystem).length === 0) {
+        logger.warn('[OTEL] dbNamespaceBySystem was provided but contains no entries; db.namespace enrichment will not be enabled');
+        return undefined;
+    }
+    // Validate eagerly so a misconfigured mapping throws in every environment
+    // (dev, CI), not only at production startup when the exporter is built.
+    assertValidDbNamespaceBySystem(dbNamespaceBySystem);
+    return dbNamespaceBySystem;
+}
 let isInstrumentationRegistered = false;
 let sdk;
 /**
@@ -61,7 +126,7 @@ let sdk;
  * ```
  */
 export function initOpenTelemetry(options = {}) {
-    const { skippedPaths = DEFAULT_SKIPPED_PATHS, consoleSpans = false, spanProcessors = [], } = options;
+    const { skippedPaths = DEFAULT_SKIPPED_PATHS, consoleSpans = false, spanProcessors = [], dbNamespaceBySystem, skipStreamEndpoints = true, } = options;
     logger.info('[OTEL] initOpenTelemetry called');
     const isOpenTelemetryEnabled = process.env.NODE_ENV !== 'test' && process.env.OTEL_ENABLED?.toLowerCase() === 'true';
     logger.info({
@@ -71,17 +136,18 @@ export function initOpenTelemetry(options = {}) {
         skippedPaths,
         consoleSpans,
         additionalSpanProcessorsCount: spanProcessors.length,
+        dbNamespaceSystemsConfigured: dbNamespaceBySystem ? Object.keys(dbNamespaceBySystem) : [],
+        skipStreamEndpoints,
     }, '[OTEL] Configuration');
+    // Validated outside the enabled gate so a misconfigured mapping throws in
+    // every environment (dev, CI) instead of only at production startup.
+    const validatedDbNamespaceBySystem = resolveDbNamespaceBySystem(dbNamespaceBySystem);
     if (isOpenTelemetryEnabled && !isInstrumentationRegistered) {
         logger.info('[OTEL] Initializing OpenTelemetry SDK...');
         // Configure the OTLP trace exporter
         const exporterUrl = process.env.OTEL_EXPORTER_URL || 'grpc://localhost:4317';
         logger.info({ exporterUrl }, '[OTEL] Configuring trace exporter');
-        const traceExporter = new OTLPTraceExporterGrpc({
-            // optional - url default value is http://localhost:4318/v1/traces (http)
-            // or grpc://localhost:4317/opentelemetry.proto.collector.trace.v1.TraceService/Export (grpc)
-            url: exporterUrl,
-        });
+        const traceExporter = buildTraceExporter(exporterUrl, validatedDbNamespaceBySystem, skipStreamEndpoints);
         const allSpanProcessors = [
             new BatchSpanProcessor(traceExporter),
             ...spanProcessors,
@@ -95,16 +161,7 @@ export function initOpenTelemetry(options = {}) {
             spanProcessors: allSpanProcessors,
             instrumentations: [
                 getNodeAutoInstrumentations(),
-                new FastifyOtelInstrumentation({
-                    registerOnInitialization: true,
-                    ignorePaths: (req) => {
-                        if (!req.url)
-                            return false;
-                        // Extract path without query string, normalize empty to '/'
-                        const path = req.url.split('?')[0] || '/';
-                        return skippedPaths.includes(path);
-                    },
-                }),
+                createFastifyOtelInstrumentation(skippedPaths, skipStreamEndpoints),
             ],
         });
         sdk.start();

package/dist/index.js.map

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

package/dist/streamSpanFilteringExporter.d.ts

@@ -0,0 +1,35 @@
+import type { ReadableSpan, SpanExporter } from '@opentelemetry/sdk-trace-base';
+type ExportResult = Parameters<Parameters<SpanExporter['export']>[1]>[0];
+/**
+ * Attribute marker set on the HTTP server span of a streaming/SSE response.
+ * Set by this package's `requestHook` (keyed on the `Accept: text/event-stream`
+ * request header); {@link StreamSpanFilteringExporter} drops every span
+ * carrying it before those spans are exported. Internal to the package — not
+ * part of the public API surface.
+ */
+export declare const STREAM_ENDPOINT_SPAN_ATTRIBUTE = "stream.endpoint";
+/**
+ * A `SpanExporter` decorator that drops streaming/SSE server spans from the
+ * export payload, then delegates the rest to the wrapped exporter.
+ *
+ * Why: an SSE/streaming response keeps the HTTP request open for the whole
+ * lifetime of the stream (e.g. a 5-minute keep-alive), so the auto-instrumented
+ * server span's duration is the stream lifetime, not the time-to-first-byte.
+ * Any latency metric or SLO derived from that span's duration is then wrecked
+ * by those multi-minute values. Dropping the span before it is exported removes
+ * it from such metrics at the source — generically for every streaming
+ * endpoint, with no per-route exclusion list to maintain.
+ *
+ * Why an exporter rather than a span processor or sampler: it layers onto a
+ * single exporter, so console / other processors and exporters still observe
+ * the stream spans (useful for local debugging). The shared span is never
+ * mutated.
+ */
+export declare class StreamSpanFilteringExporter implements SpanExporter {
+    private readonly delegate;
+    constructor(delegate: SpanExporter);
+    export(spans: ReadableSpan[], resultCallback: (result: ExportResult) => void): void;
+    shutdown(): Promise<void>;
+    forceFlush(): Promise<void>;
+}
+export {};

package/dist/streamSpanFilteringExporter.js

@@ -0,0 +1,48 @@
+/**
+ * Attribute marker set on the HTTP server span of a streaming/SSE response.
+ * Set by this package's `requestHook` (keyed on the `Accept: text/event-stream`
+ * request header); {@link StreamSpanFilteringExporter} drops every span
+ * carrying it before those spans are exported. Internal to the package — not
+ * part of the public API surface.
+ */
+export const STREAM_ENDPOINT_SPAN_ATTRIBUTE = 'stream.endpoint';
+/**
+ * A `SpanExporter` decorator that drops streaming/SSE server spans from the
+ * export payload, then delegates the rest to the wrapped exporter.
+ *
+ * Why: an SSE/streaming response keeps the HTTP request open for the whole
+ * lifetime of the stream (e.g. a 5-minute keep-alive), so the auto-instrumented
+ * server span's duration is the stream lifetime, not the time-to-first-byte.
+ * Any latency metric or SLO derived from that span's duration is then wrecked
+ * by those multi-minute values. Dropping the span before it is exported removes
+ * it from such metrics at the source — generically for every streaming
+ * endpoint, with no per-route exclusion list to maintain.
+ *
+ * Why an exporter rather than a span processor or sampler: it layers onto a
+ * single exporter, so console / other processors and exporters still observe
+ * the stream spans (useful for local debugging). The shared span is never
+ * mutated.
+ */
+export class StreamSpanFilteringExporter {
+    delegate;
+    constructor(delegate) {
+        this.delegate = delegate;
+    }
+    export(spans, resultCallback) {
+        const kept = spans.filter((span) => span.attributes[STREAM_ENDPOINT_SPAN_ATTRIBUTE] !== true);
+        // Empty batch: some OTLP transports treat it as a timeout/error, so
+        // short-circuit with success (0 === ExportResultCode.SUCCESS).
+        if (kept.length === 0) {
+            resultCallback({ code: 0 });
+            return;
+        }
+        this.delegate.export(kept, resultCallback);
+    }
+    shutdown() {
+        return this.delegate.shutdown();
+    }
+    forceFlush() {
+        return this.delegate.forceFlush?.() ?? Promise.resolve();
+    }
+}
+//# sourceMappingURL=streamSpanFilteringExporter.js.map

package/dist/streamSpanFilteringExporter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"streamSpanFilteringExporter.js","sourceRoot":"","sources":["../src/streamSpanFilteringExporter.ts"],"names":[],"mappings":"AAKA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG,iBAAiB,CAAA;AAE/D;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAO,2BAA2B;IACrB,QAAQ,CAAc;IAEvC,YAAY,QAAsB;QAChC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAA;IAC1B,CAAC;IAED,MAAM,CAAC,KAAqB,EAAE,cAA8C;QAC1E,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,8BAA8B,CAAC,KAAK,IAAI,CAAC,CAAA;QAC7F,oEAAoE;QACpE,+DAA+D;QAC/D,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACtB,cAAc,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,CAAA;YAC3B,OAAM;QACR,CAAC;QAED,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE,cAAc,CAAC,CAAA;IAC5C,CAAC;IAED,QAAQ;QACN,OAAO,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,CAAA;IACjC,CAAC;IAED,UAAU;QACR,OAAO,IAAI,CAAC,QAAQ,CAAC,UAAU,EAAE,EAAE,IAAI,OAAO,CAAC,OAAO,EAAE,CAAA;IAC1D,CAAC;CACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lokalise/opentelemetry-fastify-bootstrap",
-  "version": "3.0.0",
+  "version": "4.0.0",
   "type": "module",
   "files": [
     "dist",
@@ -34,7 +34,7 @@
   },
   "dependencies": {},
   "peerDependencies": {
-    "@fastify/otel": "0.18.1",
+    "@fastify/otel": "0.19.0",
     "@opentelemetry/auto-instrumentations-node": "^0.76.0",
     "@opentelemetry/exporter-trace-otlp-grpc": "^0.218.0",
     "@opentelemetry/sdk-node": "^0.218.0",
@@ -42,19 +42,20 @@
     "fastify": "^5.0.0"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.3.7",
-    "@lokalise/biome-config": "^3.1.0",
-    "@lokalise/tsconfig": "^4.0.0",
+    "@biomejs/biome": "^2.5.0",
+    "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/auto-instrumentations-node": "^0.76.0",
     "@opentelemetry/exporter-trace-otlp-grpc": "^0.218.0",
     "@opentelemetry/sdk-node": "^0.218.0",
     "@opentelemetry/sdk-trace-base": "^2.7.1",
-    "@fastify/otel": "0.18.1",
-    "@vitest/coverage-v8": "^4.1.7",
+    "@fastify/otel": "0.19.0",
+    "@vitest/coverage-v8": "^4.1.9",
     "fastify": "^5.7.5",
     "rimraf": "^6.1.2",
-    "typescript": "6.0.3",
-    "vitest": "^4.1.7"
+    "typescript": "7.0.2",
+    "vitest": "^4.1.9",
+    "@lokalise/biome-config": "^3.1.1",
+    "@lokalise/tsconfig": "^5.0.0"
   },
   "scripts": {
     "build": "rimraf dist && tsc --project tsconfig.build.json",