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();

provider.addSpanProcessor(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.