# @opentelemetry/instrumentation-document-load
> OpenTelemetry instrumentation for document load operations in browser applications
Latest version **0.67.0** (published 2026-08-31) · Apache-2.0 license · 0 weekly downloads
## Install
```sh
npm install @opentelemetry/instrumentation-document-load
pnpm add @opentelemetry/instrumentation-document-load
yarn add @opentelemetry/instrumentation-document-load
bun add @opentelemetry/instrumentation-document-load
```
## Health
**Score 70/100 (B)** — status: active.
Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score.
Warnings: low downloads; pre 1.0.
## Facts
| | |
|---|---|
| Version | 0.67.0 |
| Published | 2026-08-31 |
| First published | 2021-03-05 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | ^18.19.0 \|\| >=20.6.0 |
| Dependencies | 4 |
| Unpacked size | 147 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 927 |
| Author | OpenTelemetry Authors |
| Maintainers | dyladan, pichlermarc, overbalance, npmjs-account, trentm, martinkuba |
| Keywords | opentelemetry, document-load, web, tracing, profiling, plugin |
## Links
- npm: https://www.npmjs.com/package/@opentelemetry/instrumentation-document-load
- Repository: https://github.com/open-telemetry/opentelemetry-js-contrib
- Homepage: https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/packages/instrumentation-document-load#readme
- Issues: https://github.com/open-telemetry/opentelemetry-js-contrib/issues
- npm.io page: https://npm.io/package/@opentelemetry/instrumentation-document-load
## Dependencies (4)
- [@opentelemetry/core](https://npm.io/package/@opentelemetry/core.md) ^2.9.0
- [@opentelemetry/sdk-trace-web](https://npm.io/package/@opentelemetry/sdk-trace-web.md) ^2.9.0
- [@opentelemetry/instrumentation](https://npm.io/package/@opentelemetry/instrumentation.md) ^0.222.0
- [@opentelemetry/semantic-conventions](https://npm.io/package/@opentelemetry/semantic-conventions.md) ^1.23.0
## Alternatives
- [@opentelemetry/exporter-zipkin](https://npm.io/package/@opentelemetry/exporter-zipkin.md) — 14.8M weekly downloads
- [pusher-js](https://npm.io/package/pusher-js.md) — 2.0M weekly downloads
- [browserify](https://npm.io/package/browserify.md) — 1.7M weekly downloads
- [sqs-consumer](https://npm.io/package/sqs-consumer.md) — 1.7M weekly downloads
- [@sanity/eventsource](https://npm.io/package/@sanity/eventsource.md) — 930.8K weekly downloads
## Recent versions
- 0.67.0 (latest) — 2026-08-31
- 0.66.0 — 2026-07-23
- 0.65.0 — 2026-07-03
- 0.64.0 — 2026-06-11
- 0.63.0 — 2026-05-13
- 0.62.0 — 2026-05-06
- 0.61.0 — 2026-04-29
- 0.60.0 — 2026-04-17
- 0.59.0 — 2026-03-26
- 0.58.0 — 2026-03-04
- 0.57.0 — 2026-02-17
- 0.56.0 — 2026-01-22
- 0.55.0 — 2026-01-15
- 0.54.0 — 2025-11-06
- 0.53.0 — 2025-10-21
- … 49 more at https://npm.io/package/@opentelemetry/instrumentation-document-load/versions
## README
# OpenTelemetry Instrumentation Document Load
[![NPM Published Version][npm-img]][npm-url]
[![Apache License][license-image]][license-image]
This module provides automatic instrumentation for *document load* for Web applications, which may be loaded using the [`@opentelemetry/sdk-trace-web`](https://www.npmjs.com/package/@opentelemetry/sdk-trace-web) package.
If total installation size is not constrained, it is recommended to use the [`@opentelemetry/auto-instrumentations-web`](https://www.npmjs.com/package/@opentelemetry/auto-instrumentations-web) bundle with [`@opentelemetry/sdk-trace-web`](https://www.npmjs.com/package/@opentelemetry/sdk-trace-web) for the most seamless instrumentation experience.
Compatible with OpenTelemetry JS API and SDK `1.0+`.
## Installation
```bash
npm install --save @opentelemetry/instrumentation-document-load
```
## Usage
```js
import { ConsoleSpanExporter, SimpleSpanProcessor } from '@opentelemetry/sdk-trace';
import { WebTracerProvider } from '@opentelemetry/sdk-trace-web';
import { DocumentLoadInstrumentation } from '@opentelemetry/instrumentation-document-load';
import { XMLHttpRequestInstrumentation } from '@opentelemetry/instrumentation-xml-http-request';
import { registerInstrumentations } from '@opentelemetry/instrumentation';
import { B3Propagator } from '@opentelemetry/propagator-b3';
import { CompositePropagator, W3CTraceContextPropagator } from '@opentelemetry/core';
const provider = new WebTracerProvider({
spanProcessors: [
new SimpleSpanProcessor({ exporter: new ConsoleSpanExporter() }),
],
});
provider.register({
propagator: new CompositePropagator({
propagators: [
new B3Propagator(),
new W3CTraceContextPropagator(),
],
}),
});
registerInstrumentations({
instrumentations: [
new DocumentLoadInstrumentation(),
new XMLHttpRequestInstrumentation({
ignoreUrls: [/localhost/],
propagateTraceHeaderCorsUrls: [
'http://localhost:8090',
],
}),
],
});
```
## Optional: Send a trace parent from your server
This instrumentation supports connecting the server side spans for the initial HTML load with the client side span for the load from the browser's timing API. This works by having the server send its parent trace context (trace ID, span ID and trace sampling decision) to the client.
Because the browser does not send a trace context header for the initial page navigation, the server needs to fake a trace context header in a middleware and then send that trace context header back to the client as a meta tag *traceparent* . The *traceparent* meta tag should be in the [trace context W3C draft format][trace-context-url] . For example:
```html
...
...
```
## Optional : Add custom attributes to spans if needed
If it is needed to add custom attributes to the document load span,and/or document fetch span and/or resource fetch spans, respective functions to do so needs to be provided
as a config to the DocumentLoad Instrumentation as shown below. The attributes will be added to the respective spans
before the individual are spans are ended. If the function throws an error , no attributes will be added to the span and
the rest of the process continues.
```js
const addCustomAttributesToSpan = (span: Span) => {
span.setAttribute('','');
}
const addCustomAttributesToResourceFetchSpan = (span: Span, resource: PerformanceResourceTiming) => {
span.setAttribute('','');
span.setAttribute('resource.tcp.duration_ms', resource.connectEnd - resource.connectStart);
}
registerInstrumentations({
instrumentations: [
new DocumentLoadInstrumentation({
applyCustomAttributesOnSpan: {
documentLoad: addCustomAttributesToSpan,
resourceFetch: addCustomAttributesToResourceFetchSpan
}
})
]
})
```
See [examples/tracer-web](https://github.com/open-telemetry/opentelemetry-js/tree/main/examples/tracer-web) for a short example.
## Document Load Instrumentation Options
The document load instrumentation plugin has few options available to choose from. You can set the following:
| Options | Type | Description |
|---------------------------------------------|----------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `applyCustomAttributesOnSpan.documentLoad` | `DocumentLoadCustomAttributeFunction` | Function for adding custom attributes to `documentLoad` spans. |
| `applyCustomAttributesOnSpan.documentFetch` | `DocumentLoadCustomAttributeFunction` | Function for adding custom attributes to `documentFetch` spans. |
| `applyCustomAttributesOnSpan.resourceFetch` | `ResourceFetchCustomAttributeFunction` | Function for adding custom attributes to `resourceFetch` spans |
| `ignoreNetworkEvents` | `boolean` | Ignore adding [network events as span events](https://github.com/open-telemetry/opentelemetry-js/blob/e49c4c7f42c6c444da3f802687cfa4f2d6983f46/packages/opentelemetry-sdk-trace-web/src/enums/PerformanceTimingNames.ts#L17) for document fetch and resource fetch spans. |
| `ignorePerformancePaintEvents` | `boolean` | Ignore adding performance resource paint span events to document load spans. |
## Semantic Conventions
This instrumentation creates spans that include some HTTP-related data as span attributes (URL, User-Agent header).
The `instrumentation-document-load` versions 0.65.0 and later emit the stable v1.23.0+ semantic conventions.
| v1.23.0 semconv | Notes |
|-----------------------|-------------------------------------------------------------------------------------------------------------------------|
| `url.full` | Full HTTP request URL |
| `user_agent.original` | Value of the [HTTP User-Agent](https://www.rfc-editor.org/rfc/rfc9110.html#field.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-document-load
[npm-img]: https://badge.fury.io/js/%40opentelemetry%2Finstrumentation-document-load.svg
[trace-context-url]: https://www.w3.org/TR/trace-context
---
_Source: https://npm.io/package/@opentelemetry/instrumentation-document-load · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._