@carecard/telemetry

Release 1.1.1 and production data

CareCard Release 1.1.1 is the production baseline. Seeding with --seed-release-data is complete. Production cluster data, database rows, and stored user files will be preserved going forward. There will be no complete user-data wipeout and re-creation.

Future production changes must use data-preserving migrations. Do not replay the completed initialization or run reset, rollback, or seed workflows as part of ordinary production deployment.

The completed seed inventory and verification record documents the accepted release baseline and verification limitations.

Privacy-safe OpenTelemetry tracing for CareCard Node.js server processes.

Mandatory repository policy: load $pkg-telemetry-coding-standards-and-best-practices before changing, reviewing, testing, documenting, or releasing this package.

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.

Non-negotiable TypeScript type rule: Never use the TypeScript type any; always use specific domain types, generics, existing project types, or unknown with explicit narrowing in all TypeScript-family files (.ts, .tsx, .mts, .cts, and .d.ts).

Install

npm install @carecard/[email protected] --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.

require('./src/config');

const packageJson = require('./package.json');
const { createTelemetryShutdown, initializeServiceTelemetry } = require('@carecard/telemetry');

const telemetry = initializeServiceTelemetry({
  serviceName: 'worker',
  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

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:

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 }) accepts CareCard app-* and ms-* runtime identities, including app-auth and app-dashboard.
• createTelemetryShutdown({ telemetryRuntime, shutdownResources })
• captureActiveTraceparent()
• runWithTraceparent({ spanName, traceparent }, operation)
• installTelemetryShutdownHandlers(runtime)

The package exposes CommonJS, ESM, and TypeScript declarations.

Validation

npm run test:All
npm run lint
npm run format:check
npm audit --audit-level=high

Caller-owned identity and exclusions

Service names are generic bounded operational identifiers. Set serviceNamespace explicitly when needed. There is no built-in application naming rule, namespace, health route list, or framework route exclusion. Supply ignoreIncomingRequest with a boolean decision for the owning service or application. Outgoing exports remain excluded to avoid telemetry recursion. Privacy sanitization and W3C propagation remain technical package responsibilities.