@saidsef/tracing-node 4.4.0 → 5.0.0

package/libs/index.mjs

@@ -21,7 +21,7 @@ import {diag, DiagConsoleLogger, DiagLogLevel, metrics} from '@opentelemetry/api
 import {HttpInstrumentation} from '@opentelemetry/instrumentation-http';
 import {DnsInstrumentation} from '@opentelemetry/instrumentation-dns';
 import {ElasticsearchInstrumentation} from 'opentelemetry-instrumentation-elasticsearch';
-import {ExpressInstrumentation} from '@opentelemetry/instrumentation-express';
+import {ExpressInstrumentation, ExpressLayerType} from '@opentelemetry/instrumentation-express';
 import {logs} from '@opentelemetry/api-logs';
 import {NodeTracerProvider} from '@opentelemetry/sdk-trace-node';
 import {OTLPLogExporter} from '@opentelemetry/exporter-logs-otlp-grpc';
@@ -72,6 +72,32 @@ const setPeerService = (span, host) => {
   }
 };
 
+// The express hook runs once per layer span - every middleware, every router,
+// and the request handler. Only the request handler carries the matched route,
+// so the rest return before serialising anything.
+const expressRequestHook = (span, info) => {
+  // info is ExpressRequestInfo: { request, route, layerType }
+  if (info?.layerType !== ExpressLayerType.REQUEST_HANDLER) return;
+
+  const request = info.request;
+  if (info.route) {
+    span.setAttribute('express.route', info.route);
+  }
+  if (request?.params && Object.keys(request.params).length > 0) {
+    span.setAttribute('express.params', JSON.stringify(request.params));
+  }
+  // Names only. Query values carry tokens and personal data, and the span
+  // attribute value length limit defaults to unbounded.
+  const queryKeys = request?.query ? Object.keys(request.query) : [];
+  if (queryKeys.length > 0) {
+    span.setAttribute('express.query_keys', queryKeys.sort());
+  }
+  // Add user context if available
+  if (request?.user?.id) {
+    span.setAttribute('user.id', request.user.id);
+  }
+};
+
 let tracerProvider = null; // Declare provider in module scope for access in stopTracing
 let meterProvider = null;
 let loggerProvider = null;
