Registry /
observability / opentelemetry-instrumentation-fetch-node
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
NodeFetchInstrumentation
✓ import { NodeFetchInstrumentation } from '@gasbuddy/opentelemetry-instrumentation-fetch-node';
✗ const { NodeFetchInstrumentation } = require('@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.
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);
});
Errors
Common errors & fixes
TypeError: fetch is not a function
The application is running on a Node.js version older than 18.0.0, where the global native `fetch` API is not available.
fixUpgrade 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.
The `NodeFetchInstrumentation` or the overall OpenTelemetry SDK was not correctly initialized and registered before `fetch` calls were made, preventing proper instrumentation.
fixEnsure `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.
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.
fixReview 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. Audit
Dependencies
@opentelemetry/apirequiredPeer dependency for OpenTelemetry API interfaces and types, required for all OpenTelemetry instrumentations.