@opentelemetry/instrumentation-fetch

What is @opentelemetry/instrumentation-fetch?

@opentelemetry/instrumentation-fetch is an npm package that provides automatic instrumentation for the Fetch API, allowing developers to collect telemetry data such as traces and metrics for HTTP requests made using the Fetch API. This is useful for monitoring and debugging web applications.

What are @opentelemetry/instrumentation-fetch's main functionalities?

Automatic Tracing

This feature allows you to automatically trace HTTP requests made using the Fetch API. The code sample demonstrates how to set up the FetchInstrumentation and enable it to start collecting trace data.

const { FetchInstrumentation } = require('@opentelemetry/instrumentation-fetch');
const { NodeTracerProvider } = require('@opentelemetry/node');
const { SimpleSpanProcessor } = require('@opentelemetry/tracing');
const { ConsoleSpanExporter } = require('@opentelemetry/tracing');

const provider = new NodeTracerProvider();
provider.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter()));
provider.register();

const fetchInstrumentation = new FetchInstrumentation();
fetchInstrumentation.enable();

fetch('https://jsonplaceholder.typicode.com/todos/1')
  .then(response => response.json())
  .then(json => console.log(json));

Custom Attributes

This feature allows you to add custom attributes to the spans created for Fetch API requests. The code sample shows how to set a custom attribute on each span.

const { FetchInstrumentation } = require('@opentelemetry/instrumentation-fetch');
const { NodeTracerProvider } = require('@opentelemetry/node');
const { SimpleSpanProcessor } = require('@opentelemetry/tracing');
const { ConsoleSpanExporter } = require('@opentelemetry/tracing');

const provider = new NodeTracerProvider();
provider.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter()));
provider.register();

const fetchInstrumentation = new FetchInstrumentation({
  applyCustomAttributesOnSpan: (span, request, response) => {
    span.setAttribute('custom-attribute', 'custom-value');
  }
});
fetchInstrumentation.enable();

fetch('https://jsonplaceholder.typicode.com/todos/1')
  .then(response => response.json())
  .then(json => console.log(json));

Error Handling

This feature allows you to handle errors in Fetch API requests and optionally ignore certain URLs or HTTP methods from being instrumented. The code sample demonstrates how to set up error handling and ignore specific URLs and methods.

const { FetchInstrumentation } = require('@opentelemetry/instrumentation-fetch');
const { NodeTracerProvider } = require('@opentelemetry/node');
const { SimpleSpanProcessor } = require('@opentelemetry/tracing');
const { ConsoleSpanExporter } = require('@opentelemetry/tracing');

const provider = new NodeTracerProvider();
provider.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter()));
provider.register();

const fetchInstrumentation = new FetchInstrumentation({
  ignoreUrls: [/example\.com/],
  ignoreMethods: ['POST']
});
fetchInstrumentation.enable();

fetch('https://jsonplaceholder.typicode.com/todos/1')
  .then(response => response.json())
  .then(json => console.log(json))
  .catch(error => console.error('Fetch error:', error));

Other packages similar to @opentelemetry/instrumentation-fetch

axios

Axios is a popular HTTP client for making requests from both the browser and Node.js. While it does not provide automatic instrumentation out of the box, it can be integrated with OpenTelemetry using custom instrumentation. Compared to @opentelemetry/instrumentation-fetch, Axios offers more features for making HTTP requests but requires additional setup for telemetry.

got

Got is another HTTP client for Node.js that is known for its simplicity and performance. Similar to Axios, it does not provide automatic instrumentation but can be integrated with OpenTelemetry through custom instrumentation. Got is often preferred for its lightweight and efficient design compared to @opentelemetry/instrumentation-fetch.

node-fetch

Node-fetch is a lightweight module that brings the Fetch API to Node.js. It is similar to the Fetch API in the browser and can be instrumented using @opentelemetry/instrumentation-fetch. However, node-fetch itself does not provide built-in telemetry capabilities, making it less feature-rich in terms of monitoring compared to @opentelemetry/instrumentation-fetch.

README

OpenTelemetry Fetch Instrumentation for web

This module provides auto instrumentation for web using fetch.

Installation

npm install --save @opentelemetry/instrumentation-fetch

Usage

'use strict';
import { ConsoleSpanExporter, SimpleSpanProcessor } from '@opentelemetry/sdk-trace-base';
import { WebTracerProvider } from '@opentelemetry/sdk-trace-web';
import { FetchInstrumentation } from '@opentelemetry/instrumentation-fetch';
import { ZoneContextManager } from '@opentelemetry/context-zone';
import { registerInstrumentations } from '@opentelemetry/instrumentation';

const provider = new WebTracerProvider();

provider.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter()));

provider.register({
  contextManager: new ZoneContextManager(),
});

registerInstrumentations({
  instrumentations: [new FetchInstrumentation()],
});

// or plugin can be also initialised separately and then set the tracer provider or meter provider
const fetchInstrumentation = new FetchInstrumentation();
const provider = new WebTracerProvider();
provider.register({
  contextManager: new ZoneContextManager(),
});
fetchInstrumentation.setTracerProvider(provider);

provider.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter()));


// and some test

fetch('http://localhost:8090/fetch.js');

Example Screenshots

See examples/tracer-web/fetch for a short example.

Fetch Instrumentation options

Fetch instrumentation plugin has few options available to choose from. You can set the following:

Options	Type	Description
applyCustomAttributesOnSpan	HttpCustomAttributeFunction	Function for adding custom attributes
ignoreNetworkEvents	boolean	Disable network events being added as span events (network events are added by default)

Useful links

• For more information on OpenTelemetry, visit: https://opentelemetry.io/
• For more about OpenTelemetry JavaScript: https://github.com/open-telemetry/opentelemetry-js
• For help or feedback on this project, join us in GitHub Discussions

License

Apache 2.0 - See LICENSE for more information.