@carecard/telemetry 3.16.0

package/README.md

@@ -0,0 +1,136 @@
+# @carecard/telemetry
+
+Privacy-safe OpenTelemetry tracing for CareCard Node.js server processes.
+
+The package owns one explicit tracing bootstrap for CareCard services. It uses
+W3C Trace Context, exports OTLP/HTTP spans to Grafana Alloy, and instruments
+HTTP, PostgreSQL, and Kafka without sending application payloads to the tracing
+backend.
+
+## Install
+
+```sh
+npm install @carecard/telemetry@3.16.0 --save-exact
+```
+
+## Bootstrap
+
+Initialize tracing after environment configuration and before loading `http`,
+`express`, `pg`, `kafkajs`, or `undici`. Node instrumentation patches modules
+when they load, so importing those libraries first can leave requests
+uninstrumented.
+
+```js
+require('./src/config');
+
+const packageJson = require('./package.json');
+const { createTelemetryShutdown, initializeServiceTelemetry } = require('@carecard/telemetry');
+
+const telemetry = initializeServiceTelemetry({
+  serviceName: 'ms-auth',
+  serviceVersion: packageJson.version,
+});
+
+const serverRuntime = require('./src/serverRuntime');
+
+const shutdown = createTelemetryShutdown({
+  telemetryRuntime: telemetry,
+  shutdownResources: serverRuntime.shutdown,
+});
+```
+
+`installTelemetryShutdownHandlers(telemetry)` is available for small processes
+that do not already own `SIGINT` and `SIGTERM` handling. Services with an
+existing graceful-shutdown path should use `createTelemetryShutdown()` so
+application resources stop first and telemetry still flushes if cleanup fails.
+
+The Next.js dashboard calls the same initializer only from its Node.js
+`instrumentation.ts` registration hook. Browser and Edge runtimes must not load
+this package.
+
+## Configuration
+
+| Variable                             | Default                           | Meaning                                                                                                            |
+| ------------------------------------ | --------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `OTEL_SDK_DISABLED`                  | `false`                           | Set to `true` to disable the SDK. It is disabled by default when `NODE_ENV=test` unless explicitly set to `false`. |
+| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | `http://127.0.0.1:4318/v1/traces` | Alloy OTLP/HTTP trace receiver. Credentials, query parameters, and fragments are rejected.                         |
+| `OTEL_TRACES_SAMPLER`                | `parentbased_traceidratio`        | `parentbased_traceidratio`, `always_on`, or `always_off`.                                                          |
+| `OTEL_TRACES_SAMPLER_ARG`            | `1` development; `0.1` production | Root sampling ratio from `0` through `1`.                                                                          |
+
+Use a ratio of `1` for local development and Docker Desktop Kubernetes.
+Production defaults to `0.1`; the self-hosted production profile also sets it
+explicitly. Parent-based sampling preserves an upstream decision across service
+boundaries.
+
+## Propagation
+
+Automatic instrumentation creates and propagates child spans for:
+
+- inbound and outbound Node HTTP requests;
+- Express request handling;
+- PostgreSQL operations without query parameters or enhanced database
+  reporting;
+- KafkaJS producers and consumers using the existing `traceparent` message
+  header;
+- server-side `fetch` requests through Undici.
+
+Routine health, readiness, metrics, and Next.js static requests are not traced.
+Only W3C `traceparent` is propagated. Caller-provided `tracestate` is ignored,
+and baggage is intentionally not configured.
+
+For durable queues, capture the active context when creating the record and
+restore it when the record is later processed:
+
+```js
+const { captureActiveTraceparent, runWithTraceparent } = require('@carecard/telemetry');
+
+const eventMetadata = {
+  traceparent: captureActiveTraceparent(),
+};
+
+await runWithTraceparent(
+  {
+    spanName: 'outbox publish',
+    traceparent: eventMetadata.traceparent,
+  },
+  () => publishOutboxEvent(),
+);
+```
+
+Span names passed to `runWithTraceparent` must be fixed, lower-case operational
+names. Never build them from user, route, record, email, token, or payload data.
+
+## Privacy boundary
+
+The exporter applies a source-side privacy boundary before a span leaves the
+process. It keeps bounded operational fields such as route templates, HTTP
+methods and status codes, database operation names, database namespaces, and
+Kafka topic names.
+
+It removes SQL text, query parameters, message payloads, message keys, URL
+values, headers, cookies, authorization data, request and response bodies,
+client addresses, user agents, exception messages, exception stacks, status
+descriptions, dynamic span-event names, and link attributes. Grafana Alloy
+repeats defensive attribute deletion before forwarding spans to Tempo.
+
+Do not add hooks that attach domain identifiers, email addresses, JWTs, file
+names, form data, or other application values to spans.
+
+## Public API
+
+- `initializeServiceTelemetry({ serviceName, serviceVersion })`
+- `createTelemetryShutdown({ telemetryRuntime, shutdownResources })`
+- `captureActiveTraceparent()`
+- `runWithTraceparent({ spanName, traceparent }, operation)`
+- `installTelemetryShutdownHandlers(runtime)`
+
+The package exposes CommonJS, ESM, and TypeScript declarations.
+
+## Validation
+
+```sh
+npm run test:All
+npm run lint
+npm run format:check
+npm audit --audit-level=high
+```

