# @opentelemetry/instrumentation-undici
> OpenTelemetry instrumentation for `undici` http client and Node.js fetch()
Latest version **0.33.0** (published 2026-10-06) · Apache-2.0 license · 0 weekly downloads
## Install
```sh
npm install @opentelemetry/instrumentation-undici
pnpm add @opentelemetry/instrumentation-undici
yarn add @opentelemetry/instrumentation-undici
bun add @opentelemetry/instrumentation-undici
```
## Health
**Score 70/100 (B)** — status: active.
Positive: has types; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.
Warnings: low downloads; no esm support; pre 1.0.
## Facts
| | |
|---|---|
| Version | 0.33.0 |
| Published | 2026-10-06 |
| First published | 2024-04-04 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | ^18.19.0 \|\| >=20.6.0 |
| Dependencies | 3 |
| Unpacked size | 82.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 931 |
| Author | OpenTelemetry Authors |
| Maintainers | dyladan, pichlermarc, overbalance, npmjs-account, trentm, martinkuba |
| Keywords | opentelemetry, fetch, undici, nodejs, tracing, instrumentation |
## Links
- npm: https://www.npmjs.com/package/@opentelemetry/instrumentation-undici
- Repository: https://github.com/open-telemetry/opentelemetry-js-contrib
- Homepage: https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/packages/instrumentation-undici#readme
- Issues: https://github.com/open-telemetry/opentelemetry-js-contrib/issues
- npm.io page: https://npm.io/package/@opentelemetry/instrumentation-undici
## Dependencies (3)
- [@opentelemetry/core](https://npm.io/package/@opentelemetry/core.md) ^2.9.0
- [@opentelemetry/instrumentation](https://npm.io/package/@opentelemetry/instrumentation.md) ^0.223.0
- [@opentelemetry/semantic-conventions](https://npm.io/package/@opentelemetry/semantic-conventions.md) ^1.24.0
## Alternatives
- [gamedig](https://npm.io/package/gamedig.md) — 29.3K weekly downloads
- [join-monster](https://npm.io/package/join-monster.md) — 12.8K weekly downloads
- [masked](https://npm.io/package/masked.md) — 5.5K weekly downloads
- [@comunica/actor-query-process-explain-logical](https://npm.io/package/@comunica/actor-query-process-explain-logical.md) — 4.7K weekly downloads
- [@veracity/vui](https://npm.io/package/@veracity/vui.md) — 4.6K weekly downloads
## Recent versions
- 0.33.0 (latest) — 2026-10-06
- 0.32.0 — 2026-08-31
- 0.31.0 — 2026-07-23
- 0.30.0 — 2026-07-03
- 0.29.0 — 2026-06-11
- 0.28.0 — 2026-05-13
- 0.27.0 — 2026-05-06
- 0.26.0 — 2026-04-29
- 0.25.0 — 2026-04-17
- 0.24.0 — 2026-03-26
- 0.23.0 — 2026-03-04
- 0.22.0 — 2026-02-17
- 0.21.0 — 2026-01-22
- 0.20.0 — 2026-01-15
- 0.19.0 — 2025-11-06
- … 24 more at https://npm.io/package/@opentelemetry/instrumentation-undici/versions
## README
# OpenTelemetry Undici/fetch Instrumentation for Node.js
[![NPM Published Version][npm-img]][npm-url]
[![Apache License][license-image]][license-image]
**Note: This is an experimental package under active development. New releases may include breaking changes.**
This module provides automatic instrumentation for [`undici`](https://undici.nodejs.org/) and Node.js global [`fetch`](https://nodejs.org/docs/latest/api/globals.html#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/](https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/opentelemetry-instrumentation-fetch/)
## Installation
```bash
npm install --save @opentelemetry/instrumentation-undici
```
## Supported Versions
- [`undici`](https://www.npmjs.com/package/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 enable a specific instrumentation, pass it to `registerInstrumentations()`.
This is commonly done via `NodeSDK` for fully setting up all OpenTelemetry SDK components:
```js
const { NodeSDK } = require('@opentelemetry/sdk-node');
const { UndiciInstrumentation } = require('@opentelemetry/instrumentation-undici');
const sdk = new NodeSDK({
instrumentations: [
new UndiciInstrumentation(),
],
});
sdk.start();
process.once('beforeExit', async () => { await sdk.shutdown(); });
```
### Undici/Fetch instrumentation Options
Undici instrumentation has few options available to choose from. You can set the following:
| Options | Type | Description |
|----------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`ignoreRequestHook`](https://github.com/open-telemetry/opentelemetry-js-contrib/blob/main/packages/instrumentation-undici/src/types.ts#L73) | `IgnoreRequestFunction` | Undici instrumentation will not trace all incoming requests that matched with custom function. |
| [`requestHook`](https://github.com/open-telemetry/opentelemetry-js-contrib/blob/main/packages/instrumentation-undici/src/types.ts#L75) | `RequestHookFunction` | Function for adding custom attributes before request is handled. |
| [`responseHook`](https://github.com/open-telemetry/opentelemetry-js-contrib/blob/main/packages/instrumentation-undici/src/types.ts#L77) | `ResponseHookFunction` | Function for adding custom attributes after the response headers are received. |
| [`startSpanHook`](https://github.com/open-telemetry/opentelemetry-js-contrib/blob/main/packages/instrumentation-undici/src/types.ts#L79) | `StartSpanHookFunction` | Function for adding custom attributes before a span is started. |
| [`requireParentforSpans`](https://github.com/open-telemetry/opentelemetry-js-contrib/blob/main/packages/instrumentation-undici/src/types.ts#L81) | `Boolean` | Require a parent span is present to create new span for outgoing requests. |
| [`headersToSpanAttributes`](https://github.com/open-telemetry/opentelemetry-js-contrib/blob/main/packages/instrumentation-undici/src/types.ts#L83) | `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](https://nodejs.org/api/diagnostics_channel.html) to intercept the client requests
and generate traces and metrics. In particular tracing spans are started when [undici:request:create](https://undici.nodejs.org/#/docs/api/DiagnosticsChannel?id=undicirequestcreate)
channel receives a message and ended when [undici:request:trailers](https://undici.nodejs.org/#/docs/api/DiagnosticsChannel?id=undicirequesttrailers) 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](https://github.com/open-telemetry/semantic-conventions/tree/v1.24.0/docs/http). 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](https://github.com/open-telemetry/opentelemetry-js/issues/4235)
Attributes collected:
| Attribute | Short Description |
|--------------------------------|------------------------------------------------------------------------------------------------------------|
| `error.type` | An HTTP status code, as a string, for HTTP responses >=400; or [an `'UND_ERR_*'` code](https://undici.nodejs.org/api/Errors) if the request errored without a server response. Excluded if the request succeeded. |
| `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](https://tools.ietf.org/html/rfc7231#section-6). |
| `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. |
| `network.protocol.version` | The version of the network protocol being used. |
| `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](https://www.rfc-editor.org/rfc/rfc3986). |
| `url.path` | The [URI path](https://www.rfc-editor.org/rfc/rfc3986#section-3.3) component. |
| `url.query` | The [URI query](https://www.rfc-editor.org/rfc/rfc3986#section-3.4) 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:
- For more about OpenTelemetry JavaScript:
- For help or feedback on this project, join us in [GitHub Discussions][discussions-url]
## License
Apache 2.0 - See [LICENSE][license-url] for more information.
[discussions-url]: https://github.com/open-telemetry/opentelemetry-js/discussions
[license-url]: https://github.com/open-telemetry/opentelemetry-js-contrib/blob/main/LICENSE
[license-image]: https://img.shields.io/badge/license-Apache_2.0-green.svg?style=flat
[npm-url]: https://www.npmjs.com/package/@opentelemetry/instrumentation-undici
[npm-img]: https://badge.fury.io/js/%40opentelemetry%2Finstrumentation-undici.svg
---
_Source: https://npm.io/package/@opentelemetry/instrumentation-undici · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._