Skip to content

Chrome DevTools for coding agents

chore: better organize telemetry utilities (#2057)

yulunz71ccdb0dbfb1
diff --git a/scripts/update_metrics.ts b/scripts/update_metrics.ts
index 6408782f..10c1da42 100644
--- a/scripts/update_metrics.ts
+++ b/scripts/update_metrics.ts
@@ -20,7 +20,7 @@ import {
applyToExistingMetrics,
generateToolMetrics,
type ToolMetric,
-} from '../build/src/telemetry/toolMetricsUtils.js';
+} from '../build/src/telemetry/metricsRegistry.js';
import {createTools} from '../build/src/tools/tools.js';
export function HaveUniqueNames(tools: Array<{name: string}>): boolean {
diff --git a/src/ToolHandler.ts b/src/ToolHandler.ts
index cec1d1d7..680d0c42 100644
--- a/src/ToolHandler.ts
+++ b/src/ToolHandler.ts
@@ -11,7 +11,7 @@ import {McpResponse} from './McpResponse.js';
import type {Mutex} from './Mutex.js';
import {SlimMcpResponse} from './SlimMcpResponse.js';
import {ClearcutLogger} from './telemetry/ClearcutLogger.js';
-import {bucketizeLatency} from './telemetry/metricUtils.js';
+import {bucketizeLatency} from './telemetry/transformation.js';
import type {CallToolResult, zod} from './third_party/index.js';
import type {ToolCategory} from './tools/categories.js';
import {labels, OFF_BY_DEFAULT_CATEGORIES} from './tools/categories.js';
diff --git a/src/telemetry/ClearcutLogger.ts b/src/telemetry/ClearcutLogger.ts
index 3855fe9c..3cf30213 100644
--- a/src/telemetry/ClearcutLogger.ts
+++ b/src/telemetry/ClearcutLogger.ts
@@ -12,6 +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 {
McpClient,
type FlagUsage,
@@ -22,141 +23,6 @@ import {
import {WatchdogClient} from './WatchdogClient.js';
const MS_PER_DAY = 24 * 60 * 60 * 1000;
-export const PARAM_BLOCKLIST = new Set(['uid', 'reqid', 'msgid']);
-
-const SUPPORTED_ZOD_TYPES = [
- 'ZodString',
- 'ZodNumber',
- 'ZodBoolean',
- 'ZodArray',
- 'ZodEnum',
-] as const;
-type ZodType = (typeof SUPPORTED_ZOD_TYPES)[number];
-
-function isZodType(type: string): type is ZodType {
- return SUPPORTED_ZOD_TYPES.includes(type as ZodType);
-}
-
-export function getZodType(zodType: zod.ZodTypeAny): ZodType {
- const def = zodType._def;
- const typeName = def.typeName;
-
- if (
- typeName === 'ZodOptional' ||
- typeName === 'ZodDefault' ||
- typeName === 'ZodNullable'
- ) {
- return getZodType(def.innerType);
- }
- if (typeName === 'ZodEffects') {
- return getZodType(def.schema);
- }
-
- if (isZodType(typeName)) {
- return typeName;
- }
- throw new Error(`Unsupported zod type for tool parameter: ${typeName}`);
-}
-
-type LoggedToolCallArgValue = string | number | boolean;
-
-export function transformArgName(zodType: ZodType, name: string): string {
- const snakeCaseName = name.replace(
- /[A-Z]/g,
- letter => `_${letter.toLowerCase()}`,
- );
- if (zodType === 'ZodString') {
- return `${snakeCaseName}_length`;
- } else if (zodType === 'ZodArray') {
- return `${snakeCaseName}_count`;
- } else {
- return snakeCaseName;
- }
-}
-
-export function transformArgType(zodType: ZodType): string {
- if (zodType === 'ZodString' || zodType === 'ZodArray') {
- return 'number';
- }
- switch (zodType) {
- case 'ZodNumber':
- return 'number';
- case 'ZodBoolean':
- return 'boolean';
- case 'ZodEnum':
- return 'enum';
- default:
- throw new Error(`Unsupported zod type for tool parameter: ${zodType}`);
- }
-}
-
-const BUCKETS = [
- 0, 1, 2, 5, 10, 20, 50, 100, 200, 500, 1000, 2000, 5000, 10000,
-];
-
-function bucketize(value: number): number {
- for (const bucket of BUCKETS) {
- if (bucket >= value) {
- return bucket;
- }
- }
- return BUCKETS[BUCKETS.length - 1];
-}
-
-function transformValue(
- zodType: ZodType,
- value: unknown,
-): LoggedToolCallArgValue {
- if (zodType === 'ZodString') {
- return bucketize((value as string).length);
- } else if (zodType === 'ZodArray') {
- return (value as unknown[]).length;
- } else {
- return value as LoggedToolCallArgValue;
- }
-}
-
-function hasEquivalentType(zodType: ZodType, value: unknown): boolean {
- if (zodType === 'ZodString') {
- return typeof value === 'string';
- } else if (zodType === 'ZodArray') {
- return Array.isArray(value);
- } else if (zodType === 'ZodNumber') {
- return typeof value === 'number';
- } else if (zodType === 'ZodBoolean') {
- return typeof value === 'boolean';
- } else if (zodType === 'ZodEnum') {
- return (
- typeof value === 'string' ||
- typeof value === 'number' ||
- typeof value === 'boolean'
- );
- } else {
- return false;
- }
-}
-
-export function sanitizeParams(
- params: ShapeOutput<zod.ZodRawShape>,
- schema: zod.ZodRawShape,
-): ShapeOutput<zod.ZodRawShape> {
- const transformed: ShapeOutput<zod.ZodRawShape> = {};
- for (const [name, value] of Object.entries(params)) {
- if (PARAM_BLOCKLIST.has(name)) {
- continue;
- }
- const zodType = getZodType(schema[name]);
- if (!hasEquivalentType(zodType, value)) {
- throw new Error(
- `parameter ${name} has type ${zodType} but value ${value} is not of equivalent type`,
- );
- }
- const transformedName = transformArgName(zodType, name);
- const transformedValue = transformValue(zodType, value);
- transformed[transformedName] = transformedValue;
- }
- return transformed;
-}
function detectOsType(): OsType {
switch (process.platform) {
diff --git a/src/telemetry/metricUtils.ts b/src/telemetry/metricUtils.ts
deleted file mode 100644
index 55e834f4..00000000
--- a/src/telemetry/metricUtils.ts
+++ /dev/null
@@ -1,16 +0,0 @@
-/**
- * @license
- * Copyright 2026 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-
-const LATENCY_BUCKETS = [50, 100, 250, 500, 1000, 2500, 5000, 10000];
-
-export function bucketizeLatency(latencyMs: number): number {
- for (const bucket of LATENCY_BUCKETS) {
- if (latencyMs <= bucket) {
- return bucket;
- }
- }
- return LATENCY_BUCKETS[LATENCY_BUCKETS.length - 1];
-}
diff --git a/src/telemetry/toolMetricsUtils.ts b/src/telemetry/metricsRegistry.ts
similarity index 99%
rename from src/telemetry/toolMetricsUtils.ts
rename to src/telemetry/metricsRegistry.ts
index 74f2af42..b8eb32a1 100644
--- a/src/telemetry/toolMetricsUtils.ts
+++ b/src/telemetry/metricsRegistry.ts
@@ -11,7 +11,7 @@ import {
transformArgType,
getZodType,
PARAM_BLOCKLIST,
-} from './ClearcutLogger.js';
+} from './transformation.js';
/**
* Validates that all values in an enum are of the homogeneous primitive type.
diff --git a/src/telemetry/transformation.ts b/src/telemetry/transformation.ts
new file mode 100644
index 00000000..f9cba39f
--- /dev/null
+++ b/src/telemetry/transformation.ts
@@ -0,0 +1,154 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {zod, ShapeOutput} from '../third_party/index.js';
+
+const LATENCY_BUCKETS = [50, 100, 250, 500, 1000, 2500, 5000, 10000];
+
+export function bucketizeLatency(latencyMs: number): number {
+ for (const bucket of LATENCY_BUCKETS) {
+ if (latencyMs <= bucket) {
+ return bucket;
+ }
+ }
+ return LATENCY_BUCKETS[LATENCY_BUCKETS.length - 1];
+}
+
+export const PARAM_BLOCKLIST = new Set(['uid', 'reqid', 'msgid']);
+
+const SUPPORTED_ZOD_TYPES = [
+ 'ZodString',
+ 'ZodNumber',
+ 'ZodBoolean',
+ 'ZodArray',
+ 'ZodEnum',
+] as const;
+type ZodType = (typeof SUPPORTED_ZOD_TYPES)[number];
+
+function isZodType(type: string): type is ZodType {
+ return SUPPORTED_ZOD_TYPES.includes(type as ZodType);
+}
+
+export function getZodType(zodType: zod.ZodTypeAny): ZodType {
+ const def = zodType._def;
+ const typeName = def.typeName;
+
+ if (
+ typeName === 'ZodOptional' ||
+ typeName === 'ZodDefault' ||
+ typeName === 'ZodNullable'
+ ) {
+ return getZodType(def.innerType);
+ }
+ if (typeName === 'ZodEffects') {
+ return getZodType(def.schema);
+ }
+
+ if (isZodType(typeName)) {
+ return typeName;
+ }
+ throw new Error(`Unsupported zod type for tool parameter: ${typeName}`);
+}
+
+type LoggedToolCallArgValue = string | number | boolean;
+
+export function transformArgName(zodType: ZodType, name: string): string {
+ const snakeCaseName = name.replace(
+ /[A-Z]/g,
+ letter => `_${letter.toLowerCase()}`,
+ );
+ if (zodType === 'ZodString') {
+ return `${snakeCaseName}_length`;
+ } else if (zodType === 'ZodArray') {
+ return `${snakeCaseName}_count`;
+ } else {
+ return snakeCaseName;
+ }
+}
+
+export function transformArgType(zodType: ZodType): string {
+ if (zodType === 'ZodString' || zodType === 'ZodArray') {
+ return 'number';
+ }
+ switch (zodType) {
+ case 'ZodNumber':
+ return 'number';
+ case 'ZodBoolean':
+ return 'boolean';
+ case 'ZodEnum':
+ return 'enum';
+ default:
+ throw new Error(`Unsupported zod type for tool parameter: ${zodType}`);
+ }
+}
+
+const BUCKETS = [
+ 0, 1, 2, 5, 10, 20, 50, 100, 200, 500, 1000, 2000, 5000, 10000,
+];
+
+function bucketize(value: number): number {
+ for (const bucket of BUCKETS) {
+ if (bucket >= value) {
+ return bucket;
+ }
+ }
+ return BUCKETS[BUCKETS.length - 1];
+}
+
+function transformValue(
+ zodType: ZodType,
+ value: unknown,
+): LoggedToolCallArgValue {
+ if (zodType === 'ZodString') {
+ return bucketize((value as string).length);
+ } else if (zodType === 'ZodArray') {
+ return (value as unknown[]).length;
+ } else {
+ return value as LoggedToolCallArgValue;
+ }
+}
+
+function hasEquivalentType(zodType: ZodType, value: unknown): boolean {
+ if (zodType === 'ZodString') {
+ return typeof value === 'string';
+ } else if (zodType === 'ZodArray') {
+ return Array.isArray(value);
+ } else if (zodType === 'ZodNumber') {
+ return typeof value === 'number';
+ } else if (zodType === 'ZodBoolean') {
+ return typeof value === 'boolean';
+ } else if (zodType === 'ZodEnum') {
+ return (
+ typeof value === 'string' ||
+ typeof value === 'number' ||
+ typeof value === 'boolean'
+ );
+ } else {
+ return false;
+ }
+}
+
+export function sanitizeParams(
+ params: ShapeOutput<zod.ZodRawShape>,
+ schema: zod.ZodRawShape,
+): ShapeOutput<zod.ZodRawShape> {
+ const transformed: ShapeOutput<zod.ZodRawShape> = {};
+ for (const [name, value] of Object.entries(params)) {
+ if (PARAM_BLOCKLIST.has(name)) {
+ continue;
+ }
+ const zodType = getZodType(schema[name]);
+ if (!hasEquivalentType(zodType, value)) {
+ throw new Error(
+ `parameter ${name} has type ${zodType} but value ${value} is not of equivalent type`,
+ );
+ }
+ const transformedName = transformArgName(zodType, name);
+ const transformedValue = transformValue(zodType, value);
+ transformed[transformedName] = transformedValue;
+ }
+ return transformed;
+}
diff --git a/tests/telemetry/ClearcutLogger.test.ts b/tests/telemetry/ClearcutLogger.test.ts
index cab0f447..c19567d9 100644
--- a/tests/telemetry/ClearcutLogger.test.ts
+++ b/tests/telemetry/ClearcutLogger.test.ts
@@ -10,10 +10,7 @@ import {describe, it, afterEach, beforeEach} from 'node:test';
import sinon from 'sinon';
import {DAEMON_CLIENT_NAME} from '../../src/daemon/utils.js';
-import {
- ClearcutLogger,
- sanitizeParams,
-} from '../../src/telemetry/ClearcutLogger.js';
+import {ClearcutLogger} from '../../src/telemetry/ClearcutLogger.js';
import {ErrorCode} from '../../src/telemetry/errors.js';
import type {Persistence} from '../../src/telemetry/persistence.js';
import {FilePersistence} from '../../src/telemetry/persistence.js';
@@ -260,95 +257,6 @@ describe('ClearcutLogger', () => {
});
});
- describe('sanitizeParams', () => {
- it('filters out uid and transforms strings and arrays', () => {
- const schema = {
- uid: zod.string(),
- myString: zod.string(),
- myArray: zod.array(zod.string()),
- myNumber: zod.number(),
- myBool: zod.boolean(),
- myEnum: zod.enum(['a', 'b']),
- };
-
- const params = {
- uid: 'sensitive',
- myString: 'hello',
- myArray: ['one', 'two'],
- myNumber: 42,
- myBool: true,
- myEnum: 'a' as const,
- };
-
- const sanitized = sanitizeParams(params, schema);
-
- assert.deepStrictEqual(sanitized, {
- my_string_length: 5,
- my_array_count: 2,
- my_number: 42,
- my_bool: true,
- my_enum: 'a',
- });
- });
-
- it('bucketizes string lengths correctly', () => {
- const schema = {
- str0: zod.string(),
- str1: zod.string(),
- str3: zod.string(),
- str5: zod.string(),
- str10000: zod.string(),
- str10001: zod.string(),
- };
-
- const params = {
- str0: '',
- str1: 'a',
- str3: 'abc',
- str5: 'abcde',
- str10000: 'a'.repeat(10000),
- str10001: 'a'.repeat(10001),
- };
-
- const sanitized = sanitizeParams(params, schema);
-
- assert.strictEqual(sanitized.str0_length, 0);
- assert.strictEqual(sanitized.str1_length, 1);
- assert.strictEqual(sanitized.str3_length, 5); // snaps to 5
- assert.strictEqual(sanitized.str5_length, 5);
- assert.strictEqual(sanitized.str10000_length, 10000);
- assert.strictEqual(sanitized.str10001_length, 10000); // snaps to 10000
- });
-
- it('throws error for unsupported types', () => {
- const schema = {
- myObj: zod.object({foo: zod.string()}),
- };
- const params = {
- myObj: {foo: 'bar'},
- };
-
- assert.throws(
- () => sanitizeParams(params, schema),
- /Unsupported zod type for tool parameter: ZodObject/,
- );
- });
-
- it('throws error when value is not of equivalent type', () => {
- const schema = {
- myString: zod.string(),
- };
- const params = {
- myString: 123,
- };
-
- assert.throws(
- () => sanitizeParams(params, schema),
- /parameter myString has type ZodString but value 123 is not of equivalent type/,
- );
- });
- });
-
describe('Singleton', () => {
it('returns undefined if not initialized', () => {
assert.strictEqual(ClearcutLogger.get(), undefined);
diff --git a/tests/telemetry/metricUtils.test.ts b/tests/telemetry/metricUtils.test.ts
deleted file mode 100644
index 36bda868..00000000
--- a/tests/telemetry/metricUtils.test.ts
+++ /dev/null
@@ -1,42 +0,0 @@
-/**
- * @license
- * Copyright 2026 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-
-import assert from 'node:assert';
-import {describe, it} from 'node:test';
-
-import {bucketizeLatency} from '../../src/telemetry/metricUtils.js';
-
-describe('bucketizeLatency', () => {
- it('should bucketize values correctly', () => {
- assert.strictEqual(bucketizeLatency(0), 50);
- assert.strictEqual(bucketizeLatency(25), 50);
- assert.strictEqual(bucketizeLatency(50), 50);
-
- assert.strictEqual(bucketizeLatency(51), 100);
- assert.strictEqual(bucketizeLatency(100), 100);
-
- assert.strictEqual(bucketizeLatency(101), 250);
- assert.strictEqual(bucketizeLatency(250), 250);
-
- assert.strictEqual(bucketizeLatency(499), 500);
- assert.strictEqual(bucketizeLatency(500), 500);
-
- assert.strictEqual(bucketizeLatency(900), 1000);
- assert.strictEqual(bucketizeLatency(1000), 1000);
-
- assert.strictEqual(bucketizeLatency(2000), 2500);
- assert.strictEqual(bucketizeLatency(2500), 2500);
-
- assert.strictEqual(bucketizeLatency(4000), 5000);
- assert.strictEqual(bucketizeLatency(5000), 5000);
-
- assert.strictEqual(bucketizeLatency(6000), 10000);
- assert.strictEqual(bucketizeLatency(10000), 10000);
-
- assert.strictEqual(bucketizeLatency(10001), 10000);
- assert.strictEqual(bucketizeLatency(99999), 10000);
- });
-});
diff --git a/tests/telemetry/toolMetricsUtils.test.ts b/tests/telemetry/metricsRegistry.test.ts
similarity index 98%
rename from tests/telemetry/toolMetricsUtils.test.ts
rename to tests/telemetry/metricsRegistry.test.ts
index 9033bee1..37679477 100644
--- a/tests/telemetry/toolMetricsUtils.test.ts
+++ b/tests/telemetry/metricsRegistry.test.ts
@@ -11,12 +11,12 @@ import {
applyToExistingMetrics,
generateToolMetrics,
validateEnumHomogeneity,
-} from '../../src/telemetry/toolMetricsUtils.js';
+} from '../../src/telemetry/metricsRegistry.js';
import {zod} from '../../src/third_party/index.js';
import {ToolCategory} from '../../src/tools/categories.js';
import type {ToolDefinition} from '../../src/tools/ToolDefinition.js';
-describe('toolMetricsUtils', () => {
+describe('metricsRegistry', () => {
describe('validateEnumHomogeneity', () => {
it('should return the primitive type of a homogeneous enum', () => {
const result = validateEnumHomogeneity(['a', 'b', 'c']);
diff --git a/tests/telemetry/transformation.test.ts b/tests/telemetry/transformation.test.ts
new file mode 100644
index 00000000..0d829d2f
--- /dev/null
+++ b/tests/telemetry/transformation.test.ts
@@ -0,0 +1,135 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import assert from 'node:assert';
+import {describe, it} from 'node:test';
+
+import {
+ bucketizeLatency,
+ sanitizeParams,
+} from '../../src/telemetry/transformation.js';
+import {zod} from '../../src/third_party/index.js';
+
+describe('bucketizeLatency', () => {
+ it('should bucketize values correctly', () => {
+ assert.strictEqual(bucketizeLatency(0), 50);
+ assert.strictEqual(bucketizeLatency(25), 50);
+ assert.strictEqual(bucketizeLatency(50), 50);
+
+ assert.strictEqual(bucketizeLatency(51), 100);
+ assert.strictEqual(bucketizeLatency(100), 100);
+
+ assert.strictEqual(bucketizeLatency(101), 250);
+ assert.strictEqual(bucketizeLatency(250), 250);
+
+ assert.strictEqual(bucketizeLatency(499), 500);
+ assert.strictEqual(bucketizeLatency(500), 500);
+
+ assert.strictEqual(bucketizeLatency(900), 1000);
+ assert.strictEqual(bucketizeLatency(1000), 1000);
+
+ assert.strictEqual(bucketizeLatency(2000), 2500);
+ assert.strictEqual(bucketizeLatency(2500), 2500);
+
+ assert.strictEqual(bucketizeLatency(4000), 5000);
+ assert.strictEqual(bucketizeLatency(5000), 5000);
+
+ assert.strictEqual(bucketizeLatency(6000), 10000);
+ assert.strictEqual(bucketizeLatency(10000), 10000);
+
+ assert.strictEqual(bucketizeLatency(10001), 10000);
+ assert.strictEqual(bucketizeLatency(99999), 10000);
+ });
+});
+
+describe('sanitizeParams', () => {
+ it('filters out uid and transforms strings and arrays', () => {
+ const schema = {
+ uid: zod.string(),
+ myString: zod.string(),
+ myArray: zod.array(zod.string()),
+ myNumber: zod.number(),
+ myBool: zod.boolean(),
+ myEnum: zod.enum(['a', 'b']),
+ };
+
+ const params = {
+ uid: 'sensitive',
+ myString: 'hello',
+ myArray: ['one', 'two'],
+ myNumber: 42,
+ myBool: true,
+ myEnum: 'a' as const,
+ };
+
+ const sanitized = sanitizeParams(params, schema);
+
+ assert.deepStrictEqual(sanitized, {
+ my_string_length: 5,
+ my_array_count: 2,
+ my_number: 42,
+ my_bool: true,
+ my_enum: 'a',
+ });
+ });
+
+ it('bucketizes string lengths correctly', () => {
+ const schema = {
+ str0: zod.string(),
+ str1: zod.string(),
+ str3: zod.string(),
+ str5: zod.string(),
+ str10000: zod.string(),
+ str10001: zod.string(),
+ };
+
+ const params = {
+ str0: '',
+ str1: 'a',
+ str3: 'abc',
+ str5: 'abcde',
+ str10000: 'a'.repeat(10000),
+ str10001: 'a'.repeat(10001),
+ };
+
+ const sanitized = sanitizeParams(params, schema);
+
+ assert.strictEqual(sanitized.str0_length, 0);
+ assert.strictEqual(sanitized.str1_length, 1);
+ assert.strictEqual(sanitized.str3_length, 5); // snaps to 5
+ assert.strictEqual(sanitized.str5_length, 5);
+ assert.strictEqual(sanitized.str10000_length, 10000);
+ assert.strictEqual(sanitized.str10001_length, 10000); // snaps to 10000
+ });
+
+ it('throws error for unsupported types', () => {
+ const schema = {
+ myObj: zod.object({foo: zod.string()}),
+ };
+ const params = {
+ myObj: {foo: 'bar'},
+ };
+
+ assert.throws(
+ () => sanitizeParams(params, schema),
+ /Unsupported zod type for tool parameter: ZodObject/,
+ );
+ });
+
+ it('throws error when value is not of equivalent type', () => {
+ const schema = {
+ myString: zod.string(),
+ };
+ const params = {
+ myString: 123,
+ };
+
+ assert.throws(
+ () => sanitizeParams(params, schema),
+ /parameter myString has type ZodString but value 123 is not of equivalent type/,
+ );
+ });
+});