watersRand
diff --git a/‎README.md‎
Lines changed: 4 additions & 0 deletions b/‎README.md‎
Lines changed: 4 additions & 0 deletions
diff --git a/‎docs/diagnostics-channel.md‎
Lines changed: 63 additions & 0 deletions b/‎docs/diagnostics-channel.md‎
Lines changed: 63 additions & 0 deletions
diff --git a/‎package-lock.json‎
Lines changed: 8 additions & 20 deletions b/‎package-lock.json‎
Lines changed: 8 additions & 20 deletions
diff --git a/‎packages/bloom/package.json‎
Lines changed: 1 addition & 1 deletion b/‎packages/bloom/package.json‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎packages/client/index.ts‎
Lines changed: 20 additions & 0 deletions b/‎packages/client/index.ts‎
Lines changed: 20 additions & 0 deletions
diff --git a/‎packages/client/lib/client/cache.ts‎
Lines changed: 8 additions & 21 deletions b/‎packages/client/lib/client/cache.ts‎
Lines changed: 8 additions & 21 deletions
diff --git a/‎packages/client/lib/client/enterprise-maintenance-manager.ts‎
Lines changed: 9 additions & 12 deletions b/‎packages/client/lib/client/enterprise-maintenance-manager.ts‎
Lines changed: 9 additions & 12 deletions
@@ -353,6 +353,10 @@ For SDK/provider/exporter setup, verification, and advanced configuration, see:
 - [OpenTelemetry Metrics docs](./docs/otel-metrics.md)
 - [OpenTelemetry Metrics example](./examples/otel-metrics.js)
 