package/index.d.ts

@@ -0,0 +1,36 @@
+export interface TelemetryRuntime {
+  forceFlush(): Promise<void>;
+  shutdown(): Promise<void>;
+}
+
+export interface ServiceTelemetryOptions {
+  serviceName: 'app-dashboard' | `ms-${string}`;
+  serviceVersion: string;
+}
+
+export interface DurableTraceContextOptions {
+  spanName: string;
+  traceparent?: string | null;
+}
+
+export interface TelemetryShutdownOptions {
+  telemetryRuntime: Pick<TelemetryRuntime, 'shutdown'>;
+  shutdownResources?: () => void | Promise<void>;
+}
+
+export declare function initializeServiceTelemetry(
+  options: ServiceTelemetryOptions,
+): TelemetryRuntime;
+
+export declare function createTelemetryShutdown(
+  options: TelemetryShutdownOptions,
+): () => Promise<void>;
+
+export declare function installTelemetryShutdownHandlers(runtime: TelemetryRuntime): void;
+
+export declare function captureActiveTraceparent(): string | undefined;
+
+export declare function runWithTraceparent<Result>(
+  options: DurableTraceContextOptions,
+  operation: () => Result | Promise<Result>,
+): Promise<Result>;

package/index.js

@@ -0,0 +1,16 @@
+'use strict';
+
+const {
+  initializeServiceTelemetry,
+  installTelemetryShutdownHandlers,
+} = require('./src/initializeServiceTelemetry');
+const { createTelemetryShutdown } = require('./src/telemetryShutdown');
+const { captureActiveTraceparent, runWithTraceparent } = require('./src/traceContext');
+
+module.exports = {
+  captureActiveTraceparent,
+  createTelemetryShutdown,
+  initializeServiceTelemetry,
+  installTelemetryShutdownHandlers,
+  runWithTraceparent,
+};

package/index.mjs

