@carecard/telemetry 3.40.0 → 3.44.0

package/README.md

@@ -33,7 +33,7 @@ explicit narrowing in all TypeScript-family files (`.ts`, `.tsx`, `.mts`,
 ## Install
 
 ```sh
-npm install @carecard/telemetry@3.20.0 --save-exact
+npm install @carecard/telemetry@3.44.0 --save-exact
 ```
 
 ## Bootstrap
@@ -50,7 +50,7 @@ const packageJson = require('./package.json');
 const { createTelemetryShutdown, initializeServiceTelemetry } = require('@carecard/telemetry');
 
 const telemetry = initializeServiceTelemetry({
-  serviceName: 'ms-auth',
+  serviceName: 'worker',
   serviceVersion: packageJson.version,
 });
 
@@ -159,3 +159,12 @@ 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.

package/index.d.ts

@@ -1,11 +1,14 @@
+import type { IncomingMessage } from 'node:http';
 export interface TelemetryRuntime {
   forceFlush(): Promise<void>;
   shutdown(): Promise<void>;
 }
 
 export interface ServiceTelemetryOptions {
-  serviceName: `app-${string}` | `ms-${string}`;
+  serviceName: string;
   serviceVersion: string;
+  serviceNamespace?: string;
+  ignoreIncomingRequest?: (request: IncomingMessage) => boolean;
 }
 
 export interface DurableTraceContextOptions {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carecard/telemetry",
-  "version": "3.40.0",
+  "version": "3.44.0",
   "description": "Privacy-safe OpenTelemetry tracing for CareCard Node.js services",
   "main": "index.js",
   "module": "index.mjs",
@@ -19,7 +19,7 @@
     "src"
   ],
   "engines": {
-    "node": ">=24.20.0 <25"
+    "node": ">=24.21.0 <25"
   },
   "sideEffects": true,
   "repository": {
@@ -53,28 +53,28 @@
   "license": "ISC",
   "dependencies": {
     "@opentelemetry/api": "1.9.1",
-    "@opentelemetry/context-async-hooks": "2.11.0",
-    "@opentelemetry/core": "2.11.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.11.0",
-    "@opentelemetry/sdk-trace-base": "2.11.0",
-    "@opentelemetry/sdk-trace-node": "2.11.0"
+    "@opentelemetry/context-async-hooks": "2.12.0",
+    "@opentelemetry/core": "2.12.0",
+    "@opentelemetry/exporter-trace-otlp-http": "0.223.0",
+    "@opentelemetry/instrumentation": "0.223.0",
+    "@opentelemetry/instrumentation-express": "0.71.0",
+    "@opentelemetry/instrumentation-http": "0.223.0",
+    "@opentelemetry/instrumentation-kafkajs": "0.32.0",
+    "@opentelemetry/instrumentation-pg": "0.75.0",
+    "@opentelemetry/instrumentation-undici": "0.33.0",
+    "@opentelemetry/resources": "2.12.0",
+    "@opentelemetry/sdk-trace-base": "2.12.0",
+    "@opentelemetry/sdk-trace-node": "2.12.0"
   },
   "devDependencies": {
-    "@eslint/js": "9.39.5",
-    "@types/node": "25.9.9",
-    "@typescript-eslint/parser": "8.71.0",
-    "eslint": "9.39.5",
+    "@eslint/js": "10.0.1",
+    "@types/node": "24.19.2",
+    "@typescript-eslint/parser": "8.71.1",
+    "eslint": "10.12.0",
     "globals": "17.13.0",
     "husky": "9.1.7",
     "lint-staged": "17.6.0",
-    "prettier": "3.9.9",
+    "prettier": "3.9.10",
     "typescript": "6.0.3"
   },
   "overrides": {

package/src/initializeServiceTelemetry.js

@@ -15,12 +15,26 @@ const { createTraceparentOnlyPropagator } = require('./traceparentOnlyPropagator
 let activeRuntime;
 const installedShutdownHandlers = new WeakSet();
 
-// Pattern: Boundary Validation - accepts only CareCard service and server-application identities.
-function validateServiceIdentity({ serviceName, serviceVersion }) {
-  const namePattern = /^(?:app|ms)-[a-z0-9-]+$/;
+// Pattern: Boundary Validation - validates generic operational identity metadata.
+function validateServiceIdentity({
+  serviceName,
+  serviceVersion,
+  serviceNamespace,
+  ignoreIncomingRequest,
+}) {
+  const namePattern = /^[A-Za-z0-9][A-Za-z0-9._-]{0,254}$/;
   const versionPattern = /^\d+\.\d+\.\d+(?:-[a-z0-9.-]+)?$/;
-  if (!namePattern.test(serviceName)) {
-    throw new Error('serviceName must identify a CareCard server application');
+  if (typeof serviceName !== 'string' || !namePattern.test(serviceName)) {
+    throw new Error('serviceName must be a bounded operational identifier');
+  }
+  if (
+    serviceNamespace !== undefined &&
+    (typeof serviceNamespace !== 'string' || !namePattern.test(serviceNamespace))
+  ) {
+    throw new TypeError('serviceNamespace must be a bounded operational identifier');
+  }
+  if (ignoreIncomingRequest !== undefined && typeof ignoreIncomingRequest !== 'function') {
+    throw new TypeError('ignoreIncomingRequest must be a function');
   }
   if (!versionPattern.test(serviceVersion)) {
     throw new Error('serviceVersion must be a semantic version');
@@ -37,7 +51,9 @@ function createNoopRuntime() {
 function createResource(options) {
   return resourceFromAttributes({
     'service.name': options.serviceName,
-    'service.namespace': 'carecard',
+    ...(options.serviceNamespace === undefined
+      ? {}
+      : { 'service.namespace': options.serviceNamespace }),
     'service.version': options.serviceVersion,
   });
 }
@@ -81,6 +97,7 @@ function startTelemetry(options, configuration) {
   const instrumentations = registerServiceInstrumentations({
     endpoint: configuration.endpoint,
     tracerProvider: provider,
+    ignoreIncomingRequest: options.ignoreIncomingRequest,
   });
   return buildRuntime(provider, contextManager, instrumentations);
 }

package/src/instrumentations.js

@@ -7,31 +7,11 @@ const { KafkaJsInstrumentation } = require('@opentelemetry/instrumentation-kafka
 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 - produces the bracketed URL host form for DNS, IPv4, and IPv6 inputs.
 function normalizeRequestHost(requestHost) {
   const host = String(requestHost || '')
@@ -61,11 +41,11 @@ function isExporterRequest(request, endpoint) {
   );
 }
 
-function createInstrumentations(endpointUrl) {
+function createInstrumentations(endpointUrl, ignoreIncomingRequest) {
   const endpoint = new URL(endpointUrl);
   return [
     new HttpInstrumentation({
-      ignoreIncomingRequestHook: isRoutineRequest,
+      ignoreIncomingRequestHook: request => ignoreIncomingRequest?.(request) === true,
       ignoreOutgoingRequestHook: request => isExporterRequest(request, endpoint),
     }),
     new ExpressInstrumentation(),
@@ -82,7 +62,7 @@ function createInstrumentations(endpointUrl) {
 }
 
 function registerServiceInstrumentations(options) {
-  const instrumentations = createInstrumentations(options.endpoint);
+  const instrumentations = createInstrumentations(options.endpoint, options.ignoreIncomingRequest);
   registerInstrumentations({
     instrumentations,
     tracerProvider: options.tracerProvider,
@@ -92,6 +72,5 @@ function registerServiceInstrumentations(options) {
 
 module.exports = {
   createInstrumentations,
-  isRoutineRequest,
   registerServiceInstrumentations,
 };