# @lwrjs/instrumentation

Latest version **0.24.1** (published 2026-09-15) · MIT license · 0 weekly downloads

## Install

```sh
npm install @lwrjs/instrumentation
pnpm add @lwrjs/instrumentation
yarn add @lwrjs/instrumentation
bun add @lwrjs/instrumentation
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.24.1 |
| Published | 2026-09-15 |
| First published | 2023-06-26 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=22.0.0 |
| Dependencies | 8 |
| Unpacked size | 62.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | nrkruk, lpomerleau, lwc-admin, kmbauer, kevinv11n |

## Links

- npm: https://www.npmjs.com/package/@lwrjs/instrumentation
- Repository: https://github.com/salesforce-experience-platform-emu/lwr
- Homepage: https://developer.salesforce.com/docs/platform/lwr/overview
- Issues: https://github.com/salesforce-experience-platform-emu/lwr/issues
- npm.io page: https://npm.io/package/@lwrjs/instrumentation

## Dependencies (8)

- [semver](https://npm.io/package/semver.md) >=7.6.3
- [@lwrjs/diagnostics](https://npm.io/package/@lwrjs/diagnostics.md) 0.24.1
- [@opentelemetry/api](https://npm.io/package/@opentelemetry/api.md) ^1.9.1
- [@lwrjs/shared-utils](https://npm.io/package/@lwrjs/shared-utils.md) 0.24.1
- [@opentelemetry/sdk-node](https://npm.io/package/@opentelemetry/sdk-node.md) ^0.221.0
- [@opentelemetry/resources](https://npm.io/package/@opentelemetry/resources.md) ^2.10.0
- [@opentelemetry/sdk-trace-node](https://npm.io/package/@opentelemetry/sdk-trace-node.md) ^2.10.0
- [@opentelemetry/semantic-conventions](https://npm.io/package/@opentelemetry/semantic-conventions.md) ^1.43.0

## Recent versions

- 0.24.1 (latest) — 2026-09-15
- 0.23.22 (summer26) — 2026-09-23
- 0.19.9 (winter26) — 2026-09-15
- 0.22.21 (vanilla) — 2026-09-03
- 0.22.7-alpha.6 (alpha) — 2026-03-02
- 0.21.3 (next) — 2026-01-14
- 0.17.9 (summer25) — 2025-05-20
- 0.15.10 (patch) — 2025-03-28
- 0.13.10 (winter25) — 2024-10-28
- 0.12.4 (summer24) — 2024-06-21
- 0.11.15 (spring24) — 2024-03-01
- 0.10.14 (winter24) — 2023-12-08
- 0.23.21 — 2026-09-15
- 0.23.20 — 2026-09-04
- 0.23.19 — 2026-09-02
- … 315 more at https://npm.io/package/@lwrjs/instrumentation/versions

## README

# Server-side tracing in LWR

-   [Server-side tracing in LWR](#server-side-tracing-in-lwr)
    -   [Overview](#overview)
    -   [Tracer interface](#tracer-interface)
        -   [Trace levels](#trace-levels)
        -   [Custom tracing example](#custom-tracing-example)
    -   [Distributed tracing](#distributed-tracing)

## Overview

LWR exposes tracing functionality to the application layer, enabling developers to create custom spans and integrate tracing directly into their application hooks (eg: route handlers, config hooks).

Application hooks can consume `@lwrjs/instrumentation` directly to trace with minimal configuration.

Custom spans will automatically be handled by the metric exporter provided by LWR. They will be written to a trace collector and logged to Splunk.

## Tracer interface

`@lwrjs/instrumentation` exposes a `Tracer` built on top of [OpenTelemetry](https://opentelemetry.io/) which defines and manages spans. These spans represent units of work and are tracked as part of a larger trace for the entire request lifecycle. See the LWR spans [here](./src/spans.ts).

```ts
interface TraceID {
    // tracing information for a span
    name: string;
    attributes?: Record<string, string | number | boolean>;
}

interface Tracer {
    trace<T>(id: TraceID, fn: () => T): T;
}
```

### Trace levels

`@lwrjs/instrumentation` differentiates between two levels of tracing:

-   _Default_: Captures essential spans that provide an overview of the request flow, suitable for tracking critical aspects of the request lifecycle. All custom spans are are set to the `default` level.
-   _Verbose_: Offers more granular trace data to identify potential performance issues or get deeper insights into specific parts of the request.

### Custom tracing example

The following example shows how a route handler can use the tracer to create a span for page metadata retrieval:

```ts
import { getTracer } from '@lwrjs/instrumentation';

export default async function (request: ViewRequest, context: HandlerContext): Promise<ViewResponse> {
    // Create a span for the metadata retrieval operation
    const metadata = getTracer().trace(
        {
            name: 'app.routeHandler.metadata',
            attributes: { url: request.url },
        },
        (span) => {
            // Perform the actual metadata retrieval
            const data = metadataService.getMetadata(request.url);
            // add more attributes to the span
            span.setAttributes({ size: data.size });
            return data;
        },
    );
    // Continue with other route handling logic...
}
```

Trace functions may be async:

```ts
import { getTracer } from '@lwrjs/instrumentation';

export default async function (request: ViewRequest, context: HandlerContext): Promise<ViewResponse> {
    const body = await getTracer().trace(
        {
            name: 'app.routeHandler.payload',
            attributes: { url: request.url },
        },
        async () => {
            const payload = await generatePayload(request.url);
            return payload.body;
        },
    );
}
```

## Distributed tracing

By default, LWR attaches [B3 headers for distributed tracing](https://github.com/openzipkin/b3-propagation) to base documents and any data requests executed during server-side rendering (SSR). To turn this feature off, set the `DISABLE_B3_TRACING` environment variable to "true".

---
_Source: https://npm.io/package/@lwrjs/instrumentation · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._