@@ -0,0 +1,9 @@
+import telemetry from './index.js';
+
+export const {
+  captureActiveTraceparent,
+  createTelemetryShutdown,
+  initializeServiceTelemetry,
+  installTelemetryShutdownHandlers,
+  runWithTraceparent,
+} = telemetry;

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@carecard/telemetry",
+  "version": "3.16.0",
+  "description": "Privacy-safe OpenTelemetry tracing for CareCard Node.js services",
+  "main": "index.js",
+  "module": "index.mjs",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./index.mjs",
+      "require": "./index.js",
+      "types": "./index.d.ts"
+    }
+  },
+  "files": [
+    "index.js",
+    "index.mjs",
+    "index.d.ts",
+    "src"
+  ],
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "sideEffects": true,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CareCard-ca/pkg-telemetry.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js test/*.test.mjs",
+    "test:types": "tsc --noEmit",
+    "test:coverage": "node --test --experimental-test-coverage --test-coverage-lines=90 --test-coverage-functions=90 --test-coverage-branches=85 test/*.test.js test/*.test.mjs",
+    "test:All": "npm run test && npm run test:types && npm run test:coverage",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "prepare": "husky",
+    "lint:fix": "eslint --fix .",
+    "lint": "eslint ."
+  },
+  "keywords": [
+    "carecard",
+    "opentelemetry",
+    "distributed-tracing",
+    "trace-context"
+  ],
+  "author": "CareCard team",
+  "license": "ISC",
+  "dependencies": {
+    "@opentelemetry/api": "1.9.1",
+    "@opentelemetry/context-async-hooks": "2.10.0",
+    "@opentelemetry/core": "2.10.0",
+    "@opentelemetry/exporter-trace-otlp-http": "0.221.0",
+    "@opentelemetry/instrumentation": "0.221.0",
+    "@opentelemetry/instrumentation-express": "0.69.0",
+    "@opentelemetry/instrumentation-http": "0.221.0",
+    "@opentelemetry/instrumentation-kafkajs": "0.30.0",
+    "@opentelemetry/instrumentation-pg": "0.73.0",
+    "@opentelemetry/instrumentation-undici": "0.31.0",
+    "@opentelemetry/resources": "2.10.0",
+    "@opentelemetry/sdk-trace-base": "2.10.0",
+    "@opentelemetry/sdk-trace-node": "2.10.0"
+  },
+  "devDependencies": {
+    "@types/node": "25.9.3",
+    "eslint": "9.39.4",
+    "husky": "9.1.7",
+    "prettier": "3.8.4",
+    "typescript": "6.0.3"
+  },
+  "overrides": {
+    "brace-expansion": "5.0.8",
+    "minimatch": "10.2.6"
+  }
+}

package/src/configuration.js

@@ -0,0 +1,64 @@
+'use strict';
+
+const DEFAULT_ENDPOINT = 'http://127.0.0.1:4318/v1/traces';
+const DEFAULT_SAMPLER = 'parentbased_traceidratio';
+const SUPPORTED_SAMPLERS = new Set(['always_off', 'always_on', 'parentbased_traceidratio']);
+
+function parseBoolean(value, defaultValue) {
+  if (value === undefined) {
+    return defaultValue;
+  }
+  if (value === 'true' || value === 'false') {
+    return value === 'true';
+  }
+  throw new Error('OTEL_SDK_DISABLED must be true or false');
+}
+
+function parseEndpoint(value = DEFAULT_ENDPOINT) {
+  let endpoint;
+  try {
+    endpoint = new URL(value);
+  } catch {
+    throw new Error('OTEL_EXPORTER_OTLP_TRACES_ENDPOINT must be a valid http or https URL');
+  }
+  if (!['http:', 'https:'].includes(endpoint.protocol)) {
+    throw new Error('OTEL_EXPORTER_OTLP_TRACES_ENDPOINT must be a valid http or https URL');
+  }
+  if (endpoint.username || endpoint.password || endpoint.search || endpoint.hash) {
+    throw new Error(
+      'OTEL_EXPORTER_OTLP_TRACES_ENDPOINT must not contain credentials, query parameters, or fragments',
+    );
+  }
+  return endpoint.toString();
+}
+
+function parseSampler(value = DEFAULT_SAMPLER) {
+  const samplerName = value.toLowerCase();
+  if (!SUPPORTED_SAMPLERS.has(samplerName)) {
+    throw new Error('OTEL_TRACES_SAMPLER must be a supported sampler');
+  }
+  return samplerName;
+}
+
+function parseSamplingRatio(value = '1') {
+  const ratio = Number(value);
+  if (!Number.isFinite(ratio) || ratio < 0 || ratio > 1) {
+    throw new Error('OTEL_TRACES_SAMPLER_ARG must be between 0 and 1');
+  }
+  return ratio;
+}
+
+function readTelemetryConfiguration(environment = process.env) {
+  const testDefault = environment.NODE_ENV === 'test';
+  const defaultSamplingRatio = environment.NODE_ENV === 'production' ? '0.1' : '1';
+  return {
+    disabled: parseBoolean(environment.OTEL_SDK_DISABLED, testDefault),
+    endpoint: parseEndpoint(environment.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT),
+    samplerName: parseSampler(environment.OTEL_TRACES_SAMPLER),
+    samplingRatio: parseSamplingRatio(environment.OTEL_TRACES_SAMPLER_ARG ?? defaultSamplingRatio),
+  };
+}
+
+module.exports = {
+  readTelemetryConfiguration,
+};

package/src/initializeServiceTelemetry.js

@@ -0,0 +1,132 @@
+'use strict';
+
+const { AsyncLocalStorageContextManager } = require('@opentelemetry/context-async-hooks');
+const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http');
+const { resourceFromAttributes } = require('@opentelemetry/resources');
+const { BatchSpanProcessor } = require('@opentelemetry/sdk-trace-base');
+const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
+
+const { readTelemetryConfiguration } = require('./configuration');
+const { registerServiceInstrumentations } = require('./instrumentations');
+const { PrivacySafeSpanExporter } = require('./privacySafeSpanExporter');
+const { createSampler } = require('./sampler');
+const { createTraceparentOnlyPropagator } = require('./traceparentOnlyPropagator');
+
+let activeRuntime;
+const installedShutdownHandlers = new WeakSet();
+
+function validateServiceIdentity({ serviceName, serviceVersion }) {
+  const namePattern = /^(?:ms-[a-z0-9-]+|app-dashboard)$/;
+  const versionPattern = /^\d+\.\d+\.\d+(?:-[a-z0-9.-]+)?$/;
+  if (!namePattern.test(serviceName)) {
+    throw new Error('serviceName must identify a CareCard server application');
+  }
+  if (!versionPattern.test(serviceVersion)) {
+    throw new Error('serviceVersion must be a semantic version');
+  }
+}
+
+function createNoopRuntime() {
+  return Object.freeze({
+    forceFlush: async () => undefined,
+    shutdown: async () => undefined,
+  });
+}
+
+function createResource(options) {
+  return resourceFromAttributes({
+    'service.name': options.serviceName,
+    'service.namespace': 'carecard',
+    'service.version': options.serviceVersion,
+  });
+}
+
+function createProvider(options, configuration) {
+  const exporter = new OTLPTraceExporter({ url: configuration.endpoint });
+  const processor = new BatchSpanProcessor(new PrivacySafeSpanExporter(exporter));
+  return new NodeTracerProvider({
+    resource: createResource(options),
+    sampler: createSampler(configuration),
+    spanProcessors: [processor],
+  });
+}
+
+function buildRuntime(provider, contextManager, instrumentations) {
+  let stopped = false;
+  return {
+    forceFlush: () => provider.forceFlush(),
+    async shutdown() {
+      if (stopped) {
+        return;
+      }
+      stopped = true;
+      try {
+        await provider.shutdown();
+      } finally {
+        instrumentations.forEach((instrumentation) => instrumentation.disable());
+        contextManager.disable();
+      }
+    },
+  };
+}
+
+function startTelemetry(options, configuration) {
+  const contextManager = new AsyncLocalStorageContextManager();
+  const provider = createProvider(options, configuration);
+  provider.register({
+    contextManager,
+    propagator: createTraceparentOnlyPropagator(),
+  });
+  const instrumentations = registerServiceInstrumentations({
+    endpoint: configuration.endpoint,
+    tracerProvider: provider,
+  });
+  return buildRuntime(provider, contextManager, instrumentations);
+}
+
+function initializeServiceTelemetry(options) {
+  validateServiceIdentity(options);
+  const configuration = readTelemetryConfiguration();
+  if (configuration.disabled) {
+    return createNoopRuntime();
+  }
+  activeRuntime ||= startTelemetry(options, configuration);
+  return activeRuntime;
+}
+
+function installTelemetryShutdownHandlers(runtime) {
+  if (installedShutdownHandlers.has(runtime)) {
+    return;
+  }
+  installedShutdownHandlers.add(runtime);
+  installTelemetrySignalHandler(runtime, 'SIGINT');
+  installTelemetrySignalHandler(runtime, 'SIGTERM');
+}
+
+// Pattern: Signal Adapter - flushes telemetry and leaves an existing lifecycle owner in control.
+function installTelemetrySignalHandler(runtime, signal) {
+  process.once(signal, async () => {
+    try {
+      await runtime.shutdown();
+    } catch (error) {
+      reportShutdownFailure(error);
+    }
+    preserveSignalTermination(signal);
+  });
+}
+
+// Pattern: Lifecycle Fallback - restores default termination when telemetry was the only listener.
+function preserveSignalTermination(signal) {
+  if (process.listenerCount(signal) === 0) {
+    process.kill(process.pid, signal);
+  }
+}
+
+function reportShutdownFailure(error) {
+  console.error('Telemetry shutdown failed', error);
+}
+
+module.exports = {
+  initializeServiceTelemetry,
+  installTelemetryShutdownHandlers,
+};

package/src/instrumentations.js

@@ -0,0 +1,84 @@
+'use strict';
+
+const { registerInstrumentations } = require('@opentelemetry/instrumentation');
+const { ExpressInstrumentation } = require('@opentelemetry/instrumentation-express');
+const { HttpInstrumentation } = require('@opentelemetry/instrumentation-http');
+const { KafkaJsInstrumentation } = require('@opentelemetry/instrumentation-kafkajs');
+const { PgInstrumentation } = require('@opentelemetry/instrumentation-pg');
+const { UndiciInstrumentation } = require('@opentelemetry/instrumentation-undici');
+
+const IGNORED_REQUEST_PATHS = new Set([
+  '/api/health',
+  '/favicon.ico',
+  '/health',
+  '/health-check',
+  '/healthz',
+  '/metrics',
+  '/ready',
+  '/readyz',
+]);
+
+function requestPath(request) {
+  const rawPath = request.url || request.path || '/';
+  return String(rawPath).split('?')[0];
+}
+
+function isRoutineRequest(request) {
+  const path = requestPath(request);
+  return (
+    IGNORED_REQUEST_PATHS.has(path) ||
+    path.startsWith('/_next/image') ||
+    path.startsWith('/_next/static/')
+  );
+}
+
+// Pattern: Normalizer - creates the endpoint host form without duplicating a supplied port.
+function requestHostWithPort(request) {
+  const requestHost = request.hostname || request.host || request.origin;
+  const normalizedHost = String(requestHost || '').replace(/^https?:\/\//, '');
+  if (!request.port || normalizedHost.includes(':')) {
+    return normalizedHost;
+  }
+  return `${normalizedHost}:${request.port}`;
+}
+
+function isExporterRequest(request, endpoint) {
+  return (
+    requestHostWithPort(request) === endpoint.host && requestPath(request) === endpoint.pathname
+  );
+}
+
+function createInstrumentations(endpointUrl) {
+  const endpoint = new URL(endpointUrl);
+  return [
+    new HttpInstrumentation({
+      ignoreIncomingRequestHook: isRoutineRequest,
+      ignoreOutgoingRequestHook: (request) => isExporterRequest(request, endpoint),
+    }),
+    new ExpressInstrumentation(),
+    new PgInstrumentation({
+      addSqlCommenterCommentToQueries: false,
+      enableTraceContextPropagation: false,
+      enhancedDatabaseReporting: false,
+    }),
+    new KafkaJsInstrumentation(),
+    new UndiciInstrumentation({
+      ignoreRequestHook: (request) => isExporterRequest(request, endpoint),
+    }),
+  ];
+}
+
+function registerServiceInstrumentations(options) {
+  const instrumentations = createInstrumentations(options.endpoint);
+  registerInstrumentations({
+    instrumentations,
+    tracerProvider: options.tracerProvider,
+  });
+  return instrumentations;
+}
+
+module.exports = {
+  createInstrumentations,
+  isRoutineRequest,
+  registerServiceInstrumentations,
+};

package/src/privacySafeSpanExporter.js

@@ -0,0 +1,145 @@
+'use strict';
+
+const SAFE_ATTRIBUTE_NAMES = new Set([
+  'db.namespace',
+  'db.operation.name',
+  'db.system',
+  'db.system.name',
+  'error.type',
+  'http.request.method',
+  'http.response.status_code',
+  'http.route',
+  'messaging.batch.message_count',
+  'messaging.destination.name',
+  'messaging.kafka.consumer.group',
+  'messaging.operation.name',
+  'messaging.operation.type',
+  'messaging.system',
+  'network.protocol.name',
+  'network.protocol.version',
+  'network.transport',
+  'server.port',
+  'url.scheme',
+]);
+const SAFE_HTTP_METHODS = new Set([
+  'CONNECT',
+  'DELETE',
+  'GET',
+  'HEAD',
+  'OPTIONS',
+  'PATCH',
+  'POST',
+  'PUT',
+  'TRACE',
+]);
+const SAFE_TEXT_PATTERN = /^[a-zA-Z0-9_.:*/ -]+$/;
+const SAFE_SPAN_NAME_PATTERN = /^[a-z][a-z]*(?:[ .:_-][a-z]+)*$/;
+const SAFE_EVENT_NAMES = new Set(['exception']);
+const MAX_ATTRIBUTE_LENGTH = 256;
+
+function sanitizeAttributeValue(value) {
+  if (typeof value === 'number' || typeof value === 'boolean') {
+    return value;
+  }
+  if (typeof value !== 'string' || value.length > MAX_ATTRIBUTE_LENGTH) {
+    return undefined;
+  }
+  return SAFE_TEXT_PATTERN.test(value) ? value : undefined;
+}
+
+function sanitizeSpanAttributeValue(name, value) {
+  if (name === 'http.request.method') {
+    return SAFE_HTTP_METHODS.has(value) ? value : undefined;
+  }
+  return sanitizeAttributeValue(value);
+}
+
+function sanitizeSpanAttributes(attributes = {}) {
+  return Object.fromEntries(
+    Object.entries(attributes).flatMap(([name, value]) => {
+      if (!SAFE_ATTRIBUTE_NAMES.has(name)) {
+        return [];
+      }
+      const safeValue = sanitizeSpanAttributeValue(name, value);
+      return safeValue === undefined ? [] : [[name, safeValue]];
+    }),
+  );
+}
+
+function sanitizeEvents(events = []) {
+  return events.map((event) => ({
+    ...event,
+    name: SAFE_EVENT_NAMES.has(event.name) ? event.name : 'event',
+    attributes: sanitizeExceptionAttributes(event.attributes),
+  }));
+}
+
+function sanitizeExceptionAttributes(attributes = {}) {
+  const exceptionType = sanitizeAttributeValue(attributes['exception.type']);
+  return exceptionType ? { 'exception.type': exceptionType } : {};
+}
+
+function sanitizeLinks(links = []) {
+  return links.map((link) => ({ ...link, attributes: {} }));
+}
+
+function buildSemanticSpanName(attributes) {
+  if (attributes['http.request.method']) {
+    return `${attributes['http.request.method']} ${attributes['http.route'] || 'request'}`;
+  }
+  if (attributes['db.operation.name']) {
+    return `db ${String(attributes['db.operation.name']).toLowerCase()}`;
+  }
+  if (attributes['messaging.operation.name']) {
+    return `messaging ${String(attributes['messaging.operation.name']).toLowerCase()}`;
+  }
+  return undefined;
+}
+
+function sanitizeSpanName(span, attributes) {
+  const semanticName = buildSemanticSpanName(attributes);
+  if (semanticName) {
+    return semanticName;
+  }
+  return SAFE_SPAN_NAME_PATTERN.test(span.name) ? span.name : 'operation';
+}
+
+function sanitizeSpan(span) {
+  const attributes = sanitizeSpanAttributes(span.attributes);
+  const overrides = {
+    attributes,
+    events: sanitizeEvents(span.events),
+    links: sanitizeLinks(span.links),
+    name: sanitizeSpanName(span, attributes),
+    status: { code: span.status.code },
+  };
+  return new Proxy(span, {
+    get(target, property) {
+      const value = property in overrides ? overrides[property] : Reflect.get(target, property);
+      return typeof value === 'function' ? value.bind(target) : value;
+    },
+  });
+}
+
+class PrivacySafeSpanExporter {
+  constructor(delegate) {
+    this.delegate = delegate;
+  }
+
+  export(spans, callback) {
+    this.delegate.export(spans.map(sanitizeSpan), callback);
+  }
+
+  forceFlush() {
+    return this.delegate.forceFlush?.() || Promise.resolve();
+  }
+
+  shutdown() {
+    return this.delegate.shutdown();
+  }
+}
+
+module.exports = {
+  PrivacySafeSpanExporter,
+  sanitizeSpanAttributes,
+};

