feat(hooks): Hook Telemetry Infrastructure (#9082)

Author: Edilmo

packages/core/src/telemetry/loggers.ts

@@ -49,6 +49,7 @@ import type {
   WebFetchFallbackAttemptEvent,
   ExtensionUpdateEvent,
   LlmLoopCheckEvent,
+  HookCallEvent,
 } from './types.js';
 import {
   recordApiErrorMetrics,
@@ -66,6 +67,7 @@ import {
   recordAgentRunMetrics,
   recordRecoveryAttemptMetrics,
   recordLinesChanged,
+  recordHookCallMetrics,
 } from './metrics.js';
 import { isTelemetrySdkInitialized } from './sdk.js';
 import type { UiEvent } from './uiTelemetry.js';
@@ -670,3 +672,22 @@ export function logLlmLoopCheck(
   };
   logger.emit(logRecord);
 }
+
+export function logHookCall(config: Config, event: HookCallEvent): void {
+  if (!isTelemetrySdkInitialized()) return;
+
+  const logger = logs.getLogger(SERVICE_NAME);
+  const logRecord: LogRecord = {
+    body: event.toLogBody(),
+    attributes: event.toOpenTelemetryAttributes(config),
+  };
+  logger.emit(logRecord);
+
+  recordHookCallMetrics(
+    config,
+    event.hook_event_name,
+    event.hook_name,
+    event.duration_ms,
+    event.success,
+  );
+}

packages/core/src/telemetry/metrics.test.ts

@@ -1342,5 +1342,115 @@ describe('Telemetry Metrics', () => {
         expect(mockHistogramRecordFn).not.toHaveBeenCalled();
       });
     });
+
+    describe('recordHookCallMetrics', () => {
+      let recordHookCallMetricsModule: typeof import('./metrics.js').recordHookCallMetrics;
+
+      beforeEach(async () => {
+        recordHookCallMetricsModule = (await import('./metrics.js'))
+          .recordHookCallMetrics;
+      });
+
+      it('should record hook call metrics with counter and histogram', () => {
+        initializeMetricsModule(mockConfig);
+        mockCounterAddFn.mockClear();
+        mockHistogramRecordFn.mockClear();
+
+        recordHookCallMetricsModule(
+          mockConfig,
+          'BeforeTool',
+          'test-hook',
+          150,
+          true,
+        );
+
+        // Verify counter recorded
+        expect(mockCounterAddFn).toHaveBeenCalledWith(1, {
+          'session.id': 'test-session-id',
+          'installation.id': 'test-installation-id',
+          'user.email': '[email protected]',
+          hook_event_name: 'BeforeTool',
+          hook_name: 'test-hook',
+          success: true,
+        });
+
+        // Verify histogram recorded
+        expect(mockHistogramRecordFn).toHaveBeenCalledWith(150, {
+          'session.id': 'test-session-id',
+          'installation.id': 'test-installation-id',
+          'user.email': '[email protected]',
+          hook_event_name: 'BeforeTool',
+          hook_name: 'test-hook',
+          success: true,
+        });
+      });
+
+      it('should always sanitize hook names regardless of content', () => {
+        initializeMetricsModule(mockConfig);
+        mockCounterAddFn.mockClear();
+
+        // Test with a command that has sensitive information
+        recordHookCallMetricsModule(
+          mockConfig,
+          'BeforeTool',
+          '/path/to/.gemini/hooks/check-secrets.sh --api-key=abc123',
+          150,
+          true,
+        );
+
+        // Verify hook name is sanitized (detailed sanitization tested in hook-call-event.test.ts)
+        expect(mockCounterAddFn).toHaveBeenCalledWith(1, {
+          'session.id': 'test-session-id',
+          'installation.id': 'test-installation-id',
+          'user.email': '[email protected]',
+          hook_event_name: 'BeforeTool',
+          hook_name: 'check-secrets.sh', // Sanitized
+          success: true,
+        });
+      });
+
+      it('should track both success and failure', () => {
+        initializeMetricsModule(mockConfig);
+        mockCounterAddFn.mockClear();
+
+        // Success case
+        recordHookCallMetricsModule(
+          mockConfig,
+          'BeforeTool',
+          'test-hook',
+          100,
+          true,
+        );
+
+        expect(mockCounterAddFn).toHaveBeenNthCalledWith(
+          1,
+          1,
+          expect.objectContaining({
+            hook_event_name: 'BeforeTool',
+            hook_name: 'test-hook',
+            success: true,
+          }),
+        );
+
+        // Failure case
+        recordHookCallMetricsModule(
+          mockConfig,
+          'AfterTool',
+          'test-hook',
+          150,
+          false,
+        );
+
+        expect(mockCounterAddFn).toHaveBeenNthCalledWith(
+          2,
+          1,
+          expect.objectContaining({
+            hook_event_name: 'AfterTool',
+            hook_name: 'test-hook',
+            success: false,
+          }),
+        );
+      });
+    });
   });
 });

