feat: add @grpc/grpc-js driver instrumentation

Patches all four call types on Client.prototype:
- makeUnaryRequest / makeClientStreamRequest: wrap callback, capture duration
- makeServerStreamRequest / makeBidiStreamRequest: listen for stream status/error events;
  a published flag prevents double-publishing when both events fire for the same call

RPC method path (e.g. /pkg.Service/Method) is used as the query key, making gRPC
calls visible in slow-query logs, cache monitor, and OTLP exports.
Silently skipped when @grpc/grpc-js is not installed (consistent with other drivers).

17 drivers total (up from 16). 17 new tests: 12 behavior + 5 coverage.
README, CHANGELOG, and Project Structure updated.

Author: sharon77242

CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [Unreleased]
+
+### Added
+- **gRPC instrumentation** — `@grpc/grpc-js` driver patch (`drivers/grpc.ts`).
+  Auto-patches all four call types on `Client.prototype`:
+  - **Unary** (`makeUnaryRequest`) and **client-streaming** (`makeClientStreamRequest`) — wraps the callback to capture wall-clock duration and forward errors to `diagnostics_channel`.
+  - **Server-streaming** (`makeServerStreamRequest`) and **bidi-streaming** (`makeBidiStreamRequest`) — listens for the stream's `status` (completion) and `error` events; a `published` flag prevents double-publishing when both events fire for the same call.
+  The RPC method path (e.g. `/package.Service/Method`) is used as the query key, making gRPC calls visible in slow-query logs, the cache monitor, and OTLP exports.
+  17 drivers total (up from 16). Wired into `applyDriverPatches()` under a new `// RPC` section; silently skipped when `@grpc/grpc-js` is not installed.
+
+---
+
 ## [0.3.2] — 2026-04-29
 
 ### Changed

README.md

@@ -79,7 +79,7 @@ The agent has two distinct usage modes with different Node.js requirements:
 
 | Feature | Minimum Node | Behaviour on older versions |
 |---|---|---|
-| DB query tracing (all 16 drivers) | 14.18.0 | Full support — we control both publisher and subscriber |
+| DB query tracing (all 17 drivers) | 14.18.0 | Full support — we control both publisher and subscriber |
 | HTTP outbound tracing | 18.0.0 | Automatic via `diagnostics_channel`; on Node 14–17 the agent falls back to monkey-patching `http.request` / `https.request` automatically |
 | Module load timing (`slow-require`) | 20.0.0 | Silent no-op on Node < 20 (channels absent) |
 | Stream leak auto-detection | 22.0.0 | Falls back to manual `track()` calls on Node < 22 |
@@ -126,7 +126,7 @@ import { ArgusAgent } from 'argus-apm';
 git clone https://github.com/sharon77242/Argus.git
 pnpm install
 
-# Run all 373 tests (uses --experimental-strip-types, requires Node 22.6+)
+# Run all 618 tests (uses --experimental-strip-types, requires Node 22.6+)
 pnpm test
 
 # Build both ESM and CJS outputs
@@ -296,7 +296,7 @@ import fs from 'node:fs';
 const agent = await ArgusAgent.create()
   .withSourceMaps('./dist')                          // Source-map resolution for stack traces
   .withRuntimeMonitor({ eventLoopThresholdMs: 50 }) // Event loop lag + memory leak detection
-  .withInstrumentation({ autoPatching: true })       // 16 DB drivers via diagnostics_channel
+  .withInstrumentation({ autoPatching: true })       // 17 DB/RPC drivers via diagnostics_channel
   .withHttpTracing()                                 // Slow request & insecure HTTP detection
   .withLogTracing({ scrubContext: true })            // Strip secrets from console overrides
   .withFsTracing()                                   // ⚠ DEV ONLY — sync FS blocker detection
