add OpenTelemetry metrics instrumentation by PavelPashov · Pull Request #3110 · redis/node-redis

PavelPashov · 2025-10-24T14:15:00Z

Description

TODO

Add docs
Add examples

Checklist

Does npm test pass with this change (including linting)?
Is the new or changed code fully tested?
Is a documentation update included (if this change modifies existing APIs, or introduces new ones)?

Note

Medium Risk
Touches core request/connection paths (RedisClient, RedisSocket, queues, cluster redirection) to emit metrics and maintain per-client identity/registry, so mistakes could add overhead or skew counts. Functional behavior should be unchanged, but instrumentation around errors/closures and cache invalidation needs careful review.

Overview
Adds first-class OpenTelemetry metrics support via a new OpenTelemetry.init() entrypoint and an internal metrics/registry layer that can be enabled before client creation.

Instruments core client operations to emit metrics for command durations (including MULTI/PIPELINE batches), connection lifecycle (create time, active count, close reasons, relaxed timeouts, handoff), resiliency/errors (including cluster redirections and maintenance notifications), pub/sub message in/out, stream lag from XREAD/XREADGROUP, and client-side caching hits/misses/evictions.

Introduces stable per-client identity (_clientId) and a ClientRegistry so observable gauges and metric attribution can track standalone clients, pools, and cluster nodes; updates pool/cluster/node creation to set roles/parent IDs and unregisters clients on close/destroy/quit. Documentation and an otel-metrics.js example are added, along with new OpenTelemetry dev dependencies and extensive tests for the metrics implementation.

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

jit-ci

❌ The following Jit checks failed to run:

license-compliance-checker
secret-detection-trufflehog
software-component-analysis-js
static-code-analysis-semgrep-pro

#jit_bypass_commit in this PR to bypass, Jit Admin privileges required.

More info in the Jit platform.

elimelt · 2025-12-08T21:20:11Z

This is an exciting feature, I hope it makes it to main!

jit-ci · 2026-01-19T08:28:50Z

❌ Security scan failed

Security scan failed: Branch feat/add-opentelemetry-metrics does not exist in the remote repository

💡 Need to bypass this check? Comment @sera bypass to override.

jit-ci · 2026-01-19T08:35:55Z

❌ Security scan failed

Security scan failed: Branch feat/add-opentelemetry-metrics does not exist in the remote repository

💡 Need to bypass this check? Comment @sera bypass to override.

jit-ci · 2026-01-19T09:28:19Z

❌ Security scan failed

Security scan failed: Branch feat/add-opentelemetry-metrics does not exist in the remote repository

💡 Need to bypass this check? Comment @sera bypass to override.

…overhead

…ne attributes

…onfig

…ource attrs

packages/client/lib/client/cache.ts

packages/client/lib/client/index.ts

packages/client/lib/opentelemetry/metrics.ts

packages/client/lib/opentelemetry/noop-metrics.ts

packages/client/lib/client/index.ts

packages/client/lib/client/cache.ts

packages/client/lib/cluster/index.ts

packages/client/lib/client/socket.ts

PavelPashov · 2026-02-27T14:58:56Z

packages/client/lib/RESP/types.ts

  TRANSFORM_LEGACY_REPLY?: boolean;
  transformReply: TransformReply | Record<RespVersions, TransformReply>;
  unstableResp3?: boolean;
+  onSuccess?: (args: ReadonlyArray<RedisArgument>, reply: unknown, clientId: string) => void;


@nkaradzhov we might want to rename onSuccess to something more metrics/otel related

PavelPashov · 2026-02-27T15:00:38Z

packages/client/lib/client/index.ts

+      if (command.onSuccess) {
+        command.onSuccess(parser.redisArgs, finalReply, this._self._clientId);


@nkaradzhov there might be a better way to record specific command related metrics that require the server response

nkaradzhov · 2026-03-04T11:32:33Z

packages/client/lib/opentelemetry/metrics.ts

+    // Build the appropriate function based on options
+    if (options.hasIncludeCommands || options.hasExcludeCommands) {
+      // Version with filtering
+      this.createRecordOperationDuration = this.#createWithFiltering.bind(this);
+    } else {
+      this.createRecordOperationDuration =
+        this.#createWithoutFiltering.bind(this);
+    }
+  }


why have two fns?

@nkaradzhov to make sure we don't do unnecessary checks after initiating the metrics singleton if the user hasn't provided any included or excluded commands

packages/client/lib/opentelemetry/metrics.ts

… in command and CSC metrics

packages/client/lib/client/cache.ts

packages/client/lib/opentelemetry/metrics.ts

packages/client/lib/client/socket.ts

PavelPashov · 2026-03-23T14:51:36Z

@nkaradzhov & @vladvildanov

Created a separated PR for conversion of ObservableGauges to up UpDownCounters.

After the current PR is released I'll need to create 3 issues for:

redis.client.csc.network_saved - disabled, due to incorrect values computed from inside the metrics class
db.client.connection.count - state is always used, this should be renamed and converted to ObservableGauge in order to be more accurate.
db.client.connection.pending_requests - disabled, should be renamed and remain a ObservableGauge, as converting it to UpDownCounter will likely result in a performance hit when enabled.

packages/client/lib/client/index.ts

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

packages/client/lib/client/index.ts

No subscriber existed for this event. The original redis#3110 code only recorded at wait end, not start. Remove the speculative event. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

PavelPashov force-pushed the feat/add-opentelemetry-metrics branch 4 times, most recently from a11117e to 5fb1791 Compare October 31, 2025 11:39

PavelPashov force-pushed the feat/add-opentelemetry-metrics branch 2 times, most recently from 1be4565 to 03db1a2 Compare November 5, 2025 11:03