@@ -247,26 +273,7 @@ export function setupTracing(options = {}) {
       requestHook: (span, request) => setPeerService(span, request?.origin),
     }),
     new ExpressInstrumentation({
-      requestHook: (span, info) => {
-        // info is ExpressRequestInfo: { request, route, layerType }
-        const request = info.request;
-        if (info.route) {
-          span.setAttribute('express.route', info.route);
-          if (request?.method) {
-            span.updateName(`${request.method} ${info.route}`);
-          }
-        }
-        if (request?.params && Object.keys(request.params).length > 0) {
-          span.setAttribute('express.params', JSON.stringify(request.params));
-        }
-        if (request?.query && Object.keys(request.query).length > 0) {
-          span.setAttribute('express.query', JSON.stringify(request.query));
-        }
-        // Add user context if available
-        if (request?.user?.id) {
-          span.setAttribute('user.id', request.user.id);
-        }
-      },
+      requestHook: expressRequestHook,
     }),
     new PinoInstrumentation({
       // Log sending is on by default, and every record is parsed and rebuilt as
@@ -417,6 +424,13 @@ export async function stopTracing() {
   }
 }
 
+/**
+ * @internal
+ * The express request hook, exposed so it can be driven without Express.
+ * DO NOT use in production code.
+ */
+export const __expressRequestHookForTesting = expressRequestHook;
+
 /**
  * @internal
  * Resets the tracer provider for testing purposes.

package/libs/index.test.mjs

@@ -5,7 +5,7 @@ import { metrics } from '@opentelemetry/api';
 import { logs } from '@opentelemetry/api-logs';
 import { MeterProvider } from '@opentelemetry/sdk-metrics';
 import { LoggerProvider } from '@opentelemetry/sdk-logs';
-import { setupTracing, stopTracing, __resetTracingForTesting } from './index.mjs';
+import { setupTracing, stopTracing, __resetTracingForTesting, __expressRequestHookForTesting } from './index.mjs';
 
 describe('setupTracing', () => {
   // Clear environment and reset tracing state before each test
@@ -172,3 +172,93 @@ describe('setupTracing', () => {
     assert.ok(metrics.getMeterProvider() instanceof MeterProvider, 'a later setup should register again');
   });
 });
+
+// The instrumentation calls the hook once per layer span, so the cheap path
+// through it matters as much as what it records.
+describe('express request hook', () => {
+  const fakeSpan = () => {
+    const attributes = {};
+    return {
+      attributes,
+      names: [],
+      setAttribute(key, value) {
+        attributes[key] = value;
+      },
+      updateName(name) {
+        this.names.push(name);
+      },
+    };
+  };
+
+  const requestHandler = (request, route = '/work/:id') => ({
+    request,
+    route,
+    layerType: 'request_handler',
+  });
+
+  it('should record route and params on a request handler layer', () => {
+    const span = fakeSpan();
+    __expressRequestHookForTesting(span, requestHandler({
+      method: 'GET',
+      params: {id: '42'},
+      query: {},
+    }));
+    assert.strictEqual(span.attributes['express.route'], '/work/:id');
+    assert.strictEqual(span.attributes['express.params'], '{"id":"42"}');
+  });
+
+  it('should ignore middleware and router layers', () => {
+    for (const layerType of ['middleware', 'router']) {
+      const span = fakeSpan();
+      __expressRequestHookForTesting(span, {
+        request: {method: 'GET', params: {id: '42'}, query: {page: '1'}},
+        route: '/work/:id',
+        layerType,
+      });
+      assert.deepStrictEqual(span.attributes, {}, `${layerType} layer should record nothing`);
+    }
+  });
+
+  // The HTTP instrumentation renames the server span from http.route already.
+  // Renaming here would relabel every middleware span with the same string.
+  it('should not rename the span', () => {
+    const span = fakeSpan();
+    __expressRequestHookForTesting(span, requestHandler({
+      method: 'GET',
+      params: {id: '42'},
+      query: {},
+    }));
+    assert.deepStrictEqual(span.names, [], 'the hook should not rename a span');
+  });
+
+  // A query string carries tokens and personal data, and the span attribute
+  // value length limit is unbounded by default.
+  it('should record query key names without their values', () => {
+    const span = fakeSpan();
+    __expressRequestHookForTesting(span, requestHandler({
+      method: 'GET',
+      params: {},
+      query: {token: 'sensitive-value', page: '2'},
+    }));
+    assert.deepStrictEqual(span.attributes['express.query_keys'], ['page', 'token']);
+    assert.strictEqual(span.attributes['express.query'], undefined, 'query values should not be recorded');
+    assert.ok(!JSON.stringify(span.attributes).includes('sensitive-value'), 'no query value should reach the span');
+  });
+
+  it('should record the user id when the application sets one', () => {
+    const span = fakeSpan();
+    __expressRequestHookForTesting(span, requestHandler({
+      method: 'GET',
+      params: {},
+      query: {},
+      user: {id: 'user-7'},
+    }));
+    assert.strictEqual(span.attributes['user.id'], 'user-7');
+  });
+
+  it('should tolerate a layer with no request', () => {
+    const span = fakeSpan();
+    assert.doesNotThrow(() => __expressRequestHookForTesting(span, {layerType: 'request_handler'}));
+    assert.deepStrictEqual(span.attributes, {});
+  });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saidsef/tracing-node",
-  "version": "4.4.0",
+  "version": "5.0.0",
   "description": "tracing NodeJS - Wrapper for OpenTelemetry instrumentation packages",
   "main": "libs/index.mjs",
   "scripts": {