@velum-labs/routekit-tracing 1.4.0 → 1.5.1

package/dist/carrier.d.ts

@@ -1,6 +1,7 @@
 import type { Context } from "@opentelemetry/api";
 export type TraceCarrier = {
     traceparent: string;
+    tracestate?: string;
     baggage?: string;
 };
 export declare function newTraceId(): string;

package/dist/carrier.js

@@ -32,6 +32,7 @@ export function carrierOf(context) {
         return newSessionCarrier().carrier;
     return {
         traceparent: target.traceparent,
+        ...(target.tracestate !== undefined ? { tracestate: target.tracestate } : {}),
         ...(target.baggage !== undefined ? { baggage: target.baggage } : {})
     };
 }
@@ -44,17 +45,24 @@ export function carrierFromHeaders(headers) {
     if (traceparent === undefined || traceparent.length === 0)
         return undefined;
     const baggage = first(headers.baggage);
-    return { traceparent, ...(baggage !== undefined && baggage.length > 0 ? { baggage } : {}) };
+    const tracestate = first(headers.tracestate);
+    return {
+        traceparent,
+        ...(tracestate !== undefined && tracestate.length > 0 ? { tracestate } : {}),
+        ...(baggage !== undefined && baggage.length > 0 ? { baggage } : {})
+    };
 }
 export function headersOf(carrier) {
     return {
         traceparent: carrier.traceparent,
+        ...(carrier.tracestate !== undefined ? { tracestate: carrier.tracestate } : {}),
         ...(carrier.baggage !== undefined ? { baggage: carrier.baggage } : {})
     };
 }
 export function envOf(carrier) {
     return {
         TRACEPARENT: carrier.traceparent,
+        ...(carrier.tracestate !== undefined ? { TRACESTATE: carrier.tracestate } : {}),
         ...(carrier.baggage !== undefined ? { BAGGAGE: carrier.baggage } : {})
     };
 }
@@ -64,6 +72,9 @@ export function carrierFromEnv(env = process.env) {
         return undefined;
     return {
         traceparent,
+        ...(env.TRACESTATE !== undefined && env.TRACESTATE.length > 0
+            ? { tracestate: env.TRACESTATE }
+            : {}),
         ...(env.BAGGAGE !== undefined && env.BAGGAGE.length > 0 ? { baggage: env.BAGGAGE } : {})
     };
 }
@@ -81,7 +92,10 @@ export function withBaggage(carrier, entries) {
         }
     }
     const baggage = [...members.values()].join(",");