package/src/sampler.js

@@ -0,0 +1,24 @@
+'use strict';
+
+const {
+  AlwaysOffSampler,
+  AlwaysOnSampler,
+  ParentBasedSampler,
+  TraceIdRatioBasedSampler,
+} = require('@opentelemetry/sdk-trace-base');
+
+function createSampler({ samplerName, samplingRatio }) {
+  if (samplerName === 'always_off') {
+    return new AlwaysOffSampler();
+  }
+  if (samplerName === 'always_on') {
+    return new AlwaysOnSampler();
+  }
+  return new ParentBasedSampler({
+    root: new TraceIdRatioBasedSampler(samplingRatio),
+  });
+}
+
+module.exports = {
+  createSampler,
+};

package/src/telemetryShutdown.js

@@ -0,0 +1,29 @@
+'use strict';
+
+// Pattern: Decorator - preserves application cleanup order and always stops telemetry.
+function createTelemetryShutdown({ telemetryRuntime, shutdownResources = async () => undefined }) {
+  if (typeof telemetryRuntime?.shutdown !== 'function' || typeof shutdownResources !== 'function') {
+    throw new TypeError('telemetryRuntime.shutdown and shutdownResources must be functions');
+  }
+  return async function shutdownResourcesAndTelemetry() {
+    const failures = [];
+    await captureShutdownFailure(shutdownResources, failures);
+    await captureShutdownFailure(() => telemetryRuntime.shutdown(), failures);
+    if (failures.length) {
+      throw new AggregateError(failures, 'Service resource shutdown failed');
+    }
+  };
+}
+
+// Pattern: Error Collector - records one cleanup failure without skipping later cleanup.
+async function captureShutdownFailure(shutdownOperation, failures) {
+  try {
+    await shutdownOperation();
+  } catch (error) {
+    failures.push(error);
+  }
+}
+
+module.exports = {
+  createTelemetryShutdown,
+};