@@ -582,7 +582,7 @@ All thresholds can be overridden without code changes, making the agent CI/CD an
 | `.withCrashGuard()` | ✅ Yes | Very Low | Intercepts `uncaughtException`; emits event for `unhandledRejection` |
 | `.withResourceLeakMonitor(opts?)` | ✅ Yes | Low | Tracks OS handles; rate-limited by `alertCooldownMs` |
 | `.withGracefulShutdown(opts?)` | ✅ Yes | Very Low | Registers SIGTERM/SIGINT; awaits `agent.stop()` before `process.exit` |
-| `.withInstrumentation(opts?)` | ✅ Yes | Low | DB/IO tracing via `diagnostics_channel` (16 drivers) |
+| `.withInstrumentation(opts?)` | ✅ Yes | Low | DB/IO tracing via `diagnostics_channel` (17 drivers) |
 | `.withHttpTracing()` | ✅ Yes | Low | HTTP request inspection & slow-request detection |
 | `.withLogTracing(opts?)` | ✅ Yes | Low | `console.*` override with entropy-scrubbed payloads |
 | `.withFsTracing()` | ❌ **No** | High | Patches `fs`. Detects `*Sync` blockers; escalates to `sync-in-hot-path` (critical) when called inside a live request. **DEV ONLY.** |
@@ -640,7 +640,7 @@ Telemetry is exported over **mTLS** (Mutual TLS) — both client and server cert
 │ Profiling        │  Instrumentation         │  Analysis           │
 │ ──────────────── │  ─────────────────────  │  ─────────────────  │
 │ RuntimeMonitor   │  InstrumentationEngine  │  QueryAnalyzer      │
-│ CrashGuard       │  16 DB Drivers          │  SlowQueryMonitor   │
+│ CrashGuard       │  17 DB/RPC Drivers      │  SlowQueryMonitor   │
 │ ResourceLeakMon  │  HttpInstrumentation    │  TransactionMonitor │
 │ GcMonitor        │  FsInstrumentation      │  CacheMonitor       │
 │ PoolMonitor      │  LoggerInstrumentation  │  CircuitBreaker     │
@@ -711,6 +711,7 @@ packages/agent/
         bigquery.ts                  → @google-cloud/bigquery
         neo4j.ts                     → neo4j-driver
         clickhouse.ts                → @clickhouse/client
+        grpc.ts                      → @grpc/grpc-js (unary + streaming RPCs)
 
     licensing/
       public-key.ts                  → Bundled ECDSA public keys (keyed by kid)
@@ -746,7 +747,7 @@ packages/agent/
       exporter.ts                    → OTLP JSON formatter + mTLS transport
       otlp-compatible-exporter.ts    → Simplified OTLP exporter (API key, no mTLS)
 