jit-ci bot reviewed Nov 5, 2025

View reviewed changes

PavelPashov force-pushed the feat/add-opentelemetry-metrics branch 3 times, most recently from 1106f8a to 242e98d Compare November 6, 2025 13:55

PavelPashov force-pushed the feat/add-opentelemetry-metrics branch from 364ff86 to 30b0e8c Compare January 19, 2026 08:35

PavelPashov force-pushed the feat/add-opentelemetry-metrics branch 2 times, most recently from 0e91b34 to e2cc888 Compare February 20, 2026 15:32

PavelPashov marked this pull request as ready for review February 25, 2026 11:28

PavelPashov added 12 commits February 25, 2026 13:30

wip: add OpenTelemetry metrics instrumentation

2d569f7

add noop metrics

364ed40

fix: check if metrics are initilized in sendCommand

2e3cb2a

fix(otel): optimize metrics tracking by eliminating promise chaining …

cd31dfa

…overhead

refactor(otel): organize metrics into specialized metric groups

0d55b20

fix(otel): revert metrics to be tracked in the sendCommand method

67d99ca

perf(metrics): optimize command metrics with factory pattern and inli…

ce74dc1

…ne attributes

feat: Add new OTEL_ATTRIBUTES constants

0eedb01

feat: Add client-side-caching metric group with 4 new metric names

a14d159

feat: Create error categorization stub function

46ebd09

feat: Add pool name formatting utility function

cfe88dc

feat: Refactor recordConnectionCreateTime to use closure pattern

bccbdf7

test(otel): add maintenance metrics e2e scenario with standalone FI c…

d0f42d3

…onfig

PavelPashov force-pushed the feat/add-opentelemetry-metrics branch from af9f0fb to d0f42d3 Compare February 25, 2026 11:34

PavelPashov changed the title ~~wip: add OpenTelemetry metrics instrumentation~~ add OpenTelemetry metrics instrumentation Feb 25, 2026

refactor(otel): use instrumentation scope name and stop injecting res…

3e19cad

…ource attrs

vladvildanov requested changes Feb 25, 2026

View reviewed changes

vladvildanov reviewed Feb 26, 2026

View reviewed changes

packages/client/lib/opentelemetry/noop-metrics.ts Show resolved Hide resolved

PavelPashov added 2 commits February 26, 2026 14:37

fix(opentelemetry): rename stream bucket config

baac384

docs(opentelemetry): add metrics docs/examples

08c7413

cursor bot reviewed Feb 26, 2026

View reviewed changes

packages/client/lib/client/index.ts Show resolved Hide resolved

packages/client/lib/client/cache.ts Outdated Show resolved Hide resolved

packages/client/lib/cluster/index.ts Outdated Show resolved Hide resolved

packages/client/lib/client/socket.ts Show resolved Hide resolved

PavelPashov commented Feb 27, 2026

View reviewed changes

nkaradzhov reviewed Mar 4, 2026

View reviewed changes

fix(otel): scope redirection error dedupe to cluster retry path

f8a51c9

cursor bot reviewed Mar 4, 2026

View reviewed changes

packages/client/lib/opentelemetry/metrics.ts Show resolved Hide resolved

fix(opentelemetry): normalize db.namespace and server.port to strings…

181d086

… in command and CSC metrics

cursor bot reviewed Mar 5, 2026

View reviewed changes

packages/client/lib/client/cache.ts Show resolved Hide resolved

PavelPashov force-pushed the feat/add-opentelemetry-metrics branch from bf97457 to adbe066 Compare March 5, 2026 14:57

cursor bot reviewed Mar 5, 2026

View reviewed changes

packages/client/lib/opentelemetry/metrics.ts Show resolved Hide resolved

fix(otel): disable recordNetworkBytesSaved for CSC

bc14732

PavelPashov force-pushed the feat/add-opentelemetry-metrics branch from adbe066 to bc14732 Compare March 5, 2026 15:01

refactor(otel): remove command.onSuccess

32d63f2

cursor bot reviewed Mar 9, 2026

View reviewed changes

packages/client/lib/client/socket.ts Show resolved Hide resolved

PavelPashov mentioned this pull request Mar 23, 2026

feat: implement diagnostic channels for observability #3195

Open

feat(otel): convert connection count metric to UpDownCounter (#6)

8957026

cursor bot reviewed Mar 25, 2026

View reviewed changes

packages/client/lib/client/index.ts Show resolved Hide resolved

fix: keep registry identity in sync after _setIdentity

6b04331

cursor bot reviewed Mar 25, 2026

View reviewed changes

packages/client/lib/client/index.ts Show resolved Hide resolved

logaretm mentioned this pull request Mar 26, 2026

feat: TracingChannel-powered observability logaretm/node-redis#1

Draft

		if (command.onSuccess) {
		command.onSuccess(parser.redisArgs, finalReply, this._self._clientId);

Conversation

PavelPashov commented Oct 24, 2025 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Uh oh!

jit-ci bot left a comment

Choose a reason for hiding this comment

Uh oh!

elimelt commented Dec 8, 2025

Uh oh!

jit-ci bot commented Jan 19, 2026

❌ Security scan failed

Uh oh!

jit-ci bot commented Jan 19, 2026

❌ Security scan failed

Uh oh!

jit-ci bot commented Jan 19, 2026

❌ Security scan failed

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

PavelPashov Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

PavelPashov Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

nkaradzhov Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

PavelPashov Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

PavelPashov commented Mar 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

PavelPashov commented Oct 24, 2025 •

edited by cursor bot

Loading

PavelPashov commented Mar 23, 2026 •

edited

Loading