package/src/traceContext.js

@@ -0,0 +1,78 @@
+'use strict';
+
+const {
+  ROOT_CONTEXT,
+  SpanKind,
+  SpanStatusCode,
+  context,
+  propagation,
+  trace,
+} = require('@opentelemetry/api');
+
+const TRACEPARENT_HEADER = 'traceparent';
+const SAFE_SPAN_NAME_PATTERN = /^[a-z][a-z]*(?:[ .:_-][a-z]+)*$/;
+const MAX_SPAN_NAME_LENGTH = 64;
+const carrierGetter = {
+  get(carrier, key) {
+    return carrier[key];
+  },
+  keys(carrier) {
+    return Object.keys(carrier);
+  },
+};
+const carrierSetter = {
+  set(carrier, key, value) {
+    carrier[key] = value;
+  },
+};
+
+function captureActiveTraceparent() {
+  const carrier = {};
+  propagation.inject(context.active(), carrier, carrierSetter);
+  return carrier[TRACEPARENT_HEADER];
+}
+
+function validateOperation(spanName, operation) {
+  if (typeof operation !== 'function') {
+    throw new TypeError('operation must be a function');
+  }
+  if (
+    typeof spanName !== 'string' ||
+    spanName.length > MAX_SPAN_NAME_LENGTH ||
+    !SAFE_SPAN_NAME_PATTERN.test(spanName)
+  ) {
+    throw new TypeError('spanName must be a fixed privacy-safe operation name');
+  }
+}
+
+function extractParentContext(traceparent) {
+  if (typeof traceparent !== 'string') {
+    return ROOT_CONTEXT;
+  }
+  return propagation.extract(ROOT_CONTEXT, { traceparent }, carrierGetter);
+}
+
+async function invokeOperation(span, operation) {
+  try {
+    return await operation();
+  } catch (error) {
+    span.setStatus({ code: SpanStatusCode.ERROR });
+    throw error;
+  } finally {
+    span.end();
+  }
+}
+
+async function runWithTraceparent({ spanName, traceparent }, operation) {
+  validateOperation(spanName, operation);
+  const tracer = trace.getTracer('@carecard/telemetry');
+  const parentContext = extractParentContext(traceparent);
+  return tracer.startActiveSpan(spanName, { kind: SpanKind.INTERNAL }, parentContext, (span) =>
+    invokeOperation(span, operation),
+  );
+}
+
+module.exports = {
+  captureActiveTraceparent,
+  runWithTraceparent,
+};

