feat(otel): Implement distributed tracing

[logaretm]

This PR builds on #3195 by adding OTEL traces implementation by consuming the events emitted by the tracing channels, you can test it out with a simple tool I built.

I followed the implementation spirit of the OTEL metrics, so it gets enabled with a config and works in a very similar manner to metrics, I added the neccessary tests and documentations as well.

I tested a OTEL exporter app and it produced the spans you see above when running:

OpenTelemetry.init({
  tracing: {
    enabled: true,
    enableConnectionSpans: true,
  },
});

await tracer.startActiveSpan("api.handleRequest", async (outerSpan) => {
  await client.set("req:counter", "0");

  await tracer.startActiveSpan("api.authenticate", async (authSpan) => {
    await client.get("user:1:name"); // simulate auth lookup
    await client.set("session:abc", "user:1");
    await client.expire("session:abc", 3600);
    authSpan.end();
  });

  await tracer.startActiveSpan("api.fetchData", async (dataSpan) => {
    await client.incr("req:counter");

    await tracer.startActiveSpan("api.fetchData.cache", async (cacheSpan) => {
      await client.get("cache:products");
      // cache miss, set it
      await client.set("cache:products", JSON.stringify(["widget", "gadget"]));
      await client.expire("cache:products", 300);
      cacheSpan.end();
    });

    dataSpan.end();
  });

  outerSpan.end();
});

---

Note

Medium Risk
Adds new tracing instrumentation hooked into diagnostics_channel TracingChannels and relies on OpenTelemetry internal AsyncLocalStorage binding for context propagation, which could affect span correctness/performance in opt-in paths.

Overview
Adds OpenTelemetry tracing support alongside existing metrics by introducing OTelTracing and wiring it into OpenTelemetry.init({ tracing: ... }) with configurable command filtering, optional connection spans, and span error attribution.

Implements span creation for commands, batch operations (MULTI/PIPELINE) with parent/child relationships, and optional connect() spans, plus a new test suite validating span attributes and lifecycle.

Updates docs and examples to cover tracing (docs/otel-tracing.md, examples/otel-tracing.js) and refreshes package dev deps/lockfile to include tracing SDK/context packages.

^{Written by Cursor Bugbot for commit 4337ded. This will update automatically on new commits. Configure here.}

[Copilot]

Pull request overview

Adds OpenTelemetry distributed tracing support to the @redis/client package by subscribing to the existing Diagnostics Channel TracingChannel events (commands, batches, and optionally connect), alongside docs/tests/examples to validate and demonstrate span output.

Changes:

• Introduces OTelTracing implementation that creates OTel spans from node-redis tracing channels (command, batch, connect).
• Extends OTel config/types to include TracingConfig and adds new semantic attribute (db.operation.batch.size).
• Adds tracing documentation + runnable example, and a new test suite validating span creation, error recording, and parent/child relationships.

Reviewed changes

Copilot reviewed 9 out of 10 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
README.md	Updates OpenTelemetry section to include tracing and links to tracing docs/examples.
packages/client/package.json	Adds dev dependencies needed for tracing tests/examples (context manager + trace SDK base).
packages/client/lib/opentelemetry/types.ts	Adds TracingConfig and db.operation.batch.size attribute constant.
packages/client/lib/opentelemetry/tracing.ts	New tracing subscriber that creates spans from Diagnostics Channel TracingChannel.
packages/client/lib/opentelemetry/tracing.spec.ts	New tests covering command/batch/connect spans, filtering, and context propagation.
packages/client/lib/opentelemetry/index.ts	Wires tracing into OpenTelemetry.init when enabled and exports tracing types/class.
package-lock.json	Lockfile updates for added dependencies.
examples/README.md	Adds otel-tracing.js to examples list.
examples/otel-tracing.js	New runnable tracing example.
docs/otel-tracing.md	New tracing documentation and configuration reference.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

TracingConfig.enabled is not respected inside OTelTracing.init/constructor (spans will be subscribed/created even if someone calls OTelTracing.init({ ..., config: { enabled: false } })). Either enforce the flag in OTelTracing.init (return early when disabled) or remove enabled from TracingConfig to avoid a misleading configuration surface.

[Copilot]

tc.start.bindStore / unbindStore are invoked via any without checking they exist. On Node versions where TracingChannel exists but bindStore/unbindStore are unavailable or have different semantics, this will throw during initialization/teardown. Add a runtime guard (e.g., check for functions before calling) and fall back to the WeakMap approach when binding isn’t supported.

[Copilot]

In the bound-store path, error uses ctx.error! and asyncEnd/error leave the span attached to the context object. If ctx.error is unexpectedly missing this will throw, and retaining the ended span on ctx can keep references alive longer than needed. Prefer guarding when error is falsy and deleting ctx[SPAN_KEY] after ending to reduce retention.

Suggested change

	ctx[SPAN_KEY]?.end();
	},
	error: (ctx: WithSpan & { error?: Error }) => {
	const span = ctx[SPAN_KEY];
	if (span) {
	this.#endSpanWithError(span, ctx.error!);
	const span = ctx[SPAN_KEY];
	if (span) {
	span.end();
	delete ctx[SPAN_KEY];
	}
	},
	error: (ctx: WithSpan & { error?: Error }) => {
	const span = ctx[SPAN_KEY];
	if (span) {
	const error = ctx.error;
	if (error) {
	this.#endSpanWithError(span, error);
	} else {
	span.end();
	}
	delete ctx[SPAN_KEY];

[Copilot]

AsyncLocalStorageContextManager needs to be enabled (e.g. new AsyncLocalStorageContextManager().enable()) before setting it as the global context manager; otherwise context propagation (and therefore parent/child span relationships) may not work as documented.

Suggested change

	context.setGlobalContextManager(new AsyncLocalStorageContextManager());
	const contextManager = new AsyncLocalStorageContextManager().enable();
	context.setGlobalContextManager(contextManager);

[Copilot]

The AsyncLocalStorageContextManager snippet is missing .enable(). Without enabling, OpenTelemetry context propagation can be disabled, so Redis spans may not become children of active application spans as described later in this doc.

Suggested change

	context.setGlobalContextManager(new AsyncLocalStorageContextManager());
	context.setGlobalContextManager(
	new AsyncLocalStorageContextManager().enable()
	);

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

[cursor]

Span ended twice on error in ALS path

Medium Severity

In the ALS code path, when a traced operation rejects, Node.js TracingChannel.tracePromise publishes both the error and asyncEnd events. The error handler calls #endSpanWithError, which calls span.end(), and then the asyncEnd handler calls ctx[SPAN_KEY]?.end() again — double-ending the span. The WeakMap fallback path correctly avoids this by calling spans.delete(ctx) in the error handler, but the ALS path never clears ctx[SPAN_KEY]. This produces an OTel SDK warning ("Can not end a Span that has already been ended") for every errored Redis command.

Additional Locations (1)

• packages/client/lib/opentelemetry/tracing.ts#L290-L301

 

[cursor]

Field hasExcludeCommands is assigned but never read

Low Severity

hasExcludeCommands is declared in TracingOptions, computed and assigned in the constructor, but never read anywhere. The #isCommandExcluded method only uses hasIncludeCommands, includeCommands, and excludeCommands — the hasExcludeCommands shortcut is dead code.

Additional Locations (1)

• packages/client/lib/opentelemetry/tracing.ts#L75-L76

 

[PavelPashov]

@logaretm thank you, I'm gonna take a look