@opentelemetry/instrumentation-undici
TypeScript icon, indicating that this package has built-in type declarations

0.7.1 • Public • Published

OpenTelemetry Undici/fetch Instrumentation for Node.js

NPM Published Version Apache License

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

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

License

Apache 2.0 - See LICENSE for more information.

Package Sidebar

Install

npm i @opentelemetry/instrumentation-undici

Weekly Downloads

989,083

Version

0.7.1

License

Apache-2.0

Unpacked Size

109 kB

Total Files

21

Last publish

Collaborators

  • pichlermarc
  • bogdandrutu
  • dyladan