package/src/traceparentOnlyPropagator.js

@@ -0,0 +1,56 @@
+'use strict';
+
+const { W3CTraceContextPropagator } = require('@opentelemetry/core');
+
+const TRACEPARENT_HEADER = 'traceparent';
+const TRACESTATE_HEADER = 'tracestate';
+
+// Pattern: Protocol Adapter - delegates W3C parsing while exposing only CareCard traceparent.
+class TraceparentOnlyPropagator {
+  constructor() {
+    this.delegate = new W3CTraceContextPropagator();
+  }
+
+  inject(context, carrier, setter) {
+    this.delegate.inject(context, carrier, createTraceparentSetter(setter));
+  }
+
+  extract(context, carrier, getter) {
+    return this.delegate.extract(context, carrier, createTraceparentGetter(getter));
+  }
+
+  fields() {
+    return [TRACEPARENT_HEADER];
+  }
+}
+
+// Pattern: Filtering Adapter - prevents W3C tracestate from entering active context.
+function createTraceparentGetter(getter) {
+  return {
+    get(carrier, key) {
+      return key.toLowerCase() === TRACESTATE_HEADER ? undefined : getter.get(carrier, key);
+    },
+    keys(carrier) {
+      return getter.keys(carrier).filter((key) => key.toLowerCase() !== TRACESTATE_HEADER);
+    },
+  };
+}
+
+// Pattern: Filtering Adapter - prevents any propagation field except traceparent from leaving.
+function createTraceparentSetter(setter) {
+  return {
+    set(carrier, key, value) {
+      if (key.toLowerCase() === TRACEPARENT_HEADER) {
+        setter.set(carrier, key, value);
+      }
+    },
+  };
+}
+
+function createTraceparentOnlyPropagator() {
+  return new TraceparentOnlyPropagator();
+}
+
+module.exports = {
+  createTraceparentOnlyPropagator,
+};