# @prairielearn/opentelemetry

Latest version **4.0.13** (published 2026-08-11) · 0 weekly downloads

## Install

```sh
npm install @prairielearn/opentelemetry
pnpm add @prairielearn/opentelemetry
yarn add @prairielearn/opentelemetry
bun add @prairielearn/opentelemetry
```

## Health

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

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

Warnings: low downloads; no types.

## Facts

| | |
|---|---|
| Version | 4.0.13 |
| Published | 2026-08-11 |
| First published | 2022-04-12 |
| Weekly downloads | 0 |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Node | >=24.0.0 |
| Dependencies | 21 |
| Unpacked size | 188.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 500 |
| Maintainers | nwalters512, mwest1066 |

## Links

- npm: https://www.npmjs.com/package/@prairielearn/opentelemetry
- Repository: https://github.com/PrairieLearn/PrairieLearn
- npm.io page: https://npm.io/package/@prairielearn/opentelemetry

## Dependencies (21)

- [@grpc/grpc-js](https://npm.io/package/@grpc/grpc-js.md) ^1.14.4
- [@opentelemetry/api](https://npm.io/package/@opentelemetry/api.md) ^1.9.1
- [@opentelemetry/core](https://npm.io/package/@opentelemetry/core.md) ^2.10.0
- [@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-metrics](https://npm.io/package/@opentelemetry/sdk-metrics.md) ^2.10.0
- [@opentelemetry/sdk-trace-base](https://npm.io/package/@opentelemetry/sdk-trace-base.md) ^2.10.0
- [@opentelemetry/sdk-trace-node](https://npm.io/package/@opentelemetry/sdk-trace-node.md) ^2.10.0
- [@opentelemetry/instrumentation-pg](https://npm.io/package/@opentelemetry/instrumentation-pg.md) ^0.73.0
- [@opentelemetry/instrumentation-dns](https://npm.io/package/@opentelemetry/instrumentation-dns.md) ^0.64.0
- [@opentelemetry/instrumentation-http](https://npm.io/package/@opentelemetry/instrumentation-http.md) ^0.221.0
- [@opentelemetry/semantic-conventions](https://npm.io/package/@opentelemetry/semantic-conventions.md) ^1.43.0
- [@opentelemetry/instrumentation-redis](https://npm.io/package/@opentelemetry/instrumentation-redis.md) ^0.69.0
- [@opentelemetry/resource-detector-aws](https://npm.io/package/@opentelemetry/resource-detector-aws.md) ^2.21.0
- [@opentelemetry/instrumentation-aws-sdk](https://npm.io/package/@opentelemetry/instrumentation-aws-sdk.md) ^0.76.0
- [@opentelemetry/instrumentation-connect](https://npm.io/package/@opentelemetry/instrumentation-connect.md) ^0.64.0
- [@opentelemetry/instrumentation-express](https://npm.io/package/@opentelemetry/instrumentation-express.md) ^0.69.0
- [@opentelemetry/instrumentation-ioredis](https://npm.io/package/@opentelemetry/instrumentation-ioredis.md) ^0.69.0
- [@opentelemetry/exporter-trace-otlp-grpc](https://npm.io/package/@opentelemetry/exporter-trace-otlp-grpc.md) ^0.221.0
- [@opentelemetry/exporter-trace-otlp-http](https://npm.io/package/@opentelemetry/exporter-trace-otlp-http.md) ^0.221.0
- [@opentelemetry/exporter-metrics-otlp-grpc](https://npm.io/package/@opentelemetry/exporter-metrics-otlp-grpc.md) ^0.221.0

## Recent versions

- 4.0.13 (latest) — 2026-08-11
- 4.0.12 — 2026-07-10
- 4.0.11 — 2026-06-16
- 4.0.10 — 2026-06-01
- 4.0.9 — 2026-05-22
- 4.0.8 — 2026-05-16
- 4.0.7 — 2026-05-07
- 4.0.6 — 2026-04-30
- 4.0.5 — 2026-04-29
- 4.0.4 — 2026-03-06
- 4.0.3 — 2026-03-04
- 4.0.2 — 2026-02-23
- 4.0.1 — 2026-01-31
- 4.0.0 — 2026-01-16
- 3.1.2 — 2026-01-15
- … 62 more at https://npm.io/package/@prairielearn/opentelemetry/versions

## README

# `@prairielearn/opentelemetry`

Opinionated wrapper around various `@opentelemetry/*` packages.

## Usage

You should require this package as early as possible during application initialization and call `init()` once the application configuration is available.

```ts
import { init } from '@prairielearn/opentelemetry';

// ...

await init({
  openTelemetryEnabled: true,
  openTelemetryExporter: 'honeycomb',
  openTelemetryMetricExporter: 'honeycomb',
  openTelemetryMetricExportIntervalMillis: 30_000,
  openTelemetrySamplerType: 'always-on',
  openTelemetrySampleRate: 0.1,
  honeycombApiKey: 'KEY',
  honeycombDataset: 'DATASET',
});
```

This will automatically instrument a variety of commonly-used Node packages.

When using code from the OpenTelemetry libraries, make sure you import it via `@prairielearn/opentelemetry` instead of installing it separately to ensure that there is only one version of each OpenTelemetry package in use at once. If the desired functionality is not yet exported, please add it!

## Traces

To easily instrument individual pieces of functionality, you can use the `instrumented()` helper function:

```ts
import { instrumented } from '@prairielearn/opentelemetry';

async function doThing() {
  return instrumented('span.name', async (span) => {
    span.setAttribute('attribute.name', 'value');
    await doThing();
  });
}
```

This will automatically set the span status and record any exceptions that occur.

If you have a more complex use case, you can manually instrument code with the `trace` export:

```ts
import { trace, SpanStatusCode } from '@prairielearn/opentelemetry';

const tracer = trace.getTracer('default');
await tracer.startActiveSpan('span.name', async (span) => {
  try {
    await doWork();
    span.setStatus({ status: SpanStatusCode.OK });
  } catch (err) {
    span.recordException(err);
    span.setStatus({
      status: SpanStatusCode.ERROR,
      message: err.message,
    });
    throw err;
  }
});
```

## Metrics

You can manually create counters and other metrics with the following functions

- `getHistogram`
- `getCounter`
- `getUpDownCounter`
- `getObservableCounter`
- `getObservableUpDownCounter`
- `getObservableGauge`

```ts
import { metrics, getCounter, ValueType } from '@prairielearn/opentelemetry';

function handleRequest(req, res) {
  const meter = metrics.getMeter('meter-name');
  const requestCounter = getCounter(meter, 'request.count', {
    valueType: ValueType.INT,
  });
  requestCounter.add(1);
}
```

You can also use the `instrumentedWithMetrics` helper to automatically capture a duration histogram and error count:

```ts
import { metrics, instrumentedWithMetrics } from '@prairielearn/opentelemetry';

const meter = metrics.getMeter('meter-name');
await instrumentedWithMetrics(meter, 'operation.name', async () => {
  const random = Math.random() * 1000;
  await new Promise((resolve) => setTimeout(resolve, random));
  if (random > 900) {
    throw new Error('Failed!');
  }
});
```

To capture statistics about a constantly changing value (for instance, the size of a database connection pool), you can use `createObservableValueGauges`. This will "observe" your chosen value on a regular interval and collect the min/max/average of that value for each metrics collection interval.

```ts
import { metrics, createObservableValueGauges } from '@prairielearn/opentelemetry';

const meter = metrics.getMeter('meter-name');
createObservableValueGauges(
  meter,
  'db.pool.size',
  {
    // The interval that your value will be observed, in milliseconds.
    interval: 1000,
  },
  () => pool.size,
);
```

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