add OpenTelemetry metrics instrumentation

README.md

@@ -311,6 +311,33 @@ See the [Programmability overview](https://github.com/redis/node-redis/blob/mast
 
 Check out the [Clustering Guide](https://github.com/redis/node-redis/blob/master/docs/clustering.md) when using Node Redis to connect to a Redis Cluster.
 
+### OpenTelemetry
+
+#### OpenTelemetry Metrics Instrumentation
+
+```typescript
+import { createClient, OpenTelemetry } from "redis";
+
+OpenTelemetry.init({
+  metrics: {
+    enabled: true
+  }
+});
+
+const client = createClient()
+
+await client.connect();
+// ... use the client as usual
+```
+
+**Important:** Initializing `OpenTelemetry` only enables node-redis metrics instrumentation and requires both `@opentelemetry/api` and an OpenTelemetry SDK configured in your application.
+
+**Important:** Initialize `OpenTelemetry` before creating Redis clients.
+For SDK/provider/exporter setup, verification, and advanced configuration, see:
+
+- [OpenTelemetry Metrics docs](./docs/otel-metrics.md)
+- [OpenTelemetry Metrics example](./examples/otel-metrics.js)
+
 ### Events
 
 The Node Redis client class is an Nodejs EventEmitter and it emits an event each time the network status changes:

docs/otel-metrics.md

@@ -0,0 +1,173 @@
+# OpenTelemetry Metrics
+
+## Get started
+
+### Step 1. Install node-redis dependencies
+
+```bash
+npm install redis @opentelemetry/api
+```
+
+`@opentelemetry/api` is required at runtime for `OpenTelemetry.init(...)`.
+
+### Step 2. Install OpenTelemetry SDK packages
+
+```bash
+npm install @opentelemetry/sdk-metrics
+```
+
+Alternative (Node SDK):
+
+```bash
+npm install @opentelemetry/sdk-node @opentelemetry/sdk-metrics
+```
+
+If you export to OTLP or another backend, install the matching OpenTelemetry exporter package.
+
+For more information, see the [OpenTelemetry Metrics documentation](https://opentelemetry.io/docs/instrumentation/js/exporters/#metrics).
+
+### Step 3. Register OpenTelemetry
+
+Option A: Use `@opentelemetry/sdk-metrics` directly
+
+```typescript
+import { metrics } from "@opentelemetry/api";
+import {
+  ConsoleMetricExporter,
+  MeterProvider,
+  PeriodicExportingMetricReader,
+} from "@opentelemetry/sdk-metrics";
+
+const meterProvider = new MeterProvider({
+  readers: [
+    new PeriodicExportingMetricReader({
+      exporter: new ConsoleMetricExporter(),
+      exportIntervalMillis: 1000,
+    }),
+  ],
+});
+
+metrics.setGlobalMeterProvider(meterProvider);
+```
+
+Option B: Use `@opentelemetry/sdk-node`
+
+```typescript
+import { NodeSDK } from "@opentelemetry/sdk-node";
+import {
+  ConsoleMetricExporter,
+  PeriodicExportingMetricReader,
+} from "@opentelemetry/sdk-metrics";
+
+const sdk = new NodeSDK({
+  metricReader: new PeriodicExportingMetricReader({
+    exporter: new ConsoleMetricExporter(),
+    exportIntervalMillis: 1000,
+  }),
+});
+
+await sdk.start();
+```
+
+### Step 4. Initialize node-redis instrumentation before creating clients
+
+```typescript
+import { createClient, OpenTelemetry } from "redis";
+
+OpenTelemetry.init({
+  metrics: {
+    enabled: true,
+  },
+});
+
+const client = createClient();
+await client.connect();
+```
+
+## Examples
+
+### Minimal Example
+
+```typescript
+import { OpenTelemetry } from "redis";
+
+OpenTelemetry.init({
+  metrics: {
+    enabled: true,
+  },
+});
+```
+
+### Full Example
+
+```typescript
+import { OpenTelemetry } from "redis";
+
+OpenTelemetry.init({
+  metrics: {
+    enabled: true,
+    meterProvider: customMeterProvider,
+    enabledMetricGroups: ["command", "pubsub", "streaming", "resiliency"],
+    includeCommands: ["GET", "HSET", "XREADGROUP", "PUBLISH"],
+    excludeCommands: ["SET"],
+    hidePubSubChannelNames: true,
+    hideStreamNames: false,
+    bucketsOperationDuration: [0.001, 0.01, 0.1, 1],
+    bucketsStreamProcessingDuration: [0.01, 0.1, 1, 5],
+  },
+});
+```
+
+## Configuration
+
+### ObservabilityConfig
+
+| Property | Default | Description |
+| -------- | ------- | ----------- |
+| metrics |  | OpenTelemetry metrics configuration for node-redis. |
+
+### MetricConfig
+
+| Property | Default | Description |
+| -------- | ------- | ----------- |
+| enabled | **false** | Enables metric collection. |
+| meterProvider |  | Uses this provider instead of the global provider from @opentelemetry/api. |
+| includeCommands | **[]** | Case-insensitive allow-list for command metrics. |
+| excludeCommands | **[]** | Case-insensitive deny-list for command metrics. If both include and exclude match, exclude wins. |
+| enabledMetricGroups | **['connection-basic', 'resiliency']** | Metric groups to enable. Supported groups: command, connection-basic, connection-advanced, resiliency, pubsub, streaming, client-side-caching. |
+| hidePubSubChannelNames | **false** | If true, omits redis.client.pubsub.channel to reduce cardinality. |
+| hideStreamNames | **false** | If true, omits redis.client.stream.name to reduce cardinality. |
+| bucketsOperationDuration | **[0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1, 5, 10]** | Histogram bucket boundaries for db.client.operation.duration (seconds). |
+| bucketsConnectionCreateTime | **[0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1, 5, 10]** | Histogram bucket boundaries for db.client.connection.create_time (seconds). |
+| bucketsConnectionWaitTime | **[0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1, 5, 10]** | Histogram bucket boundaries for db.client.connection.wait_time (seconds). |
+| bucketsStreamProcessingDuration | **[0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1, 5, 10]** | Histogram bucket boundaries for redis.client.stream.lag (seconds). |
+
+## Metric groups and metrics
+
+| Metric Group | Metric Name |
+| ------------ | ----------- |
+| command | db.client.operation.duration |
+| connection-basic | db.client.connection.count |
+| connection-basic | db.client.connection.create_time |
+| connection-basic | redis.client.connection.relaxed_timeout |
+| connection-basic | redis.client.connection.handoff |
+| connection-advanced | db.client.connection.pending_requests |
+| connection-advanced | db.client.connection.wait_time |
+| connection-advanced | redis.client.connection.closed |
+| resiliency | redis.client.errors |
+| resiliency | redis.client.maintenance.notifications |
+| pubsub | redis.client.pubsub.messages |
+| streaming | redis.client.stream.lag |
+| client-side-caching | redis.client.csc.requests |
+| client-side-caching | redis.client.csc.items |
+| client-side-caching | redis.client.csc.evictions |
+| client-side-caching | redis.client.csc.network_saved |
+
+## Notes
+
+- `OpenTelemetry` is a singleton and a second `init` call throws.
+- If `@opentelemetry/api` is not installed, `init` throws.
+
+## Runnable example
+
+See ../examples/otel-metrics.js.

examples/README.md

@@ -18,6 +18,7 @@ This folder contains example scripts showing how to use Node Redis in different
 | `hyperloglog.js`                         | Showing use of Hyperloglog commands [PFADD, PFCOUNT and PFMERGE](https://redis.io/commands/?group=hyperloglog).                                      |
 | `lua-multi-incr.js`                      | Define a custom lua script that allows you to perform INCRBY on multiple keys.                                                                       |
 | `managing-json.js`                       | Store, retrieve and manipulate JSON data atomically with [RedisJSON](https://redisjson.io/).                                                         |
+| `otel-metrics.js`                        | Enable OpenTelemetry metrics for node-redis, generate command and resiliency signals, and export them via OpenTelemetry SDK metrics.                 |
 | `pubsub-publisher.js`                    | Adds multiple messages on 2 different channels messages to Redis.                                                                                    |
 | `pubsub-subscriber.js`                   | Reads messages from channels using `PSUBSCRIBE` command.                                                                                             |
 | `search-hashes.js`                       | Uses [RediSearch](https://redisearch.io) to index and search data in hashes.                                                                         |

examples/otel-metrics.js

@@ -0,0 +1,58 @@
+// OpenTelemetry metrics example for node-redis.
+// Demonstrates enablement, command activity, and metric export verification.
+
+import { createClient, OpenTelemetry } from 'redis';
+import { metrics } from '@opentelemetry/api';
+import {
+  ConsoleMetricExporter,
+  MeterProvider,
+  PeriodicExportingMetricReader
+} from '@opentelemetry/sdk-metrics';
+
+// Export metrics to console for easy local verification.
+const reader = new PeriodicExportingMetricReader({
+  exporter: new ConsoleMetricExporter(),
+});
+
+const meterProvider = new MeterProvider({
+  readers: [reader]
+});
+
+metrics.setGlobalMeterProvider(meterProvider);
+
+// Enable OpenTelemetry before creating clients
+OpenTelemetry.init({
+  metrics: {
+    enabled: true,
+    enabledMetricGroups: ['command', 'connection-basic', 'resiliency'],
+  }
+});
+
+const client = createClient();
+
+client.on('error', (err) => {
+  console.error('Redis client error:', err);
+});
+
+try {
+  await client.connect();
+
+  // Normal command traffic.
+  await client.ping();
+  await client.set('otel:example:key', '1');
+  await client.get('otel:example:key');
+
+  // Generate a handled error to demonstrate resiliency metrics.
+  await client.hSet('otel:example:hash', 'field', 'value');
+  try {
+    await client.incr('otel:example:hash');
+  } catch (err) {
+    console.log('Expected command error:', err);
+  }
+
+  // Force export so output is visible immediately.
+  await meterProvider.forceFlush();
+} finally {
+  client.destroy();
+  await meterProvider.shutdown();
+}