Sherlock SDK for Node.js

Add traces, metrics, and trace-linked exemplars to a Node.js service with one import.

@sherlock-labs/otel is the Sherlock distribution of OpenTelemetry JS. You add it to a Node.js service. It sends traces and metrics to Sherlock and puts a trace-linked exemplar on every histogram it manages, so a spike on a chart links to the request that caused it, and then to the logs of that request.

How the SDK works

• Register. A register entry patches libraries as they load: HTTP, Express, Koa, Postgres, Redis, pino, and more.
• Start. The pipelines start on their own from two environment variables, or from a start() call when the token arrives later. Everything exports over OTLP/HTTP with your bearer token.
• Link. Every histogram bucket keeps a few sampled measurements with the trace id and span id of the request. Log lines written inside a request get the same ids.

The SDK is in alpha. The package is not on a public registry yet. Today it arrives as a tarball that you install with a file: dependency. The API is the same on both paths.

What you get

Traces

Auto-instrumented spans for the libraries you use, plus custom spans for queue jobs and database calls that have no instrumentation.

Metrics

http.server.request.duration and http.client.request.duration for every request, Node.js runtime metrics, the app.http.server.* family from the Express or Koa adapter, and your own custom metrics.

Exemplars

A sampled measurement on every histogram bucket, with the trace id and span id of the request. Your own histograms get them too. The upstream SDK cannot emit exemplars at all (opentelemetry-js#5147).

Log correlation

The SDK does not ship logs. It stamps trace_id, span_id, and trace_flags on every pino log line inside a request, so one filter joins a chart, a trace, and the logs. A pino OTLP transport or a collector sends the lines to Sherlock. See Ship and correlate logs.

Requirements

Requirement	Value
Node.js	20 or later. 20.6 or later for ES modules.
Module systems	ES modules and CommonJS
TypeScript	Type definitions included
Frameworks with a metrics adapter	Express, Koa
Peer dependency	@opentelemetry/api 1.9.1

The package brings its own OpenTelemetry dependencies, pinned to exact versions. Do not add @opentelemetry/* packages yourself. Import the trace API from @sherlock-labs/otel.

Next steps

Quickstart

First data in ten minutes.

End-to-end steps

From credentials to a verified production deploy.

Custom metrics

Define your own instruments with exemplars.

Custom spans

Trace queue jobs and database calls.