Chrome DevTools for coding agents
chore: better organize telemetry utilities (#2057)
yulunz71ccdb0dbfb1
diff --git a/scripts/update_metrics.ts b/scripts/update_metrics.tsindex 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.tsindex 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.tsindex 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.tsdeleted file mode 100644index 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.tssimilarity index 99%rename from src/telemetry/toolMetricsUtils.tsrename to src/telemetry/metricsRegistry.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsdeleted file mode 100644index 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.tssimilarity index 98%rename from tests/telemetry/toolMetricsUtils.test.tsrename to tests/telemetry/metricsRegistry.test.tsindex 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.tsnew file mode 100644index 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/,+ );+ });+});