chore: disallow underscores followed by numbers in metrics names

Author: yulunz

src/telemetry/ClearcutLogger.ts

@@ -12,7 +12,7 @@ import type {zod, ShapeOutput} from '../third_party/index.js';
 
 import type {ErrorCode} from './errors.js';
 import type {LocalState, Persistence} from './persistence.js';
-import {sanitizeParams} from './transformation.js';
+import {sanitizeParams, stripUnderscoreBeforeNumber} from './transformation.js';
 import {
   McpClient,
   type FlagUsage,
@@ -113,14 +113,18 @@ export class ClearcutLogger {
     success: boolean;
     latencyMs: number;
   }): Promise<void> {
+    const sanitizedToolName = stripUnderscoreBeforeNumber(args.toolName);
     const tool_invocation: ToolInvocation = {
-      tool_name: args.toolName,
+      tool_name: sanitizedToolName,
       success: args.success,
       latency_ms: args.latencyMs,
     };
     if (Object.keys(args.params).length > 0) {
       tool_invocation.tool_params = {
-        [`${args.toolName}_params`]: sanitizeParams(args.params, args.schema),
+        [`${sanitizedToolName}_params`]: sanitizeParams(
+          args.params,
+          args.schema,
+        ),
       };
     }
 
@@ -185,7 +189,9 @@ export class ClearcutLogger {
       payload: {
         mcp_client: this.#mcpClient,
         server_error: {
-          tool_name: args.toolName ?? '',
+          tool_name: args.toolName
+            ? stripUnderscoreBeforeNumber(args.toolName)
+            : '',
           error_code: args.errorCode,
         },
       },

src/telemetry/flagUtils.ts

@@ -7,6 +7,7 @@
 import type {cliOptions} from '../bin/chrome-devtools-mcp-cli-options.js';
 import {toSnakeCase} from '../utils/string.js';
 
+import {stripUnderscoreBeforeNumber} from './transformation.js';
 import type {FlagUsage} from './types.js';
 
 type CliOptions = typeof cliOptions;
@@ -17,7 +18,9 @@ type CliOptions = typeof cliOptions;
  * as an `enum` where the keys of the enum will map to the uppercase `choice`.
  */
 function formatEnumChoice(snakeCaseName: string, choice: string): string {
-  return `${snakeCaseName}_${choice}`.toUpperCase();
+  return stripUnderscoreBeforeNumber(
+    `${snakeCaseName}_${choice}`,
+  ).toUpperCase();
 }
 
 /**
@@ -41,7 +44,7 @@ export function computeFlagUsage(
 
   for (const [flagName, config] of Object.entries(options)) {
     const value = args[flagName];
-    const snakeCaseName = toSnakeCase(flagName);
+    const snakeCaseName = stripUnderscoreBeforeNumber(toSnakeCase(flagName));
 
     // If there isn't a default value provided for the flag,
     // we're going to log whether it's present on the args user
@@ -82,7 +85,7 @@ export function getPossibleFlagMetrics(options: CliOptions): FlagMetric[] {
   const metrics: FlagMetric[] = [];
 
   for (const [flagName, config] of Object.entries(options)) {
-    const snakeCaseName = toSnakeCase(flagName);
+    const snakeCaseName = stripUnderscoreBeforeNumber(toSnakeCase(flagName));
 
     // _present is always a possible metric
     metrics.push({

src/telemetry/metricsRegistry.ts

@@ -11,6 +11,7 @@ import {
   transformArgType,
   getZodType,
   PARAM_BLOCKLIST,
+  stripUnderscoreBeforeNumber,
 } from './transformation.js';
 
 /**
@@ -118,7 +119,7 @@ export function generateToolMetrics(tools: ToolDefinition[]): ToolMetric[] {
     }
 
     return {
-      name: tool.name,
+      name: stripUnderscoreBeforeNumber(tool.name),
       args,
     };
   });

src/telemetry/tool_call_metrics.json

@@ -616,7 +616,7 @@
     ]
   },
   {
-    "name": "execute_3p_developer_tool",
+    "name": "execute3p_developer_tool",
     "args": [
       {
         "name": "tool_name_length",
@@ -629,7 +629,7 @@
     ]
   },
   {
-    "name": "list_3p_developer_tools",
+    "name": "list3p_developer_tools",
     "args": []
   }
 ]

src/telemetry/transformation.ts

@@ -53,20 +53,26 @@ export function getZodType(zodType: zod.ZodTypeAny): ZodType {
   throw new Error(`Unsupported zod type for tool parameter: ${typeName}`);
 }
 
+export function stripUnderscoreBeforeNumber(name: string): string {
+  return name.replace(/_([0-9])/g, '$1');
+}
+
 type LoggedToolCallArgValue = string | number | boolean;
 
 export function transformArgName(zodType: ZodType, name: string): string {
   const snakeCaseName = name.replace(
     /[A-Z]/g,
     letter => `_${letter.toLowerCase()}`,
   );
+  let transformed: string;
   if (zodType === 'ZodString') {
-    return `${snakeCaseName}_length`;
+    transformed = `${snakeCaseName}_length`;
   } else if (zodType === 'ZodArray') {
-    return `${snakeCaseName}_count`;
+    transformed = `${snakeCaseName}_count`;
   } else {
-    return snakeCaseName;
+    transformed = snakeCaseName;
   }
+  return stripUnderscoreBeforeNumber(transformed);
 }
 
 export function transformArgType(zodType: ZodType): string {

tests/telemetry/flagUtils.test.ts

@@ -106,6 +106,18 @@ describe('computeFlagUsage', () => {
       const usage = computeFlagUsage(args, mockOptions);
       assert.equal(usage.string_flag_present, false);
     });
+
+    it('sanitizes flag names containing underscores before numbers', () => {
+      const mock3pOptions = {
+        experimental3pTool: {
+          type: 'boolean' as const,
+          description: 'A 3p flag',
+        },
+      } as unknown as typeof cliOptions;
+      const args = {experimental3pTool: true};
+      const usage = computeFlagUsage(args, mock3pOptions);
+      assert.equal(usage.experimental3p_tool, true);
+    });
   });
 });
 
@@ -141,4 +153,19 @@ describe('getPossibleFlagMetrics', () => {
       },
     ]);
   });
+
+  it('sanitizes flag names containing underscores before numbers', () => {
+    const mock3pOptions = {
+      experimental3pTool: {
+        type: 'boolean' as const,
+        description: 'A 3p flag',
+      },
+    } as unknown as typeof cliOptions;
+    const metrics = getPossibleFlagMetrics(mock3pOptions);
+
+    assert.deepEqual(metrics, [
+      {name: 'experimental3p_tool_present', flagType: 'boolean'},
+      {name: 'experimental3p_tool', flagType: 'boolean'},
+    ]);
+  });
 });

tests/telemetry/metricsRegistry.test.ts

@@ -82,6 +82,26 @@ describe('metricsRegistry', () => {
       assert.strictEqual(metrics[0].args[0].name, 'arg_enum');
       assert.strictEqual(metrics[0].args[0].argType, 'string');
     });
+
+    it('should sanitize tool names containing underscores before numbers', () => {
+      const mockTool: ToolDefinition = {
+        name: 'list_3p_developer_tools',
+        description: 'test description',
+        annotations: {
+          category: ToolCategory.THIRD_PARTY,
+          readOnlyHint: true,
+        },
+        schema: {},
+        blockedByDialog: false,
+        handler: async () => {
+          // no-op
+        },
+      };
+
+      const metrics = generateToolMetrics([mockTool]);
+      assert.strictEqual(metrics.length, 1);
+      assert.strictEqual(metrics[0].name, 'list3p_developer_tools');
+    });
   });
 
   describe('applyToExistingMetrics', () => {

tests/telemetry/transformation.test.ts

@@ -10,6 +10,8 @@ import {describe, it} from 'node:test';
 import {
   bucketizeLatency,
   sanitizeParams,
+  stripUnderscoreBeforeNumber,
+  transformArgName,
 } from '../../src/telemetry/transformation.js';
 import {zod} from '../../src/third_party/index.js';
 
@@ -133,3 +135,33 @@ describe('sanitizeParams', () => {
     );
   });
 });
+
+describe('stripUnderscoreBeforeNumber', () => {
+  it('removes underscores immediately preceding numbers', () => {
+    assert.strictEqual(
+      stripUnderscoreBeforeNumber('list_3p_developer_tools'),
+      'list3p_developer_tools',
+    );
+    assert.strictEqual(
+      stripUnderscoreBeforeNumber('make_2g_network_request'),
+      'make2g_network_request',
+    );
+    assert.strictEqual(
+      stripUnderscoreBeforeNumber('no_numbers_here'),
+      'no_numbers_here',
+    );
+  });
+});
+
+describe('transformArgName', () => {
+  it('sanitizes argument names containing underscores before numbers', () => {
+    assert.strictEqual(
+      transformArgName('ZodNumber', 'my3pParam'),
+      'my3p_param',
+    );
+    assert.strictEqual(
+      transformArgName('ZodString', 'my3pParam'),
+      'my3p_param_length',
+    );
+  });
+});