@opentelemetry/instrumentation-undici

What is @opentelemetry/instrumentation-undici?

@opentelemetry/instrumentation-undici is an npm package that provides automatic instrumentation for the undici HTTP client library using OpenTelemetry. This allows developers to collect and export telemetry data such as traces and metrics from their undici-based HTTP requests, which can be used for monitoring and observability purposes.

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

Automatic Instrumentation

This feature allows you to automatically instrument undici HTTP client requests. By registering the UndiciInstrumentation with the OpenTelemetry tracer provider, all HTTP requests made using undici will be traced and the telemetry data will be collected.

const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
const { registerInstrumentations } = require('@opentelemetry/instrumentation');
const { UndiciInstrumentation } = require('@opentelemetry/instrumentation-undici');

const provider = new NodeTracerProvider();
provider.register();

registerInstrumentations({
  instrumentations: [
    new UndiciInstrumentation(),
  ],
  tracerProvider: provider,
});

Custom Attributes

This feature allows you to add custom attributes to the spans created for undici HTTP requests. By providing a requestHook function, you can modify the span and add any custom attributes you need for better observability.

const { UndiciInstrumentation } = require('@opentelemetry/instrumentation-undici');

const undiciInstrumentation = new UndiciInstrumentation({
  requestHook: (span, request) => {
    span.setAttribute('custom-attribute', 'value');
  },
});

Other packages similar to @opentelemetry/instrumentation-undici

@opentelemetry/instrumentation-http

@opentelemetry/instrumentation-http provides automatic instrumentation for the built-in Node.js HTTP and HTTPS modules. It is similar to @opentelemetry/instrumentation-undici but is used for the native HTTP clients in Node.js rather than the undici library.

@opentelemetry/instrumentation-fetch

@opentelemetry/instrumentation-fetch provides automatic instrumentation for the Fetch API in both browser and Node.js environments. It is similar to @opentelemetry/instrumentation-undici but is used for the Fetch API instead of the undici library.

README

OpenTelemetry Undici/fetch Instrumentation for Node.js

Note: This is an experimental package under active development. New releases may include breaking changes.

This module provides automatic instrumentation for undici and Node.js global fetch API. If you're looking the instrumentation for browser's fetch API it is located at https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/opentelemetry-instrumentation-fetch/

Installation

npm install --save @opentelemetry/instrumentation-undici

Supported Versions

• undici version >=5.12.0

Usage

OpenTelemetry Undici/fetch Instrumentation allows the user to automatically collect trace data and export them to their backend of choice, to give observability to distributed systems.

To load a specific instrumentation (Undici in this case), specify it in the Node Tracer's configuration.

const {
  UndiciInstrumentation,
} = require('@opentelemetry/instrumentation-undici');
const {
  ConsoleSpanExporter,
  NodeTracerProvider,
  SimpleSpanProcessor,
} = require('@opentelemetry/sdk-trace-node');
const { registerInstrumentations } = require('@opentelemetry/instrumentation');

const provider = new NodeTracerProvider({
  spanProcessors: [
    new SimpleSpanProcessor(new ConsoleSpanExporter()),
  ],
});

provider.register();

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

Undici/Fetch instrumentation Options

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

Options	Type	Description
ignoreRequestHook	IgnoreRequestFunction	Undici instrumentation will not trace all incoming requests that matched with custom function.
requestHook	RequestHookFunction	Function for adding custom attributes before request is handled.
responseHook	ResponseHookFunction	Function for adding custom attributes after the response headers are received.
startSpanHook	StartSpanHookFunction	Function for adding custom attributes before a span is started.
requireParentforSpans	Boolean	Require a parent span is present to create new span for outgoing requests.
headersToSpanAttributes	Object	List of case insensitive HTTP headers to convert to span attributes. Headers will be converted to span attributes in the form of http.{request|response}.header.header-name where the name is only lowercased, e.g. http.response.header.content-length

Observations

This instrumentation subscribes to certain diagnostics_channel to intercept the client requests and generate traces and metrics. In particular tracing spans are started when undici:request:create channel receives a message and ended when undici:request:trailers channel receive a message. This means the full response body has been received when the instrumentation ends the span.

Semantic Conventions

This package uses Semantic Conventions Version 1.24.0. As for now the Semantic Conventions are bundled in this package but eventually will be imported from @opentelemetry/semantic-conventions package when it is updated to latest version. Ref: opentelemetry-js/issues/4235

Attributes collected:

Attribute	Short Description
error.type	Describes a class of error the operation ended with.
http.request.method	HTTP request method.
http.request.method_original	Original HTTP method sent by the client in the request line.
http.response.status_code	HTTP response status code.
network.peer.address	Peer address of the network connection - IP address or Unix domain socket name.
network.peer.port	Peer port number of the network connection.
server.address	Server domain name, IP address or Unix domain socket name.
server.port	Server port number.
url.full	Absolute URL describing a network resource according to RFC3986.
url.path	The URI path component.
url.query	The URI query component.
url.scheme	HTTP request method.
user_agent.original	Value of the HTTP User-Agent header sent by the client.

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.