# @netlify/opentelemetry-sdk-setup

> Opentelemetry SDK setup script

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

## Install

```sh
npm install @netlify/opentelemetry-sdk-setup
pnpm add @netlify/opentelemetry-sdk-setup
yarn add @netlify/opentelemetry-sdk-setup
bun add @netlify/opentelemetry-sdk-setup
```

Provides the command `otel-sdk-setup`.

## Health

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

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

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 4.0.0 |
| Published | 2026-09-15 |
| First published | 2023-11-21 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=22.12.0 |
| Dependencies | 10 |
| Unpacked size | 17 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 259 |
| Author | Netlify Inc. |
| Maintainers | netlify-bot, mikewen, youvalv, serhalp-netlify, mlgualtieri-gatsby |

## Links

- npm: https://www.npmjs.com/package/@netlify/opentelemetry-sdk-setup
- Repository: https://github.com/netlify/build
- Homepage: https://github.com/netlify/build#readme
- Issues: https://github.com/netlify/build/issues
- npm.io page: https://npm.io/package/@netlify/opentelemetry-sdk-setup

## Dependencies (10)

- [yargs-parser](https://npm.io/package/yargs-parser.md) ^21.1.1
- [read-package-up](https://npm.io/package/read-package-up.md) ^11.0.0
- [@opentelemetry/core](https://npm.io/package/@opentelemetry/core.md) ~2.8.0
- [@opentelemetry/resources](https://npm.io/package/@opentelemetry/resources.md) ~2.8.0
- [@netlify/opentelemetry-utils](https://npm.io/package/@netlify/opentelemetry-utils.md) ~4.0.0
- [@opentelemetry/sdk-trace-base](https://npm.io/package/@opentelemetry/sdk-trace-base.md) ~2.8.0
- [@opentelemetry/sdk-trace-node](https://npm.io/package/@opentelemetry/sdk-trace-node.md) ~2.8.0
- [@opentelemetry/semantic-conventions](https://npm.io/package/@opentelemetry/semantic-conventions.md) ~1.43.0
- [@opentelemetry/baggage-span-processor](https://npm.io/package/@opentelemetry/baggage-span-processor.md) ~0.5.0
- [@opentelemetry/exporter-trace-otlp-grpc](https://npm.io/package/@opentelemetry/exporter-trace-otlp-grpc.md) ~0.208.0

## Recent versions

- 4.0.0 (latest) — 2026-09-15
- 3.1.0 — 2026-07-17
- 3.0.1 — 2026-06-30
- 3.0.0 — 2026-06-16
- 2.0.3 — 2026-02-25
- 2.0.2 — 2025-05-29
- 2.0.1 — 2025-05-16
- 2.0.0 — 2025-05-14
- 1.2.2 — 2025-04-10
- 1.2.1 — 2025-03-20
- 1.2.0 — 2024-12-11
- 1.1.3 — 2024-05-27
- 1.1.2 — 2024-05-14
- 1.1.1 — 2024-04-23
- 1.1.0 — 2024-03-28
- … 6 more at https://npm.io/package/@netlify/opentelemetry-sdk-setup/versions

## README

# Opentelemetry SDK Setup

This package extracts the logic necessary to initialise the OpenTelemetry JS SDK using our tracing exporter. This not
only allows us to reuse the initialisation logic across different node process executions but also means **our modules
don't need to depend on any `@opentelemetry` module other than the `@opentelemetry/api`**.

## How to use it?

This module is designed to be preloaded via [--import](https://nodejs.org/docs/latest-v18.x/api/cli.html#--importmodule)
on any node execution. For example:

```
$> node --import=./lib/bin.js ../build/lib/core/bin.js --debug --tracing.httpProtocol=http --tracing.host=localhost --tracing.port=4317 --tracing.debug=true --tracing.preloadingEnabled=true .
```

On the script we're instrumenting we can just rely on `@opentelemetry/api` to create spans and interact with the SDK:

```ts
  import { trace } from '@opentelemetry/api'
  const tracer = trace.getTracer('secrets-scanning')

  const myInstrumentedFunction = async function() {
    await tracer.startActiveSpan(
      'scanning-files',
      { attributes: { myAttribute: 'foobar' } },
      async (span) => {
        doSomeWork()
        span.end()
      }
  }

```

## Sharing and receiving context from outside of the process

Our SDK initialisation is prepared to receive [trace](https://opentelemetry.io/docs/concepts/signals/traces/) and
[baggage](https://opentelemetry.io/docs/concepts/signals/baggage/) context from outside of the process. This allow us
to, for example, hook this node process execution to an ongoing trace which is already taking place or share the baggage
attributes for that execution with the spans created in this process. The list of tracing options show the options
available to the executable and what they mean.

Unfortunately, to our knowledge, the current `@opentelemetry` setup does not allow us to define an initial global
context that the root span can inherit from. As a consequence we had to get creative in order to pass the ingested
attributes to our main script execution, so that the root span can get the newly ingested attributes. We're relying on a
global property which can be accessed via `@netlify/opentelemetry-utils`. If your process receives any outside
attributes you can do the following:

```
$> node --import=./lib/bin.js my-instrumented-script --tracing.httpProtocol=http --tracing.host=localhost --tracing.port=4317 --tracing.debug=true --tracing.preloadingEnabled=true --tracing.baggageFilePath='./my-baggage-filepath' --tracing.traceId=<my-trace-id> --tracing.parentSpanId=<the-span-id-of-the-parent>
```

And on the instrumented script:

```ts
  import { trace } from '@opentelemetry/api'
  import { getGlobalContext } from '@netlify/opentelemetry-utils'
  const tracer = trace.getTracer('secrets-scanning')

  const myInstrumentedFunction = async function() {
    await tracer.startActiveSpan(
      'scanning-files',
      { attributes: { myAttribute: 'foobar' } },
      getGlobalContext(),
      async (span) => {
        doSomeWork()
        span.end()
      }
  }

```

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