OpenTelemetry Node.js Fetch Instrumentation

Common errors

• TypeError: fetch is not a function

  cause The application is running on a Node.js version older than 18.0.0, where the global native `fetch` API is not available.
  fix Upgrade your Node.js runtime to version 18.0.0 or higher to enable native `fetch` functionality.

• OpenTelemetry traces for native fetch calls are not appearing or seem incomplete.

  cause The `NodeFetchInstrumentation` or the overall OpenTelemetry SDK was not correctly initialized and registered before `fetch` calls were made, preventing proper instrumentation.
  fix Ensure `new NodeFetchInstrumentation()` is passed to `registerInstrumentations()` and that the `NodeSDK` is explicitly started *before* any native `fetch` requests are executed in your application's lifecycle.

• TypeScript compiler error: Property 'headers' does not exist on type 'Request' or 'Response' in `onRequest` callback.

  cause The type definitions being used for `Request` or `Response` within the `onRequest` callback might not align with the `undici`-based native `fetch` types or you're attempting to access headers improperly.
  fix Review the `Request` and `Response` interfaces provided by the DOM and Node's `undici` typings for correct property access. Use standard methods like `request.headers.get('header-name')` or `request.headers.raw()` for robust header manipulation.

Warnings

• gotcha This instrumentation specifically targets Node.js 18.0.0 or higher due to its reliance on native `fetch` (which uses `undici` internally) and Node's diagnostics channel features. It will not function on older Node.js versions.
  Fix: Ensure your Node.js runtime environment is version 18.0.0 or later to use this package.
• gotcha Node.js's native `fetch` is lazily loaded. This instrumentation performs an internal 'phony fetch' to an unparseable URL at initialization to ensure the diagnostics channel is registered and no `fetch` events are missed.
  Fix: No user action is required; this is an internal mechanism. Be aware of this if you observe an unexpected, failed network event on application startup, which is harmless.
• gotcha Unlike generic HTTP instrumentations (e.g., `@opentelemetry/instrumentation-http`), this package is exclusively for Node.js native `fetch`. If your application uses both native `fetch` and Node's traditional `http`/`https` modules, you will need to register both instrumentations to cover all traffic.
  Fix: Use `NodeFetchInstrumentation` for native `fetch` and `@opentelemetry/instrumentation-http` for other HTTP/HTTPS traffic if both types of requests are made in your application.
• gotcha Since `undici` (Node's internal fetch implementation) and consequently this instrumentation (from v1.2.0) support array-based header values, your `onRequest` or `onResponse` callbacks should be prepared to handle headers as potentially being string arrays, not just single strings.
  Fix: When accessing or manipulating headers (e.g., `request.headers.get('name')`), ensure your code accounts for the possibility of `string | string[]` return types or use `request.headers.raw()` for direct access to all header values as arrays.

Install

• npm install opentelemetry-instrumentation-fetch-node npm
• yarn add opentelemetry-instrumentation-fetch-node yarn
• pnpm add opentelemetry-instrumentation-fetch-node pnpm

Imports

• NodeFetchInstrumentation
  wrong:

  const { NodeFetchInstrumentation } = require('@gasbuddy/opentelemetry-instrumentation-fetch-node');

  correct:

  import { NodeFetchInstrumentation } from '@gasbuddy/opentelemetry-instrumentation-fetch-node';

  This is the primary class for initializing and configuring fetch instrumentation. While Node.js 18+ environments predominantly use ESM, CommonJS `require` is also supported.
• NodeFetchInstrumentationConfig

  import type { NodeFetchInstrumentationConfig } from '@gasbuddy/opentelemetry-instrumentation-fetch-node';

  This TypeScript type defines the configuration options available for `NodeFetchInstrumentation`, useful for detailed customization in TypeScript projects.
• registerInstrumentations

  import { registerInstrumentations } from '@opentelemetry/instrumentation';

  This is a generic OpenTelemetry utility from the core instrumentation package, essential for activating `NodeFetchInstrumentation` and any other instrumentations in your application.

Quickstart

Demonstrates how to set up and register `NodeFetchInstrumentation` with a basic OpenTelemetry Node SDK, make a traced native `fetch` request, and customize span attributes and request headers using `onRequest` and `applyCustomAttributesOnSpan` callbacks.

import { NodeSDK } from '@opentelemetry/sdk-node';
import { ConsoleSpanExporter } from '@opentelemetry/sdk-trace-node';
import { Resource } from '@opentelemetry/resources';
import { SemanticResourceAttributes } from '@opentelemetry/semantic-conventions';
import { registerInstrumentations } from '@opentelemetry/instrumentation';
import { NodeFetchInstrumentation } from '@gasbuddy/opentelemetry-instrumentation-fetch-node';

const sdk = new NodeSDK({
  resource: new Resource({
    [SemanticResourceAttributes.SERVICE_NAME]: 'my-fetch-service',
  }),
  traceExporter: new ConsoleSpanExporter(),
});

// Initialize and register the fetch instrumentation
registerInstrumentations([
  new NodeFetchInstrumentation({
    propagateContext: true, // Propagate trace context in outgoing headers
    ignoreMethods: ['OPTIONS'], // Do not instrument OPTIONS requests
    onRequest: (span, request) => {
      // Add custom attributes to the span before the request is made
      span.setAttribute('http.request.method', request.method);
      span.setAttribute('http.request.headers.host', request.headers.get('host') ?? '');
      // Example: Add a custom header to the outgoing request
      // request.headers.set('x-custom-trace-id', span.spanContext().traceId);
    },
    applyCustomAttributesOnSpan: (span, request, response) => {
        // Add custom attributes to the span after the response is received
        if (response) {
            span.setAttribute('http.response.status_code', response.status);
            span.setAttribute('http.response.status_text', response.statusText);
        }
    }
  }),
]);

sdk.start();

async function makeFetchRequest() {
  try {
    console.log('Making a fetch request...');
    const response = await fetch('https://httpbin.org/get', {
      method: 'GET',
      headers: {
        'Content-Type': 'application/json',
        'Accept': 'application/json'
      },
    });
    const data = await response.json();
    console.log('Fetch request completed (URL):', data.url);
  } catch (error) {
    console.error('Fetch request failed:', error);
  }
}

// Execute the request and then shut down the SDK gracefully
makeFetchRequest().finally(() => {
  console.log('Shutting down OpenTelemetry SDK...');
  // A small delay to ensure all spans are processed before shutdown
  setTimeout(() => sdk.shutdown().then(() => console.log('SDK shutdown complete.')), 500);
});