+### Diagnostics Channel
+
+Node Redis publishes telemetry through Node.js [`diagnostics_channel`](https://nodejs.org/api/diagnostics_channel.html), enabling APM tools and custom instrumentation to observe commands, connections, and internal events. See the [Diagnostics Channel guide](./docs/diagnostics-channel.md) for the full channel reference and usage examples.
+
 ### Events
 
 The Node Redis client class is an Nodejs EventEmitter and it emits an event each time the network status changes:
 
@@ -0,0 +1,63 @@
+# Diagnostics Channel
+
+Node Redis publishes telemetry through Node.js [`diagnostics_channel`](https://nodejs.org/api/diagnostics_channel.html), allowing APM tools and custom instrumentation to observe commands, connections, and internal events without modifying application code.
+
+All channel name constants (`CHANNELS`) and payload types are exported from `@redis/client`.
+
+```typescript
+import { CHANNELS, type CommandTraceContext } from "@redis/client";
+```
+
+## Channel Types
+
+### TracingChannels (async lifecycle)
+
+Requires Node.js >= 18.19.0. These channels use Node.js `TracingChannel#tracePromise()` and emit `start`, `end`, `asyncStart`, `asyncEnd`, and `error` sub-events. `start`/`end` wrap the synchronous portion of the traced callback, while `asyncStart`/`asyncEnd` wrap the returned promise. Subscribe via `tracing:<name>:<event>`, for example `tracing:node-redis:command:start` or `tracing:node-redis:command:asyncEnd`.
+
+```typescript
+import dc from "node:diagnostics_channel";
+
+// Fired when the command starts.
+dc.subscribe("tracing:node-redis:command:start", ({ command, args }) => {
+  console.log(`> ${command}`, args);
+});
+
+// Fired when the async Redis operation settles (success or failure).
+dc.subscribe("tracing:node-redis:command:asyncEnd", ({ command }) => {
+  console.log(`${command} settled`);
+});
+
+dc.subscribe("tracing:node-redis:command:error", ({ command, error }) => {
+  console.error(`${command} failed:`, error);
+});
+```
+
+| Channel name         | Payload                                          | Description                                |
+| -------------------- | ------------------------------------------------ | ------------------------------------------ |
+| `node-redis:command` | `CommandTraceContext / BatchCommandTraceContext`  | Individual command (standalone or pipeline) |
+| `node-redis:batch`   | `BatchOperationContext`                           | MULTI/PIPELINE batch as a whole            |
+| `node-redis:connect` | `ConnectTraceContext`                             | Socket connection attempt                  |
+
+### Point-event channels (fire-and-forget)
+
+Work on Node.js >= 16. Subscribe via `dc.subscribe('<name>', handler)`.
+
+```typescript
+dc.subscribe("node-redis:connection:ready", ({ clientId, createTimeMs }) => {
+  console.log(`Client ${clientId} connected in ${createTimeMs.toFixed(1)}ms`);
+});
+```
+
+| Channel name                            | Payload                         | Description                              |
+| --------------------------------------- | ------------------------------- | ---------------------------------------- |
+| `node-redis:connection:ready`           | `ConnectionReadyEvent`          | Socket connected and ready               |
+| `node-redis:connection:closed`          | `ConnectionClosedEvent`         | Socket closed                            |
+| `node-redis:connection:relaxed-timeout` | `ConnectionRelaxedTimeoutEvent` | Timeout relaxed/restored for maintenance |
+| `node-redis:connection:handoff`         | `ConnectionHandoffEvent`        | Maintenance handoff completed            |
+| `node-redis:error`                      | `ClientErrorEvent`              | Client or cluster error                  |
+| `node-redis:maintenance`                | `MaintenanceNotificationEvent`  | Maintenance push notification            |
+| `node-redis:pubsub`                     | `PubSubMessageEvent`            | Inbound PubSub message                   |
+| `node-redis:cache:request`              | `CacheRequestEvent`             | Client-side cache hit/miss               |
+| `node-redis:cache:eviction`             | `CacheEvictionEvent`            | Cache entry evicted                      |
+| `node-redis:command:reply`              | `CommandReplyEvent`             | Command reply (for pubsub/streaming)     |
+| `node-redis:pool:connection-wait`       | `PoolConnectionWaitEvent`       | Pool task acquired a client              |
@@ -19,7 +19,7 @@
     "@redis/test-utils": "*"
   },
   "engines": {
-    "node": ">= 18"
+    "node": ">= 18.19.0"
   },
   "repository": {
     "type": "git",
 
@@ -37,3 +37,23 @@ export { SetOptions, CLIENT_KILL_FILTERS, FAILOVER_MODES, CLUSTER_SLOT_STATES, C
 
 export { BasicClientSideCache, BasicPooledClientSideCache } from './lib/client/cache';
 export { OpenTelemetry } from './lib/opentelemetry';
+
+export {
+  CHANNELS,
+  type ChannelEvents,
+  type CommandTraceContext,
+  type BatchCommandTraceContext,
+  type BatchOperationContext,
+  type ConnectTraceContext,
+  type ConnectionReadyEvent,
+  type ConnectionClosedEvent,
+  type ConnectionRelaxedTimeoutEvent,
+  type ConnectionHandoffEvent,
+  type ClientErrorEvent,
+  type MaintenanceNotificationEvent,
+  type PubSubMessageEvent,
+  type CacheRequestEvent,
+  type CacheEvictionEvent,
+  type CommandReplyEvent,
+  type PoolConnectionWaitEvent,
+} from './lib/client/tracing';
@@ -2,7 +2,7 @@ import { EventEmitter } from 'stream';
 import RedisClient from '.';
 import { RedisArgument, ReplyUnion, TransformReply, TypeMapping } from '../RESP/types';
 import { BasicCommandParser } from './parser';
-import { OTelMetrics, CSC_RESULT, CSC_EVICTION_REASON } from '../opentelemetry';
+import { publish, CHANNELS } from './tracing';
 
 /**
  * A snapshot of cache statistics.
@@ -558,33 +558,20 @@ export class BasicClientSideCache extends ClientSideCacheProvider {
       // If instanceof is "too slow", can add a "type" and then use an "as" cast to call proper getters.
       if (cacheEntry instanceof ClientSideCacheEntryValue) { // "2b1"
         this.#statsCounter.recordHits(1);
-        OTelMetrics.instance.clientSideCacheMetrics.recordCacheRequest(
-          CSC_RESULT.HIT,
-          client._clientId,
-        );
-        OTelMetrics.instance.clientSideCacheMetrics.recordNetworkBytesSaved(
-          cacheEntry.value,
-          client._clientId,
-        );
+        publish(CHANNELS.CACHE_REQUEST, () => ({ result: 'hit', clientId: client._clientId }));
 
         return structuredClone(cacheEntry.value);
       } else if (cacheEntry instanceof ClientSideCacheEntryPromise) { // 2b2
         // This counts as a miss since the value hasn't been fully loaded yet.
         this.#statsCounter.recordMisses(1);
-        OTelMetrics.instance.clientSideCacheMetrics.recordCacheRequest(
-          CSC_RESULT.MISS,
-          client._clientId,
-        );
+        publish(CHANNELS.CACHE_REQUEST, () => ({ result: 'miss', clientId: client._clientId }));
         reply = await cacheEntry.promise;
       } else {
         throw new Error("unknown cache entry type");
       }
     } else { // 3/3a
       this.#statsCounter.recordMisses(1);
-      OTelMetrics.instance.clientSideCacheMetrics.recordCacheRequest(
-        CSC_RESULT.MISS,
-        client._clientId,
-      );
+      publish(CHANNELS.CACHE_REQUEST, () => ({ result: 'miss', clientId: client._clientId }));
 
       const startTime = performance.now();
       const promise = fn();
@@ -640,7 +627,7 @@ export class BasicClientSideCache extends ClientSideCacheProvider {
       this.clear(false);
       // Record invalidations as server-initiated evictions
       if (oldSize > 0) {
-        OTelMetrics.instance.clientSideCacheMetrics.recordCacheEviction(CSC_EVICTION_REASON.INVALIDATION, oldSize);
+        publish(CHANNELS.CACHE_EVICTION, () => ({ reason: 'invalidation', count: oldSize }));
       }
       this.emit("invalidate", key);
 
@@ -661,7 +648,7 @@ export class BasicClientSideCache extends ClientSideCacheProvider {
       this.#keyToCacheKeySetMap.delete(key.toString());
       if (deletedCount > 0) {
         // Record invalidations as server-initiated evictions
-        OTelMetrics.instance.clientSideCacheMetrics.recordCacheEviction(CSC_EVICTION_REASON.INVALIDATION, deletedCount);
+        publish(CHANNELS.CACHE_EVICTION, () => ({ reason: 'invalidation', count: deletedCount }));
       }
     }
 
@@ -692,7 +679,7 @@ export class BasicClientSideCache extends ClientSideCacheProvider {
       this.delete(cacheKey);
       this.#statsCounter.recordEvictions(1);
       // Entry failed validation - this is TTL expiry since invalidation marks are handled separately
-      OTelMetrics.instance.clientSideCacheMetrics.recordCacheEviction(CSC_EVICTION_REASON.TTL);
+      publish(CHANNELS.CACHE_EVICTION, () => ({ reason: 'ttl', count: 1 }));
       this.emit("cache-evict", cacheKey);
 
       return undefined;
@@ -731,7 +718,7 @@ export class BasicClientSideCache extends ClientSideCacheProvider {
       this.deleteOldest();
       this.#statsCounter.recordEvictions(1);
       // Eviction due to cache capacity limit
-      OTelMetrics.instance.clientSideCacheMetrics.recordCacheEviction(CSC_EVICTION_REASON.FULL);
+      publish(CHANNELS.CACHE_EVICTION, () => ({ reason: 'full', count: 1 }));
     }
 
     this.#cacheKeyToEntryMap.set(cacheKey, cacheEntry);
 
@@ -7,8 +7,7 @@ import { setTimeout } from "node:timers/promises";
 import { RedisTcpSocketOptions } from "./socket";
 import diagnostics_channel from "node:diagnostics_channel";
 import { RedisArgument } from "../RESP/types";
-import {  OTelMetrics } from "../opentelemetry";
-import { METRIC_ERROR_ORIGIN } from "../opentelemetry/types";
+import { publish, CHANNELS } from "./tracing";
 
 type RedisType = RedisClient<any, any, any, any, any>;
 
@@ -124,12 +123,12 @@ export default class EnterpriseMaintenanceManager {
       errorHandler: (error: Error) => {
         dbgMaintenance("handshake failed:", error);
 
-        OTelMetrics.instance.resiliencyMetrics.recordClientErrors({
+        publish(CHANNELS.ERROR, () => ({
           error,
-          origin: METRIC_ERROR_ORIGIN.CLIENT,
+          origin: 'client',
           internal: true,
           clientId,
-        });
+        }));
 
         if (options.maintNotifications === "enabled") {
           throw error;
@@ -160,10 +159,10 @@ export default class EnterpriseMaintenanceManager {
 
     const type = String(push[0]);
 
-    OTelMetrics.instance.resiliencyMetrics.recordMaintenanceNotifications(
-      type,
-      this.#client._clientId,
-    );
+    publish(CHANNELS.MAINTENANCE, () => ({
+      notification: type,
+      clientId: this.#client._clientId,
+    }));
 
     emitDiagnostics({
       type,
@@ -306,9 +305,7 @@ export default class EnterpriseMaintenanceManager {
     dbgMaintenance("Resume writing");
     this.#client._unpause();
     this.#onMigrated();
-    OTelMetrics.instance.connectionBasicMetrics.recordConnectionHandoff(
-      this.#client._clientId,
-    );
+    publish(CHANNELS.CONNECTION_HANDOFF, () => ({ clientId: this.#client._clientId }));
   };
 
   #onMigrating = () => {