-    return { traceparent: carrier.traceparent, ...(baggage.length > 0 ? { baggage } : {}) };
+    return {
+        ...carrier,
+        ...(baggage.length > 0 ? { baggage } : {})
+    };
 }
 export function baggageOf(carrier, keys) {
     if (carrier?.baggage === undefined)

package/dist/event.d.ts

@@ -0,0 +1,8 @@
+import { type Attributes } from "@opentelemetry/api";
+/** Structured OTel events use the existing provider and its export attribute policy. */
+export declare function emitTraceEvent(input: Readonly<{
+    scope: string;
+    name: string;
+    attributes: Attributes;
+    error?: boolean;
+}>): void;

package/dist/event.js

@@ -0,0 +1,17 @@
+import { context } from "@opentelemetry/api";
+import { logs, SeverityNumber } from "@opentelemetry/api-logs";
+/** Structured OTel events use the existing provider and its export attribute policy. */
+export function emitTraceEvent(input) {
+    try {
+        logs.getLogger(input.scope).emit({
+            eventName: input.name,
+            context: context.active(),
+            severityNumber: input.error ? SeverityNumber.ERROR : SeverityNumber.INFO,
+            severityText: input.error ? "ERROR" : "INFO",
+            attributes: input.attributes
+        });
+    }
+    catch {
+        // An unavailable exporter must not affect the operation being observed.
+    }
+}

package/dist/exportable.d.ts

@@ -1,8 +1,13 @@
+import type { AttributeValue } from "@opentelemetry/api";
 import type { ReadableSpan, SpanExporter } from "@opentelemetry/sdk-trace-base";
 import type { LogRecordExporter, ReadableLogRecord } from "@opentelemetry/sdk-logs";
 export type AttributePolicy = {
     allowed: ReadonlySet<string>;
     redactedAttribute: string;
+    normalizeAttribute?: (key: string, value: AttributeValue) => AttributeValue | undefined;
+    normalizeSpanName?: (span: ReadableSpan) => string;
+    normalizeEventName?: (name: string) => string;
+    normalizeSeverityText?: (value: string) => string | undefined;
 };
 export declare function toExportableSpan(span: ReadableSpan, policy: AttributePolicy): ReadableSpan;
 export declare function toExportableEvent(record: ReadableLogRecord, policy: AttributePolicy): ReadableLogRecord;

package/dist/exportable.js

@@ -1,41 +1,73 @@
+const URL_IN_SPAN_NAME = /\b[a-z][a-z0-9+.-]*:\/\/[^\s]+/gi;
+const RELATIVE_URL_QUERY_IN_SPAN_NAME = /(^|\s)(\/[^\s?#]*)[?#][^\s]*/g;
+const UUID_IN_SPAN_NAME = /\b[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\b/gi;
+function exportableSpanName(name) {
+    return name
+        .replace(URL_IN_SPAN_NAME, "[url]")
+        .replace(RELATIVE_URL_QUERY_IN_SPAN_NAME, "$1$2")
+        .replace(UUID_IN_SPAN_NAME, "[id]")
+        .slice(0, 256);
+}
 function filterAttributes(attributes, policy) {
     const kept = {};
     let dropped = 0;
+    let changed = false;
     for (const [key, value] of Object.entries(attributes)) {
-        if (policy.allowed.has(key))
-            kept[key] = value;
-        else
+        if (!policy.allowed.has(key) || value === undefined) {
+            dropped += 1;
+            continue;
+        }
+        const normalized = policy.normalizeAttribute === undefined
+            ? value
+            : policy.normalizeAttribute(key, value);
+        if (normalized === undefined)
             dropped += 1;
+        else {
+            kept[key] = normalized;
+            if (normalized !== value)
+                changed = true;
+        }
     }
-    return { kept, dropped };
+    return { kept, dropped, changed };
 }
 export function toExportableSpan(span, policy) {
     const own = filterAttributes(span.attributes, policy);
     let childDrops = 0;
+    let childChanged = false;
     const events = span.events.map((event) => {
+        const name = policy.normalizeEventName?.(event.name) ?? event.name;
+        if (name !== event.name)
+            childChanged = true;
         if (event.attributes === undefined)
-            return event;
+            return name === event.name ? event : { ...event, name };
         const filtered = filterAttributes(event.attributes, policy);
         childDrops += filtered.dropped;
-        return filtered.dropped === 0 ? event : { ...event, attributes: filtered.kept };
+        childChanged ||= filtered.changed;
+        return filtered.dropped === 0 && !filtered.changed && name === event.name
+            ? event
+            : { ...event, name, attributes: filtered.kept };
     });
     const links = span.links.map((link) => {
         if (link.attributes === undefined)
             return link;
         const filtered = filterAttributes(link.attributes, policy);
         childDrops += filtered.dropped;
-        return filtered.dropped === 0 ? link : { ...link, attributes: filtered.kept };
+        childChanged ||= filtered.changed;
+        return filtered.dropped === 0 && !filtered.changed ? link : { ...link, attributes: filtered.kept };
     });
-    if (own.dropped + childDrops === 0)
+    const name = exportableSpanName(policy.normalizeSpanName?.(span) ?? span.name);
+    const status = span.status.message === undefined ? span.status : { code: span.status.code };
+    if (own.dropped + childDrops === 0 && !own.changed && !childChanged && name === span.name && status === span.status) {
         return span;
+    }
     return {
-        name: span.name,
+        name,
         kind: span.kind,
         spanContext: () => span.spanContext(),
         ...(span.parentSpanContext !== undefined ? { parentSpanContext: span.parentSpanContext } : {}),
         startTime: span.startTime,
         endTime: span.endTime,
-        status: span.status,
+        status,
         attributes: { ...own.kept, [policy.redactedAttribute]: true },
         links,
         events,
@@ -50,16 +82,25 @@ export function toExportableSpan(span, policy) {
 }
 export function toExportableEvent(record, policy) {
     const filtered = filterAttributes(record.attributes, policy);
-    if (filtered.dropped === 0)
+    const bodyDropped = record.body !== undefined;
+    const eventName = record.eventName === undefined
+        ? undefined
+        : policy.normalizeEventName?.(record.eventName) ?? record.eventName;
+    const severityText = record.severityText === undefined
+        ? undefined
+        : policy.normalizeSeverityText === undefined
+            ? record.severityText
+            : policy.normalizeSeverityText(record.severityText);
+    if (filtered.dropped === 0 && !filtered.changed && !bodyDropped &&
+        eventName === record.eventName && severityText === record.severityText)
         return record;
     return {
         hrTime: record.hrTime,
         hrTimeObserved: record.hrTimeObserved,
         ...(record.spanContext !== undefined ? { spanContext: record.spanContext } : {}),
-        ...(record.severityText !== undefined ? { severityText: record.severityText } : {}),
+        ...(severityText !== undefined ? { severityText } : {}),
         ...(record.severityNumber !== undefined ? { severityNumber: record.severityNumber } : {}),
-        ...(record.body !== undefined ? { body: record.body } : {}),
-        ...(record.eventName !== undefined ? { eventName: record.eventName } : {}),
+        ...(eventName !== undefined ? { eventName } : {}),
         resource: record.resource,
         instrumentationScope: record.instrumentationScope,
         attributes: { ...filtered.kept, [policy.redactedAttribute]: true },

package/dist/index.d.ts

@@ -12,3 +12,4 @@ export { InMemorySpanExporter, SimpleSpanProcessor } from "@opentelemetry/sdk-tr
 export type { SpanProcessor } from "@opentelemetry/sdk-trace-base";
 export { InMemoryLogRecordExporter, SimpleLogRecordProcessor } from "@opentelemetry/sdk-logs";
 export type { LogRecordProcessor } from "@opentelemetry/sdk-logs";
+export { emitTraceEvent } from "./event.js";

package/dist/index.js

@@ -5,3 +5,4 @@ export { isLoopbackOtlpEndpoint, PolicyLogExporter, PolicySpanExporter, toExport
 export { flushTracing, initTracing, isEventExportConfigured, isTraceExportConfigured, isTracingActive, resetTracingForTest, shutdownTracing, tracingServiceName } from "./provider.js";
 export { InMemorySpanExporter, SimpleSpanProcessor } from "@opentelemetry/sdk-trace-base";
 export { InMemoryLogRecordExporter, SimpleLogRecordProcessor } from "@opentelemetry/sdk-logs";
+export { emitTraceEvent } from "./event.js";

package/dist/provider.d.ts

@@ -4,6 +4,7 @@ import type { AttributePolicy } from "./exportable.js";
 export type InitTracingOptions = {
     serviceName: string;
     attributePolicy: AttributePolicy;
+    allowLoopbackFullFidelity?: boolean;
     fullFidelityEnvironmentVariable?: string;
     logPrefix?: string;
     spanProcessors?: SpanProcessor[];

package/dist/provider.js

@@ -36,7 +36,7 @@ export function initTracing(options) {
     if (traceEndpoint !== undefined) {
         const fullFidelity = (options.fullFidelityEnvironmentVariable !== undefined &&
             process.env[options.fullFidelityEnvironmentVariable] === "1") ||
-            isLoopbackOtlpEndpoint(traceEndpoint);
+            (options.allowLoopbackFullFidelity !== false && isLoopbackOtlpEndpoint(traceEndpoint));
         if (options.logPrefix !== undefined) {
             process.stderr.write(fullFidelity
                 ? `${options.logPrefix}: exporting full traces to ${traceEndpoint}\n`
@@ -48,7 +48,7 @@ export function initTracing(options) {
     if (eventEndpoint !== undefined) {
         const fullFidelity = (options.fullFidelityEnvironmentVariable !== undefined &&
             process.env[options.fullFidelityEnvironmentVariable] === "1") ||
-            isLoopbackOtlpEndpoint(eventEndpoint);
+            (options.allowLoopbackFullFidelity !== false && isLoopbackOtlpEndpoint(eventEndpoint));
         logProcessors.push(new BatchLogRecordProcessor({
             exporter: new PolicyLogExporter(new OTLPLogExporter(), options.attributePolicy, fullFidelity),
             scheduledDelayMillis: 500
@@ -71,8 +71,10 @@ export const isTracingActive = () => provider !== undefined &&
         hasEventListeners() ||
         extraProcessorsInstalled);
 export async function flushTracing() {
-    await provider?.forceFlush().catch(() => undefined);
-    await loggerProvider?.forceFlush().catch(() => undefined);
+    await Promise.allSettled([
+        provider?.forceFlush(),
+        loggerProvider?.forceFlush()
+    ]);
 }
 export async function shutdownTracing() {
     const activeProvider = provider;

package/dist/test/tracing.test.js

@@ -1,6 +1,6 @@
 import assert from "node:assert/strict";
 import test from "node:test";
-import { baggageOf, carrierFromEnv, envOf, newSessionCarrier, traceIdOf, withBaggage } from "../index.js";
+import { baggageOf, carrierFromEnv, envOf, newSessionCarrier, toExportableEvent, toExportableSpan, traceIdOf, withBaggage } from "../index.js";
 test("generic trace carriers cross environment and baggage boundaries", () => {
     const created = newSessionCarrier();
     const enriched = withBaggage(created.carrier, { "route.owner": "example", attempt: 2 });
@@ -12,3 +12,98 @@ test("generic trace carriers cross environment and baggage boundaries", () => {
         attempt: "2"
     });
 });
+test("export policy removes URL-bearing names, status messages, and denied exception fields", () => {
+    const span = {
+        name: "fetch GET https://provider.test/private/path?token=secret",
+        status: { code: 2, message: "postgres://user:password@database/private" },
+        attributes: { "http.method": "GET", "http.url": "https://provider.test/private" },
+        events: [
+            {
+                name: "exception",
+                attributes: {
+                    "exception.type": "TypeError",
+                    "exception.message": "secret",
+                    "exception.stacktrace": "secret stack"
+                }
+            }
+        ],
+        links: [],
+        droppedAttributesCount: 0
+    };
+    const exported = toExportableSpan(span, {
+        allowed: new Set(["http.method", "exception.type"]),
+        redactedAttribute: "test.redacted"
+    });
+    assert.equal(exported.name, "fetch GET [url]");
+    assert.deepEqual(exported.status, { code: 2 });
+    assert.deepEqual(exported.attributes, { "http.method": "GET", "test.redacted": true });
+    assert.deepEqual(exported.events[0]?.attributes, {
+        "exception.type": "TypeError"
+    });
+});
+test("export policy removes log bodies even when every attribute is allowed", () => {
+    const record = {
+        body: "credential=secret",
+        attributes: { "http.method": "POST" },
+        droppedAttributesCount: 0
+    };
+    const exported = toExportableEvent(record, {
+        allowed: new Set(["http.method"]),
+        redactedAttribute: "test.redacted"
+    });
+    assert.equal(exported.body, undefined);
+    assert.deepEqual(exported.attributes, {
+        "http.method": "POST",
+        "test.redacted": true
+    });
+});
+test("W3C tracestate survives headers, environment, context and baggage enrichment", async () => {
+    const { carrierFromHeaders, carrierOf, contextOf, headersOf, initTracing, resetTracingForTest } = await import("../index.js");
+    await resetTracingForTest();
+    initTracing({ serviceName: "carrier-test", attributePolicy: { allowed: new Set(), redactedAttribute: "redacted" } });
+    try {
+        const carrier = { ...newSessionCarrier().carrier, tracestate: "vendor=opaque" };
+        const enriched = withBaggage(carrier, { stage: "checkout" });
+        assert.equal(enriched.tracestate, "vendor=opaque");
+        assert.deepEqual(carrierFromHeaders(headersOf(enriched)), enriched);
+        assert.deepEqual(carrierFromEnv(envOf(enriched)), enriched);
+        assert.equal(carrierOf(contextOf(enriched)).tracestate, "vendor=opaque");
+    }
+    finally {
+        await resetTracingForTest();
+    }
+});
+test("trace and log flushes start together even when the trace flush is pending", async () => {
+    const { initTracing, flushTracing, resetTracingForTest } = await import("../index.js");
+    await resetTracingForTest();
+    let finishTrace;
+    const pendingTrace = new Promise((resolve) => { finishTrace = resolve; });
+    let logFlushStarted = false;
+    initTracing({
+        serviceName: "parallel-flush-test",
+        attributePolicy: { allowed: new Set(), redactedAttribute: "redacted" },
+        spanProcessors: [{
+                onStart() { },
+                onEnd() { },
+                forceFlush: () => pendingTrace,
+                shutdown: async () => { }
+            }],
+        logRecordProcessors: [{
+                onEmit() { },
+                forceFlush: async () => { logFlushStarted = true; },
+                shutdown: async () => { }
+            }]
+    });
+    try {
+        const flushing = flushTracing();
+        await new Promise((resolve) => setImmediate(resolve));
+        assert.equal(logFlushStarted, true);
+        assert.ok(finishTrace);
+        finishTrace();
+        await flushing;
+    }
+    finally {
+        finishTrace?.();
+        await resetTracingForTest();
+    }
+});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@velum-labs/routekit-tracing",
   "private": false,
-  "version": "1.4.0",
+  "version": "1.5.1",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/velum-labs/routekit.git",