-  tests/                             → Mirrors src/ structure (508 tests, 86 suites)
+  tests/                             → Mirrors src/ structure (618 tests, 121 suites)
 ```
 
 ---

packages/agent/src/instrumentation/drivers/grpc.ts

@@ -0,0 +1,133 @@
+import { performance } from "node:perf_hooks";
+import { nodeRequire } from "./_require.ts";
+import {
+  isAlreadyPatched,
+  PATCHED_SYMBOL,
+  activePatches,
+  AUTO_PATCH_CHANNEL,
+} from "./patch-utils.ts";
+import type { PatchedQueryMessage } from "./patch-utils.ts";
+import { safeChannel } from "../safe-channel.ts";
+
+const DRIVER = "@grpc/grpc-js";
+
+type AnyProto = Record<string, any>;
+
+// Wraps callback-bearing gRPC calls: makeUnaryRequest and makeClientStreamRequest.
+// args[0] is always the full RPC method path, e.g. /package.Service/Method.
+// The callback (err, response) is always the last function argument.
+function wrapCallbackMethod(proto: AnyProto, methodName: string): void {
+  if (isAlreadyPatched(proto, methodName)) return;
+  const original = proto[methodName] as (...args: unknown[]) => unknown;
+  const channel = safeChannel(AUTO_PATCH_CHANNEL);
+
+  const wrapped = function (this: unknown, ...args: unknown[]) {
+    const start = performance.now();
+    const query = typeof args[0] === "string" ? args[0] : String(args[0]);
+
+    const lastIdx = args.length - 1;
+    if (lastIdx >= 0 && typeof args[lastIdx] === "function") {
+      const originalCb = args[lastIdx] as (...a: unknown[]) => unknown;
+      args[lastIdx] = function (this: unknown, err: unknown, ...rest: unknown[]) {
+        channel.publish({
+          query,
+          durationMs: performance.now() - start,
+          driver: DRIVER,
+          error: err ?? undefined,
+        } satisfies PatchedQueryMessage);
+        return originalCb.call(this, err, ...rest);
+      };
+    }
+
+    return original.apply(this, args);
+  };
+
+  (wrapped as unknown as Record<symbol, unknown>)[PATCHED_SYMBOL] = true;
+  proto[methodName] = wrapped;
+  activePatches.push({ target: proto, methodName, original });
+}
+
+// Wraps stream-returning gRPC calls: makeServerStreamRequest and makeBidiStreamRequest.
+// Timing covers from call initiation to the stream's 'status' (success) or 'error' event.
+// The published flag prevents double-publishing when both events fire for a single call.
+function wrapStreamMethod(proto: AnyProto, methodName: string): void {
+  if (isAlreadyPatched(proto, methodName)) return;
+  const original = proto[methodName] as (...args: unknown[]) => unknown;
+  const channel = safeChannel(AUTO_PATCH_CHANNEL);
+
+  const wrapped = function (this: unknown, ...args: unknown[]) {
+    const start = performance.now();
+    const query = typeof args[0] === "string" ? args[0] : String(args[0]);
+
+    const stream = original.apply(this, args);
+
+    if (stream != null && typeof stream === "object") {
+      const s = stream as Record<string, unknown>;
+      if (typeof s.once === "function") {
+        let published = false;
+        const publish = (err?: unknown) => {
+          if (published) return;
+          published = true;
+          channel.publish({
+            query,
+            durationMs: performance.now() - start,
+            driver: DRIVER,
+            error: err,
+          } satisfies PatchedQueryMessage);
+        };
+        (s.once as (e: string, fn: (...a: unknown[]) => void) => void)("status", () => publish());
+        (s.once as (e: string, fn: (err: unknown) => void) => void)("error", (err) => publish(err));
+      }
+    }
+
+    return stream;
+  };
+
+  (wrapped as unknown as Record<symbol, unknown>)[PATCHED_SYMBOL] = true;
+  proto[methodName] = wrapped;
+  activePatches.push({ target: proto, methodName, original });
+}
+
+export function patchGrpc(): boolean {
+  try {
+    const grpc = nodeRequire("@grpc/grpc-js");
+    const clientProto: AnyProto | undefined = grpc.Client?.prototype;
+    if (!clientProto) return false;
+
+    let patched = false;
+
+    if (clientProto.makeUnaryRequest && !isAlreadyPatched(clientProto, "makeUnaryRequest")) {
+      wrapCallbackMethod(clientProto, "makeUnaryRequest");
+      patched = true;
+    }
+
+    if (
+      clientProto.makeClientStreamRequest &&
+      !isAlreadyPatched(clientProto, "makeClientStreamRequest")
+    ) {
+      wrapCallbackMethod(clientProto, "makeClientStreamRequest");
+      patched = true;
+    }
+
+    if (
+      clientProto.makeServerStreamRequest &&
+      !isAlreadyPatched(clientProto, "makeServerStreamRequest")
+    ) {
+      wrapStreamMethod(clientProto, "makeServerStreamRequest");
+      patched = true;
+    }
+
+    if (
+      clientProto.makeBidiStreamRequest &&
+      !isAlreadyPatched(clientProto, "makeBidiStreamRequest")
+    ) {
+      wrapStreamMethod(clientProto, "makeBidiStreamRequest");
+      patched = true;
+    }
+
+    return patched;
+  } catch {
+    /* not installed */
+  }
+  return false;
+}

packages/agent/src/instrumentation/drivers/index.ts

@@ -13,6 +13,7 @@ import { patchFirestore } from "./firestore.ts";
 import { patchCassandra } from "./cassandra.ts";
 import { patchNeo4j } from "./neo4j.ts";
 import { patchClickhouse } from "./clickhouse.ts";
+import { patchGrpc } from "./grpc.ts";
 
 // Re-export shared utilities for external consumers
 export { AUTO_PATCH_CHANNEL, patchMethod } from "./patch-utils.ts";
@@ -30,6 +31,7 @@ export type { PatchedQueryMessage } from "./patch-utils.ts";
  * - Cloud: @google-cloud/bigquery
  * - Graph: neo4j-driver
  * - Analytics: @clickhouse/client
+ * - RPC:  @grpc/grpc-js
  */
 export function applyDriverPatches(): string[] {
   const patched: string[] = [];
@@ -57,6 +59,9 @@ export function applyDriverPatches(): string[] {
   if (patchNeo4j()) patched.push("neo4j-driver");
   if (patchClickhouse()) patched.push("@clickhouse/client");
 
+  // RPC
+  if (patchGrpc()) patched.push("@grpc/grpc-js");
+
   return patched;
 }
 

packages/agent/tests/instrumentation/drivers-all-coverage.test.ts

@@ -674,4 +674,74 @@ describe("Driver Patch Modules (coverage)", () => {
       }
     });
   });
+
+  // ── grpc.ts ────────────────────────────────────────────────────
+  describe("patchGrpc", () => {
+    it("should patch @grpc/grpc-js Client prototype methods", async () => {
+      const { patchGrpc } = await import("../../src/instrumentation/drivers/grpc.ts");
+      const mockProto: Record<string, any> = {
+        makeUnaryRequest: () => {},
+        makeClientStreamRequest: () => ({}),
+        makeServerStreamRequest: () => ({}),
+        makeBidiStreamRequest: () => ({}),
+      };
+      const restore = mockNodeRequire(() => ({ Client: { prototype: mockProto } }));
+      try {
+        assert.strictEqual(patchGrpc(), true);
+      } finally {
+        restore();
+        cleanupPatches();
+      }
+    });
+
+    it("should return false when Client.prototype is missing", async () => {
+      const { patchGrpc } = await import("../../src/instrumentation/drivers/grpc.ts");
+      const restore = mockNodeRequire(() => ({ Client: {} }));
+      try {
+        assert.strictEqual(patchGrpc(), false);
+      } finally {
+        restore();
+      }
+    });
+
+    it("should return false when Client is absent", async () => {
+      const { patchGrpc } = await import("../../src/instrumentation/drivers/grpc.ts");
+      const restore = mockNodeRequire(() => ({}));
+      try {
+        assert.strictEqual(patchGrpc(), false);
+      } finally {
+        restore();
+      }
+    });
+
+    it("should return false when not installed", async () => {
+      const { patchGrpc } = await import("../../src/instrumentation/drivers/grpc.ts");
+      const restore = mockNodeRequire(() => {
+        throw new Error("not found");
+      });
+      try {
+        assert.strictEqual(patchGrpc(), false);
+      } finally {
+        restore();
+      }
+    });
+
+    it("should return false when all methods already patched", async () => {
+      const { patchGrpc } = await import("../../src/instrumentation/drivers/grpc.ts");
+      const mockProto: Record<string, any> = {
+        makeUnaryRequest: () => {},
+        makeClientStreamRequest: () => ({}),
+        makeServerStreamRequest: () => ({}),
+        makeBidiStreamRequest: () => ({}),
+      };
+      const restore = mockNodeRequire(() => ({ Client: { prototype: mockProto } }));
+      try {
+        assert.strictEqual(patchGrpc(), true);
+        assert.strictEqual(patchGrpc(), false, "second call should return false (already patched)");
+      } finally {
+        restore();
+        cleanupPatches();
+      }
+    });
+  });
 });