@saidsef/tracing-node 3.22.6 → 4.0.0

package/README.md

@@ -36,6 +36,33 @@ Effortlessly supercharge your applications with world-class distributed tracing!
 npm install @saidsef/tracing-node --save
 ```
 
+## Upgrading to 4.0.0
+
+**Breaking change: spans now carry the stable OpenTelemetry semantic conventions.**
+
+The upstream instrumentations ([open-telemetry/opentelemetry-js-contrib#3585](https://github.com/open-telemetry/opentelemetry-js-contrib/pull/3585)) dropped the legacy attributes and removed the `OTEL_SEMCONV_STABILITY_OPT_IN` escape hatch, so there is no way to keep the old names. The public API of `setupTracing` / `stopTracing` is unchanged - no code changes are required - but any dashboard, alert or processor keyed on the old attribute names must be updated.
+
+| Removed | Replacement | Affected spans |
+|---------|-------------|----------------|
+| `http.method` | `http.request.method` | HTTP |
+| `http.status_code` | `http.response.status_code` | HTTP, AWS SDK |
+| `http.url` | `url.full` | HTTP |
+| `http.target` | `url.path` + `url.query` | HTTP |
+| `http.scheme` | `url.scheme` | HTTP |
+| `http.user_agent` | `user_agent.original` | HTTP |
+| `http.client_ip` | `client.address` | HTTP |
+| `http.flavor` | `network.protocol.version` | HTTP |
+| `net.peer.name` | `server.address` | HTTP, IORedis |
+| `net.peer.port` | `server.port` | HTTP, IORedis |
+| `db.system` | `db.system.name` | IORedis, DynamoDB |
+| `db.statement` | `db.query.text` | IORedis, DynamoDB |
+| `db.operation` | `db.operation.name` | IORedis, DynamoDB |
+| `db.connection_string` | none | IORedis |
+
+Server-side HTTP metrics also move from `http.server.duration` (milliseconds) to `http.server.request.duration` (seconds), and the client equivalents likewise.
+
+`peer.service` is unchanged, so Tempo/Grafana service graphs keep working as before. IORedis spans also gain `db.operation.name`, which distinguishes `MULTI`/`PIPELINE` commands.
+
 ## Usage
 
 You can set required params via env variables or function:

package/libs/index.mjs

@@ -43,6 +43,15 @@ const setIntAttribute = (span, name, value) => {
   }
 };
 
+// Slice before converting: String(buf) decodes a whole 1MB Buffer only to throw
+// it away. 4 bytes per UTF-16 unit plus slack keeps the result byte-identical.
+const truncateArg = (value, limit) => {
+  const str = Buffer.isBuffer(value) ? value.subarray(0, limit * 4 + 8).toString() : String(value);
+  return str.length > limit ? `${str.substring(0, limit)}...` : str;
+};
+
+let tracerProvider = null; // Declare provider in module scope for access in stopTracing
+
 /**
 * Sets up tracing for the application using OpenTelemetry.
 *
@@ -53,7 +62,7 @@ const setIntAttribute = (span, name, value) => {
 * service map visualization in distributed tracing tools like Tempo.
 *
 * @param {Object} options - Configuration options for tracing.
-* @param {string} [options.hostname=process.env.HOSTNAME] - The hostname of the service.
+* @param {string} [options.hostname=process.env.CONTAINER_NAME || process.env.HOSTNAME] - The hostname of the service.
 * @param {string} [options.serviceName=process.env.SERVICE_NAME] - The name of the service.
 * @param {string} [options.url=process.env.ENDPOINT] - The endpoint URL for the tracing collector.
 * @param {number} [options.concurrencyLimit=10] - The concurrency limit for the exporter.
@@ -62,12 +71,10 @@ const setIntAttribute = (span, name, value) => {
 *
 * @returns {Tracer} - The tracer for the service.
 */
-let tracerProvider = null; // Declare provider in module scope for access in stopTracing
-
 export function setupTracing(options = {}) {
   // Prevent multiple initializations - return existing provider if already set up
   if (tracerProvider) {
-    console.warn('Tracing is already initialized. Returning existing tracer.');
+    diag.warn('Tracing is already initialized. Returning existing tracer.');
     return tracerProvider.getTracer(options.serviceName || process.env.SERVICE_NAME);
   }
 
@@ -95,10 +102,8 @@ export function setupTracing(options = {}) {
     timeoutMillis: 10000,
   };
 
-  // Register the span processor with the tracer provider
   const exporter = new OTLPTraceExporter(exportOptions);
 
-  // Configure BatchSpanProcessor for production workloads
   const spanProcessor = new BatchSpanProcessor(exporter, {
     maxQueueSize: 4096,
     maxExportBatchSize: 1024,
@@ -127,69 +132,49 @@ export function setupTracing(options = {}) {
   // explicit config, with the recommended context manager.
   tracerProvider.register();
 
-  // Hook to set peer service name for outgoing requests
+  // Only an outgoing ClientRequest carries .host, so bailing without it keeps
+  // server spans out: peer.service must name the remote service being called.
   const applyCustomAttributesOnSpan = (span, request) => {
-    const url = request?.url || request?.uri || '';
-    const hostname = request?.hostname || request?.host || '';
-    
-    // Detect Elasticsearch endpoints
-    if (hostname.includes('elasticsearch') || url.includes('elasticsearch') || 
-        hostname.includes(':9200') || url.includes(':9200')) {
-      span.setAttribute('peer.service', 'elasticsearch');
-      span.setAttribute('db.system', 'elasticsearch');
-    }
-
-    // Detect Redis endpoints
-    if (hostname.includes('redis') || url.includes('redis') || 
-        hostname.includes(':6379') || url.includes(':6379')) {
-      span.setAttribute('peer.service', 'redis');
-      span.setAttribute('db.system', 'redis');
+    const host = request?.host;
+    if (!host) return;
+
+    for (const service of ['elasticsearch', 'redis']) {
+      if (host.includes(service)) {
+        span.setAttribute('peer.service', service);
+        span.setAttribute('db.system.name', service);
+        return;
+      }
     }
   };
 
-  // Register instrumentations
   const instrumentations = [
     new HttpInstrumentation({
-      serverName: serviceName,
       // Ignore spans from static assets (metrics/health probes).
       ignoreIncomingRequestHook: (req) => req.url.startsWith('/metrics') || req.url.startsWith('/healthz'),
       applyCustomAttributesOnSpan,
       requestHook: (span, request) => {
-        // Enrich spans with additional HTTP request attributes
-        if (!request.headers) return;
+        // Outgoing ClientRequest exposes getHeaders(); incoming IncomingMessage has .headers.
+        const headers = request.getHeaders?.() ?? request.headers;
+        if (!headers) return;
 
-        const headers = request.headers;
+        const contentType = headers['content-type'];
+        const requestId = headers['x-request-id'];
+        const correlationId = headers['x-correlation-id'];
 
-        // Safe header extraction with case-insensitive fallback
-        const userAgent = headers['user-agent'] || headers['User-Agent'];
-        const contentType = headers['content-type'] || headers['Content-Type'];
-        const contentLength = headers['content-length'] || headers['Content-Length'];
-        const requestId = headers['x-request-id'] || headers['X-Request-ID'];
-        const correlationId = headers['x-correlation-id'] || headers['X-Correlation-ID'];
-
-        // Only set attributes if values exist
-        if (userAgent) span.setAttribute('http.user_agent', userAgent);
         if (contentType) span.setAttribute('http.request.content_type', contentType);
-
-        setIntAttribute(span, 'http.request.content_length', contentLength);
-
-        // Correlation headers for distributed tracing
+        setIntAttribute(span, 'http.request.content_length', headers['content-length']);
         if (requestId) span.setAttribute('http.request_id', requestId);
         if (correlationId) span.setAttribute('http.correlation_id', correlationId);
       },
       responseHook: (span, response) => {
-        // Add response attributes for better observability
         if (!response.headers) return;
 
         const headers = response.headers;
-        const contentType = headers['content-type'] || headers['Content-Type'];
-        const contentLength = headers['content-length'] || headers['Content-Length'];
-        const requestId = headers['x-request-id'] || headers['X-Request-ID'];
+        const contentType = headers['content-type'];
+        const requestId = headers['x-request-id'];
 
         if (contentType) span.setAttribute('http.response.content_type', contentType);
-
-        setIntAttribute(span, 'http.response.content_length', contentLength);
-
+        setIntAttribute(span, 'http.response.content_length', headers['content-length']);
         if (requestId) span.setAttribute('http.request_id', requestId);
       },
     }),
@@ -249,17 +234,12 @@ export function setupTracing(options = {}) {
     new IORedisInstrumentation({
       requireParentSpan: false,
       requestHook: (span, {cmdName, cmdArgs}) => {
-        // requestInfo is IORedisRequestHookInformation: { cmdName, cmdArgs }.
-        // Set peer.service for service graph visualization - CRITICAL for Tempo.
-        // The span is already created with SpanKind.CLIENT and net.peer.name is
-        // already set to the real host by the instrumentation, so we do not
-        // override those here.
+        // peer.service drives the Tempo service graph and is never emitted by
+        // the instrumentation, so it has to be set here. db.system.name,
+        // db.operation.name and server.* already come from the instrumentation.
         span.setAttribute('peer.service', 'redis');
-        span.setAttribute('db.system', 'redis');
 
-        // Add command details for better observability
         if (cmdName) {
-          span.setAttribute('db.operation', cmdName.toUpperCase());
           span.updateName(`redis.${cmdName.toUpperCase()}`);
         }
 
@@ -274,9 +254,8 @@ export function setupTracing(options = {}) {
         }
       },
       responseHook: (span, cmdName, cmdArgs, response) => {
-        // peer.service, db.system and db.operation are already set on this span
-        // by requestHook and persist for the span's lifetime, so they are not
-        // re-set here. Record only the response shape for observability.
+        // peer.service is already set by requestHook and persists for the
+        // span's lifetime, so only the response shape is recorded here.
         if (response !== undefined && response !== null) {
           span.setAttribute('db.response.type', typeof response);
           if (Array.isArray(response)) {
@@ -285,37 +264,22 @@ export function setupTracing(options = {}) {
         }
       },
       dbStatementSerializer: (cmdName, cmdArgs) => {
-        // Serialize command for better observability (limit arg length to avoid huge spans)
-        const args = cmdArgs.map(arg => {
-          const str = String(arg);
-          return str.length > 100 ? `${str.substring(0, 100)}...` : str;
-        });
+        const args = cmdArgs.map(arg => truncateArg(arg, 100));
         return `${cmdName} ${args.join(' ')}`;
       },
     }),
     new ElasticsearchInstrumentation(),
+    // Spread so the optional instrumentations are constructed only when enabled:
+    // FsInstrumentation patches fs on construction.
+    ...(enableFsInstrumentation ? [new FsInstrumentation()] : []),
+    // DnsInstrumentationConfig accepts only ignoreHostnames; it has no hooks.
+    ...(enableDnsInstrumentation ? [new DnsInstrumentation({ignoreHostnames: ['localhost', '127.0.0.1', '::1']})] : []),
   ];
 
-  if (enableFsInstrumentation) {
-    // Enable fs instrumentation if specified
-    // This instrumentation is useful for tracing file system operations.
-    instrumentations.push(new FsInstrumentation());
-  }
-
-  if (enableDnsInstrumentation) {
-    // Enable DNS instrumentation if specified
-    // This instrumentation is useful for tracing DNS operations.
-    // DnsInstrumentationConfig only supports ignoreHostnames; it has no
-    // request/response/error hooks.
-    instrumentations.push(new DnsInstrumentation({
-      ignoreHostnames: ['localhost', '127.0.0.1', '::1'],
-    }));
-  }
-
   // Register instrumentations
   registerInstrumentations({
-    tracerProvider: tracerProvider,
-    instrumentations: instrumentations,
+    tracerProvider,
+    instrumentations,
   });
 
   // Return the tracer for the service
@@ -336,12 +300,12 @@ export async function stopTracing() {
     try {
       await tracerProvider.shutdown();
       tracerProvider = null;
-      console.info('Tracing has been successfully shut down.');
+      diag.info('Tracing has been successfully shut down.');
     } catch (error) {
-      console.error('Error during tracing shutdown:', error);
+      diag.error('Error during tracing shutdown:', error);
     }
   } else {
-    console.warn('Tracer provider is not initialized.');
+    diag.warn('Tracer provider is not initialized.');
   }
 }
 

package/libs/index.test.mjs

@@ -1,48 +1,38 @@
 // index.test.mjs
 import { describe, it, beforeEach, afterEach } from 'node:test';
 import assert from 'node:assert';
+import { setupTracing, stopTracing, __resetTracingForTesting } from './index.mjs';
 
 describe('setupTracing', () => {
-  let stopTracing;
-
   // Clear environment and reset tracing state before each test
-  beforeEach(async () => {
+  beforeEach(() => {
     delete process.env.SERVICE_NAME;
     delete process.env.ENDPOINT;
     delete process.env.HOSTNAME;
     delete process.env.CONTAINER_NAME;
 
-    // Import and store stopTracing for cleanup
-    const tracing = await import('./index.mjs');
-    stopTracing = tracing.stopTracing;
-
     // Reset singleton for test isolation
-    tracing.__resetTracingForTesting();
+    __resetTracingForTesting();
   });
 
   // Clean up tracing after each test
   afterEach(async () => {
-    if (stopTracing) {
-      await stopTracing();
-    }
+    await stopTracing();
   });
 
-  it('should throw error when serviceName is not provided', async () => {
-    const { setupTracing } = await import('./index.mjs');
+  it('should throw error when serviceName is not provided', () => {
     assert.throws(() => {
       setupTracing({ url: 'http://localhost:4317' });
     }, /serviceName is required/);
   });
 
-  it('should throw error when url is not provided', async () => {
-    const { setupTracing } = await import('./index.mjs');
+  it('should throw error when url is not provided', () => {
     assert.throws(() => {
       setupTracing({ serviceName: 'test-service' });
     }, /url is required/);
   });
 
-  it('should create a tracer with required parameters', async () => {
-    const { setupTracing } = await import('./index.mjs');
+  it('should create a tracer with required parameters', () => {
     const tracer = setupTracing({
       serviceName: 'test-service',
       url: 'http://localhost:4317',
@@ -50,8 +40,7 @@ describe('setupTracing', () => {
     assert.ok(tracer, 'tracer should be defined');
   });
 
-  it('should accept hostname parameter', async () => {
-    const { setupTracing } = await import('./index.mjs');
+  it('should accept hostname parameter', () => {
     const tracer = setupTracing({
       serviceName: 'test-service',
       url: 'http://localhost:4317',
@@ -60,8 +49,7 @@ describe('setupTracing', () => {
     assert.ok(tracer, 'tracer should be defined');
   });
 
-  it('should accept optional instrumentations', async () => {
-    const { setupTracing } = await import('./index.mjs');
+  it('should accept optional instrumentations', () => {
     const tracer = setupTracing({
       serviceName: 'test-service',
       url: 'http://localhost:4317',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saidsef/tracing-node",
-  "version": "3.22.6",
+  "version": "4.0.0",
   "description": "tracing NodeJS - Wrapper for OpenTelemetry instrumentation packages",
   "main": "libs/index.mjs",
   "scripts": {
@@ -31,30 +31,30 @@
   "homepage": "https://github.com/saidsef/tracing-node#readme",
   "dependencies": {
     "@opentelemetry/api": "^1.9.0",
-    "@opentelemetry/exporter-trace-otlp-grpc": "^0.220.0",
-    "@opentelemetry/instrumentation": "^0.220.0",
-    "@opentelemetry/instrumentation-aws-sdk": "^0.75.0",
-    "@opentelemetry/instrumentation-connect": "^0.63.0",
+    "@opentelemetry/exporter-trace-otlp-grpc": "^0.221.0",
+    "@opentelemetry/instrumentation": "^0.221.0",
+    "@opentelemetry/instrumentation-aws-sdk": "^0.76.0",
+    "@opentelemetry/instrumentation-connect": "^0.64.0",
     "@opentelemetry/instrumentation-dns": "^0.64.0",
-    "@opentelemetry/instrumentation-express": "^0.67.0",
+    "@opentelemetry/instrumentation-express": "^0.69.0",
     "@opentelemetry/instrumentation-fs": "^0.40.0",
-    "@opentelemetry/instrumentation-http": "^0.220.0",
-    "@opentelemetry/instrumentation-ioredis": "^0.68.0",
-    "@opentelemetry/instrumentation-pino": "^0.66.0",
-    "@opentelemetry/resources": "^2.8.0",
-    "@opentelemetry/sdk-trace-base": "^2.8.0",
-    "@opentelemetry/sdk-trace-node": "^2.8.0",
-    "@opentelemetry/semantic-conventions": "^1.41.1",
+    "@opentelemetry/instrumentation-http": "^0.221.0",
+    "@opentelemetry/instrumentation-ioredis": "^0.69.0",
+    "@opentelemetry/instrumentation-pino": "^0.67.0",
+    "@opentelemetry/resources": "^2.10.0",
+    "@opentelemetry/sdk-trace-base": "^2.10.0",
+    "@opentelemetry/sdk-trace-node": "^2.10.0",
+    "@opentelemetry/semantic-conventions": "^1.43.0",
     "opentelemetry-instrumentation-elasticsearch": "^0.41.0"
   },
   "devDependencies": {
-    "eslint": "^10.5.0"
+    "eslint": "^10.8.0"
   },
   "overrides": {
     "protobufjs": "^7.5.3",
-    "@opentelemetry/core": "^2.8.0"
+    "@opentelemetry/core": "^2.10.0"
   },
   "allowScripts": {
-    "protobufjs@7.6.4": true
+    "protobufjs@7.6.5": true
   }
 }