@saidsef/tracing-node 4.3.0 → 5.0.0

package/README.md

@@ -22,6 +22,7 @@ Effortlessly supercharge your applications with world-class distributed tracing!
 | AWS SDK | Cloud service instrumentation |
 | Pino logger | Integration with trace/span IDs |
 | Node runtime metrics | Event loop, garbage collection, heap |
+| Log export | Pino records over OTLP, correlated by trace |
 | RED metrics | Request duration histograms over OTLP |
 | DNS/FS instrumentation | Optional monitoring |
 | Resource detection | Host, OS, process, container |
@@ -47,6 +48,8 @@ The W3C Trace Context propagation this library registers is what lets Tempo pair
 
 Metrics go to the same endpoint by default and land in Mimir. They are recorded before the sampler runs, so they stay complete however far trace volume is turned down.
 
+Pino log records go to the same endpoint and land in Loki, each carrying the trace and span id of the request that wrote it. No log agent or file scraping sits in between.
+
 ## Instalation
 
 ```
@@ -86,6 +89,8 @@ setupTracing({hostname: 'hostname', serviceName: 'service_name', url: 'endpoint'
 | enableMetrics | boolean | export metrics as well as traces | No | `true` |
 | metricsUrl | string | metrics endpoint, when it differs from `url` | No | `url` |
 | metricExportIntervalMillis | number | how often metrics are exported | No | `60000` |
+| enableLogs | boolean | send Pino log records over OTLP | No | `true` |
+| logsUrl | string | logs endpoint, when it differs from `url` | No | `url` |
 
 ## Documentation
 

package/libs/index.mjs

@@ -21,8 +21,10 @@ 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';
 import {OTLPMetricExporter} from '@opentelemetry/exporter-metrics-otlp-grpc';
 import {OTLPTraceExporter} from '@opentelemetry/exporter-trace-otlp-grpc';
 import {PinoInstrumentation} from '@opentelemetry/instrumentation-pino';
@@ -31,6 +33,7 @@ import {IORedisInstrumentation} from '@opentelemetry/instrumentation-ioredis';
 import {registerInstrumentations} from '@opentelemetry/instrumentation';
 import {RuntimeNodeInstrumentation} from '@opentelemetry/instrumentation-runtime-node';
 import {MeterProvider, PeriodicExportingMetricReader} from '@opentelemetry/sdk-metrics';
+import {BatchLogRecordProcessor, LoggerProvider} from '@opentelemetry/sdk-logs';
 import {FsInstrumentation} from '@opentelemetry/instrumentation-fs';
 import {resourceFromAttributes, detectResources, envDetector, hostDetector, osDetector, processDetector, serviceInstanceIdDetector} from '@opentelemetry/resources';
 import {ATTR_SERVICE_NAME} from '@opentelemetry/semantic-conventions';
@@ -69,8 +72,35 @@ 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;
 
 /**
 * Sets up tracing for the application using OpenTelemetry.
@@ -95,6 +125,8 @@ let meterProvider = null;
 * @param {boolean} [options.enableMetrics=true] - Export metrics as well as traces.
 * @param {string} [options.metricsUrl=options.url] - Endpoint for metrics, when it differs from the trace endpoint.
 * @param {number} [options.metricExportIntervalMillis=60000] - How often metrics are exported.
+* @param {boolean} [options.enableLogs=true] - Send Pino log records over OTLP.
+* @param {string} [options.logsUrl=options.url] - Endpoint for logs, when it differs from the trace endpoint.
 *
 * @returns {Tracer} - The tracer for the service.
 */
@@ -115,6 +147,8 @@ export function setupTracing(options = {}) {
     enableMetrics = true,
     metricsUrl = url,
     metricExportIntervalMillis = 60000,
+    enableLogs = true,
+    logsUrl = url,
   } = options;
 
   // Validate required parameters
@@ -149,8 +183,8 @@ export function setupTracing(options = {}) {
     explicitAttributes[ATTR_CONTAINER_NAME] = hostname;
   }
 
-  // One resource for both signals. Grafana pairs a metric with a trace on
-  // service.name, so the two providers have to carry an identical resource.
+  // One resource for every signal. Grafana pairs a metric and a log line with
+  // a trace on service.name, so the providers carry an identical resource.
   const resource = detectResources({
     detectors: [envDetector, hostDetector, osDetector, processDetector, serviceInstanceIdDetector],
   }).merge(resourceFromAttributes(explicitAttributes));
@@ -173,6 +207,22 @@ export function setupTracing(options = {}) {
     metrics.setGlobalMeterProvider(meterProvider);
   }
 
+  if (enableLogs) {
+    loggerProvider = new LoggerProvider({
+      resource,
+      processors: [
+        new BatchLogRecordProcessor({
+          exporter: new OTLPLogExporter({...exportOptions, url: logsUrl}),
+          maxQueueSize: 4096,
+          maxExportBatchSize: 1024,
+          scheduledDelayMillis: 2000,
+          exportTimeoutMillis: 10000,
+        }),
+      ],
+    });
+    logs.setGlobalLoggerProvider(loggerProvider);
+  }
+
   // Register globally. With no overrides, register() installs the modern
   // AsyncLocalStorageContextManager and a CompositePropagator of
   // W3CTraceContext + W3CBaggage - identical propagation to the previous
@@ -223,28 +273,13 @@ 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
+      // a LogRecord before it reaches a logger. With no logger provider that
+      // work is done for a no-op, so turn it off rather than pay for nothing.
+      disableLogSending: !enableLogs,
       logHook: (span, record) => {
         // trace_id/span_id/trace_flags are injected by the instrumentation by
         // default; only add service name for better log correlation.
@@ -329,6 +364,7 @@ export function setupTracing(options = {}) {
   registerInstrumentations({
     tracerProvider,
     meterProvider,
+    loggerProvider,
     instrumentations,
   });
 
@@ -337,11 +373,11 @@ export function setupTracing(options = {}) {
 }
 
 /**
-* Gracefully stops the tracing by shutting down the tracer and meter providers.
+* Gracefully stops the tracing by shutting down every provider it registered.
 *
-* This function ensures that all pending spans and metrics are exported and
-* resources are cleaned up properly. It is recommended to call this function
-* during the application's shutdown process.
+* This function ensures that all pending spans, metrics and log records are
+* exported and resources are cleaned up properly. It is recommended to call
+* this function during the application's shutdown process.
 *
 * @returns {Promise<void>} - A promise that resolves when shutdown is complete.
 */
@@ -372,8 +408,29 @@ export async function stopTracing() {
       diag.error('Error during metrics shutdown:', error);
     }
   }
+
+  if (loggerProvider) {
+    try {
+      await loggerProvider.shutdown();
+      diag.info('Logs have been successfully shut down.');
+    } catch (error) {
+      diag.error('Error during logs shutdown:', error);
+    } finally {
+      // A second setGlobalLoggerProvider is ignored, so unregister whatever the
+      // flush did, or a later setupTracing keeps writing to a dead provider.
+      loggerProvider = null;
+      logs.disable();
+    }
+  }
 }
 
+/**
+ * @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.
@@ -382,4 +439,5 @@ export async function stopTracing() {
 export function __resetTracingForTesting() {
   tracerProvider = null;
   meterProvider = null;
+  loggerProvider = null;
 }

package/libs/index.test.mjs

@@ -2,8 +2,10 @@
 import { describe, it, beforeEach, afterEach } from 'node:test';
 import assert from 'node:assert';
 import { metrics } from '@opentelemetry/api';
+import { logs } from '@opentelemetry/api-logs';
 import { MeterProvider } from '@opentelemetry/sdk-metrics';
-import { setupTracing, stopTracing, __resetTracingForTesting } from './index.mjs';
+import { LoggerProvider } from '@opentelemetry/sdk-logs';
+import { setupTracing, stopTracing, __resetTracingForTesting, __expressRequestHookForTesting } from './index.mjs';
 
 describe('setupTracing', () => {
   // Clear environment and reset tracing state before each test
@@ -105,6 +107,53 @@ describe('setupTracing', () => {
     assert.ok(metrics.getMeterProvider() instanceof MeterProvider, 'global meter provider should be the SDK one');
   });
 
+  // The Pino instrumentation sends every log record to the Logs API whether or
+  // not a provider is registered. Without one the record is built and dropped.
+  it('should register a global logger provider by default', () => {
+    setupTracing({
+      serviceName: 'test-service',
+      url: 'http://localhost:4317',
+    });
+    assert.ok(logs.getLoggerProvider() instanceof LoggerProvider, 'global logger provider should be the SDK one');
+  });
+
+  it('should leave the no-op logger provider in place when logs are disabled', () => {
+    setupTracing({
+      serviceName: 'test-service',
+      url: 'http://localhost:4317',
+      enableLogs: false,
+    });
+    assert.ok(!(logs.getLoggerProvider() instanceof LoggerProvider), 'no logger provider should be registered');
+  });
+
+  it('should accept a separate logs endpoint', () => {
+    const tracer = setupTracing({
+      serviceName: 'test-service',
+      url: 'http://localhost:4317',
+      logsUrl: 'http://localhost:4318',
+    });
+    assert.ok(tracer, 'tracer should be defined');
+    assert.ok(logs.getLoggerProvider() instanceof LoggerProvider, 'global logger provider should be the SDK one');
+  });
+
+  // Without the unregister in stopTracing the API keeps the first provider and
+  // silently ignores the second registration.
+  it('should unregister the logger provider on shutdown', async () => {
+    setupTracing({
+      serviceName: 'test-service',
+      url: 'http://localhost:4317',
+    });
+    await stopTracing();
+    assert.ok(!(logs.getLoggerProvider() instanceof LoggerProvider), 'logger provider should be unregistered');
+
+    __resetTracingForTesting();
+    setupTracing({
+      serviceName: 'test-service',
+      url: 'http://localhost:4317',
+    });
+    assert.ok(logs.getLoggerProvider() instanceof LoggerProvider, 'a later setup should register again');
+  });
+
   // Without the unregister in stopTracing the API refuses the second
   // registration and the global keeps pointing at the shut-down provider.
   it('should unregister the meter provider on shutdown', async () => {
@@ -123,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.3.0",
+  "version": "5.0.0",
   "description": "tracing NodeJS - Wrapper for OpenTelemetry instrumentation packages",
   "main": "libs/index.mjs",
   "scripts": {
@@ -33,6 +33,8 @@
   "homepage": "https://github.com/saidsef/tracing-node#readme",
   "dependencies": {
     "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/api-logs": "^0.222.0",
+    "@opentelemetry/exporter-logs-otlp-grpc": "^0.222.0",
     "@opentelemetry/exporter-metrics-otlp-grpc": "^0.222.0",
     "@opentelemetry/exporter-trace-otlp-grpc": "^0.222.0",
     "@opentelemetry/instrumentation": "^0.222.0",
@@ -47,6 +49,7 @@
     "@opentelemetry/instrumentation-runtime-node": "^0.35.0",
     "@opentelemetry/instrumentation-undici": "^0.32.0",
     "@opentelemetry/resources": "^2.11.0",
+    "@opentelemetry/sdk-logs": "^0.222.0",
     "@opentelemetry/sdk-metrics": "^2.11.0",
     "@opentelemetry/sdk-trace-base": "^2.11.0",
     "@opentelemetry/sdk-trace-node": "^2.11.0",