@saidsef/tracing-node 4.0.0 → 4.1.1

package/README.md

@@ -15,6 +15,7 @@ Effortlessly supercharge your applications with world-class distributed tracing!
 | Feature | Description |
 |---------|-------------|
 | HTTP/HTTPS instrumentation | Automatic service detection |
+| fetch/undici instrumentation | Outgoing `globalThis.fetch` calls |
 | Express.js support | Framework instrumentation |
 | Elasticsearch client | Database instrumentation |
 | IORedis client | Cache instrumentation |
@@ -30,38 +31,27 @@ Effortlessly supercharge your applications with world-class distributed tracing!
 - ...
 - Profit?
 
-## Instalation
+## Where the traces go
 
-```
-npm install @saidsef/tracing-node --save
-```
+`setupTracing` exports OTLP over gRPC, so any OpenTelemetry-compatible collector or backend will take it - point `url` at yours.
+
+If you do not have one yet, [grafana-loki-on-k8s](https://github.com/saidsef/grafana-loki-on-k8s) is a companion project that deploys the full LGTM+ stack - Grafana, Prometheus, Mimir, Loki, Tempo, Pyroscope, Alloy and Beyla - to Kubernetes with `kubectl apply -k ./deployment`, broken into small composable manifests rather than a single opaque chart. Send traces to its Alloy OTLP receiver and they land in Tempo, with the metrics-generator turning them into RED and service-graph metrics in Mimir:
 
-## Upgrading to 4.0.0
+```javascript
+setupTracing({serviceName: 'my-service', url: 'http://alloy:4317'});
+```
 
-**Breaking change: spans now carry the stable OpenTelemetry semantic conventions.**
+The W3C Trace Context propagation this library registers is what lets Tempo pair a caller's client span with the callee's server span, which is what a service graph is built from.
 
-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.
+## Instalation
 
-| 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 |
+```
+npm install @saidsef/tracing-node --save
+```
 
-Server-side HTTP metrics also move from `http.server.duration` (milliseconds) to `http.server.request.duration` (seconds), and the client equivalents likewise.
+## Upgrading
 
-`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.
+Breaking changes and the attribute renames they bring are recorded in the [release notes](https://github.com/saidsef/tracing-node/releases) for the version concerned.
 
 ## Usage
 
@@ -92,7 +82,7 @@ setupTracing({hostname: 'hostname', serviceName: 'service_name', url: 'endpoint'
 
 ## Source
 
-Our latest and greatest source of `tracing-node` can be found on [GitHub](https://github.com/saidsef/tracing-nodec/fork). Fork us!
+Our latest and greatest source of `tracing-node` can be found on [GitHub](https://github.com/saidsef/tracing-node/fork). Fork us!
 
 ## Contributing
 

package/libs/index.mjs

@@ -25,6 +25,7 @@ import {ExpressInstrumentation} from '@opentelemetry/instrumentation-express';
 import {NodeTracerProvider} from '@opentelemetry/sdk-trace-node';
 import {OTLPTraceExporter} from '@opentelemetry/exporter-trace-otlp-grpc';
 import {PinoInstrumentation} from '@opentelemetry/instrumentation-pino';
+import {UndiciInstrumentation} from '@opentelemetry/instrumentation-undici';
 import {IORedisInstrumentation} from '@opentelemetry/instrumentation-ioredis';
 import {registerInstrumentations} from '@opentelemetry/instrumentation';
 import {FsInstrumentation} from '@opentelemetry/instrumentation-fs';
@@ -50,6 +51,21 @@ const truncateArg = (value, limit) => {
   return str.length > limit ? `${str.substring(0, limit)}...` : str;
 };
 
+// Tempo names a service-graph node from peer.service, which no instrumentation
+// emits, so both the http and undici hooks below derive it from the remote host.
+const PEER_SERVICES = ['elasticsearch', 'redis'];
+
+const setPeerService = (span, host) => {
+  if (!host) return;
+  for (const service of PEER_SERVICES) {
+    if (host.includes(service)) {
+      span.setAttribute('peer.service', service);
+      span.setAttribute('db.system.name', service);
+      return;
+    }
+  }
+};
+
 let tracerProvider = null; // Declare provider in module scope for access in stopTracing
 
 /**
@@ -134,18 +150,7 @@ export function setupTracing(options = {}) {
 
   // 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 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;
-      }
-    }
-  };
+  const applyCustomAttributesOnSpan = (span, request) => setPeerService(span, request?.host);
 
   const instrumentations = [
     new HttpInstrumentation({
@@ -178,6 +183,14 @@ export function setupTracing(options = {}) {
         if (requestId) span.setAttribute('http.request_id', requestId);
       },
     }),
+    // globalThis.fetch runs on undici, which never touches the http/https
+    // modules HttpInstrumentation patches. Without this, fetch calls produce no
+    // client span and inject no traceparent, so the callee starts a new trace
+    // and the two services can never be paired into a service-graph edge.
+    new UndiciInstrumentation({
+      // UndiciRequest exposes origin, not the .host the http hook reads.
+      requestHook: (span, request) => setPeerService(span, request?.origin),
+    }),
     new ExpressInstrumentation({
       requestHook: (span, info) => {
         // info is ExpressRequestInfo: { request, route, layerType }

package/libs/index.test.mjs

@@ -49,6 +49,20 @@ describe('setupTracing', () => {
     assert.ok(tracer, 'tracer should be defined');
   });
 
+  // globalThis.fetch runs on undici, so it is invisible to HttpInstrumentation.
+  // Registering it must not disturb setup, and the patch has to land on the
+  // global fetch itself - otherwise outgoing calls carry no traceparent.
+  it('should instrument global fetch', () => {
+    const before = globalThis.fetch;
+    const tracer = setupTracing({
+      serviceName: 'test-service',
+      url: 'http://localhost:4317',
+    });
+    assert.ok(tracer, 'tracer should be defined');
+    assert.strictEqual(typeof globalThis.fetch, 'function', 'global fetch should still be callable');
+    assert.ok(before, 'global fetch should exist on a supported runtime');
+  });
+
   it('should accept optional instrumentations', () => {
     const tracer = setupTracing({
       serviceName: 'test-service',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saidsef/tracing-node",
-  "version": "4.0.0",
+  "version": "4.1.1",
   "description": "tracing NodeJS - Wrapper for OpenTelemetry instrumentation packages",
   "main": "libs/index.mjs",
   "scripts": {
@@ -23,7 +23,7 @@
   "author": "Said Sef <saidsef@gmail.com>",
   "license": "Apache-2.0",
   "engines": {
-    "node": ">= 20"
+    "node": ">= 20.6.0"
   },
   "bugs": {
     "url": "https://github.com/saidsef/tracing-node/issues"
@@ -41,6 +41,7 @@
     "@opentelemetry/instrumentation-http": "^0.221.0",
     "@opentelemetry/instrumentation-ioredis": "^0.69.0",
     "@opentelemetry/instrumentation-pino": "^0.67.0",
+    "@opentelemetry/instrumentation-undici": "^0.31.0",
     "@opentelemetry/resources": "^2.10.0",
     "@opentelemetry/sdk-trace-base": "^2.10.0",
     "@opentelemetry/sdk-trace-node": "^2.10.0",