packages/core/src/telemetry/metrics.ts

@@ -16,6 +16,7 @@ import type {
 } from './types.js';
 import { AuthType } from '../core/contentGenerator.js';
 import { getCommonAttributes } from './telemetryAttributes.js';
+import { sanitizeHookName } from './sanitize.js';
 
 const EVENT_CHAT_COMPRESSION = 'gemini_cli.chat_compression';
 const TOOL_CALL_COUNT = 'gemini_cli.tool.call.count';
@@ -34,6 +35,8 @@ const MODEL_ROUTING_LATENCY = 'gemini_cli.model_routing.latency';
 const MODEL_ROUTING_FAILURE_COUNT = 'gemini_cli.model_routing.failure.count';
 const MODEL_SLASH_COMMAND_CALL_COUNT =
   'gemini_cli.slash_command.model.call_count';
+const EVENT_HOOK_CALL_COUNT = 'gemini_cli.hook_call.count';
+const EVENT_HOOK_CALL_LATENCY = 'gemini_cli.hook_call.latency';
 
 // Agent Metrics
 const AGENT_RUN_COUNT = 'gemini_cli.agent.run.count';
@@ -202,6 +205,16 @@ const COUNTER_DEFINITIONS = {
     assign: (c: Counter) => (exitFailCounter = c),
     attributes: {} as Record<string, never>,
   },
+  [EVENT_HOOK_CALL_COUNT]: {
+    description: 'Counts hook calls, tagged by hook event name and success.',
+    valueType: ValueType.INT,
+    assign: (c: Counter) => (hookCallCounter = c),
+    attributes: {} as {
+      hook_event_name: string;
+      hook_name: string;
+      success: boolean;
+    },
+  },
 } as const;
 
 const HISTOGRAM_DEFINITIONS = {
@@ -297,6 +310,17 @@ const HISTOGRAM_DEFINITIONS = {
       'error.type'?: string;
     },
   },
+  [EVENT_HOOK_CALL_LATENCY]: {
+    description: 'Latency of hook calls in milliseconds.',
+    unit: 'ms',
+    valueType: ValueType.INT,
+    assign: (c: Histogram) => (hookCallLatencyHistogram = c),
+    attributes: {} as {
+      hook_event_name: string;
+      hook_name: string;
+      success: boolean;
+    },
+  },
 } as const;
 
 const PERFORMANCE_COUNTER_DEFINITIONS = {
@@ -506,6 +530,8 @@ let agentRecoveryAttemptDurationHistogram: Histogram | undefined;
 let flickerFrameCounter: Counter | undefined;
 let exitFailCounter: Counter | undefined;
 let slowRenderHistogram: Histogram | undefined;
+let hookCallCounter: Counter | undefined;
+let hookCallLatencyHistogram: Histogram | undefined;
 
 // OpenTelemetry GenAI Semantic Convention Metrics
 let genAiClientTokenUsageHistogram: Histogram | undefined;
@@ -1162,3 +1188,27 @@ export function recordApiResponseMetrics(
     });
   }
 }
+
+export function recordHookCallMetrics(
+  config: Config,
+  hookEventName: string,
+  hookName: string,
+  durationMs: number,
+  success: boolean,
+): void {
+  if (!hookCallCounter || !hookCallLatencyHistogram || !isMetricsInitialized)
+    return;
+
+  // Always sanitize hook names in metrics (metrics are aggregated and exposed)
+  const sanitizedHookName = sanitizeHookName(hookName);
+
+  const metricAttributes: Attributes = {
+    ...baseMetricDefinition.getCommonAttributes(config),
+    hook_event_name: hookEventName,
+    hook_name: sanitizedHookName,
+    success,
+  };
+
+  hookCallCounter.add(1, metricAttributes);
+  hookCallLatencyHistogram.record(durationMs, metricAttributes);
+}