## What
`generateToolMetrics` reads an enum parameter's values by unwrapping
**at most
one** `optional` wrapper:
```ts
if (schema._def.values?.length > 0) {
values = schema._def.values;
} else {
values = schema._def.innerType._def.values; // only one level
}
```
An enum parameter wrapped in `.default().optional()` (or any nested
`optional`/`default`/`nullable` combination) therefore falls through to
`schema._def.innerType._def.values === undefined`, and `npm run
update-metrics`
(run as part of `npm run gen`) crashes:
```
TypeError: Cannot read properties of undefined (reading '0')
at validateEnumHomogeneity (build/src/telemetry/metricsRegistry.js:12)
at generateToolMetrics (build/src/telemetry/metricsRegistry.js:59)
```
## Why it matters
`npm run gen` is required whenever a tool is added or changed (per
`CONTRIBUTING.md`). Declaring an enum parameter with a default — a
natural,
documented zod pattern — silently breaks docs/metrics generation.
## Fix
Add `getEnumValues()` in `transformation.ts` that recursively unwraps
`optional` / `default` / `nullable` / `effects` wrappers, mirroring the
existing
`getZodType()`, and use it in `generateToolMetrics`. Behavior is
unchanged for
the existing bare-enum and single-`optional` cases.
## Tests
- `getEnumValues` unit tests: bare enum, `optional`, `default`, both
orders of
`default`+`optional`, and throws for a non-enum type.
- `generateToolMetrics` regression test with
`zod.enum(...).default(...).optional()`.
- `npm run typecheck`, the telemetry tests, and `npm run check-format`
pass.
---
First-time contributor here — happy to sign the CLA.
Underscore followed by numbers is not encouraged in the proto style
guide. See "Underscores in Identifiers" in
https://protobuf.dev/programming-guides/style/.
This recently became an issue because we have `list_3p_developer_tools`
and `execute_3p_developer_tool` which would have been dis-allowed. This
change replaces them with `list3p_developer_tools` and
`execute3p_developer_tool` respectively, as suggested by the style
guide.
This only affects the logged version. The tool name is still the
existing one.
This transformation is also applied to other similar places, like flag
names, tool name in error logging, and tool args.
The `tool_name_metrics.json` was manually updated because we never
landed the server side change because it was disallowed by proto style
check.
There is no behavior change.
This groups utilities into two modules:
- `transformation.ts`: for any logic related to mutating / filtering of
the names, values of telemetry entries.
- `metricsRegistry.ts`: for any logic that related to the maintenance of
metrics.json files.
This adds logging to the read & write operations to the telemetry state
file. In particular,
- for read, no error is logged if the state file doesn't exist, which is
expected to happen when the user is new. An error is logged otherwise
(e.g. file format error, errors when reading an existing file like
permission issue).
- for write, any error in the path will be logged.
This commit also puts the instantiation of the `Persistence` object out
of the `ClearcutLogger` object to avoid circular dependency.
We will add a error logging method to ClearcutLogger in a follow-up PR.
Since the error can happen anywhere in the stack, the logger instance
has to be readily available (i.e. w/o passing the logger instance
everywhere). This commit registers the instantiated logger as a global
singleton, and makes it possible to retrieve it by a static method
(`ClearcutLogger.get()`) wherever we need it.
This is the second most highly touched metric areas - so let's automate
this portion first. The approach is similar to what we have for tool
call args. The append-only logic will be added in the follow-up PR:
#1882
This fixes the casing of the tool call params. We don't need any server
side fix since they are already converted to snake case in the proto
definition. This is needed nevertheless since the sanitizeParams()
function will be called when we log the params (see the next PR: #1863
1863).
With this change new tools are added to the very back of the json file.
Any removed tools will receive a isDeprecated flag in the existing
entry. And the same with tool arguments.
This adds a script that generates a json file that summarizes all tool
calls and arguments for each.
- The arguments run through the blocklist filtering so arguments
containing high entropy ids are filtered out (e.g. "uid", "msgid" etc).
- It uses existing functions from clearcut logger module to transform
the arg name and value (i.e. take the length of the string, take the
size of the array, and rename the string to be "string_length", and
array "array_count" etc).
- These functions from the clearcut logger module will be later used to
sanitize the params as we start to log them.
This doesn't include the append only / deprecation logic just yet (i.e.
it's doesn't handle the case when new tools are added / removed, or
arguments of the existing tools are modified). This will be added in
following PRs.
The parent PR is #1250.
This adds functions to sanitize the tool call parameters. They are not
called as of now since we don't have server side changes landed yet to
support these.
The changes in the PR intercepts the name of the MCP client right after
server initialization, coverts it into one of the existing enum values,
and append it with the telemetry request.
Note that the client name is unset if there is no client connected yet.
This means the server_start event won't have a client name.
Tested with gemini-cli.
---------
Co-authored-by: Yulun Zeng <yulunz@chromium.org>
- `chrome-devtools-mcp.js` is the `npx chrome-devtools-mcp`
- `chrome-devtools.js` is the new CLI
- `-cli-options.js` is the corresponding options
- all these files are in the bin folder to indicate they are executable
This PR completes the telemetry system by implementing the transport
layer for `ClearcutSender`. It enables actual HTTP communication with
the Clearcut backend, handling event batching, rate limiting, and
reliable delivery, including robust shutdown handling.
**Key Changes:**
* **HTTP Transport**: Implemented `fetch`-based transport sending `POST`
requests to the Clearcut HTTP server.
* **Event Batching**: Events are now buffered and flushed periodically
(default: 15 minutes) or on shutdown.
* **Reliability & Rate Limiting**:
* **Server-Side Backoff**: Respects `next_request_wait_millis` from
server responses to handle rate limiting dynamically.
* **Transient Error Retries**: Failed requests (5xx, 429) result in
events being requeued for the next flush.
* **Request Timeouts**: Enforced 30s timeout on requests to prevent
hanging processes.
* **Session Rotation**: Automatically rotates session IDs every 24
hours.
* **Safety & Stability**:
* **Buffer Overflow Protection**: Caps the buffer at 1000 events to
prevent memory leaks, dropping oldest events if necessary.
* **Optimistic Removal**: Prevents race conditions and duplicate events
during shutdown by optimistically removing events from the buffer before
sending.
* **Testing Improvements**:
* **E2E Robustness**: Updated E2E tests to use a mock web server instead
of relying on the logger to log specific lines.
**Implementation Roadmap:**
These changes finalize the planned telemetry architecture:
1. **CLI & Opt-out Mechanism
([Merged](https://github.com/ChromeDevTools/chrome-devtools-mcp/pull/757))**
2. **Logger Scaffolding & Integration
([Merged](https://github.com/ChromeDevTools/chrome-devtools-mcp/pull/758))**
3. **Persistence Layer
([Merged](https://github.com/ChromeDevTools/chrome-devtools-mcp/pull/766))**
4. **Watchdog Process Architecture
([Merged](https://github.com/ChromeDevTools/chrome-devtools-mcp/pull/769))**
5. **Transport, Batching & Retries (This PR):**
* Finalized `ClearcutSender` with HTTP transport, batching, and
server-directed backoff strategies.
---------
Co-authored-by: Alex Rudenko <alexrudenko@chromium.org>
This PR implements the watchdog process architecture for the telemetry
system. It moves the `ClearcutSender` execution to a dedicated child
process, ensuring that events—especially shutdown events—are reliably
transmitted even if the main server process terminates abruptly.
Added an e2e test that runs the server, checks the log file and confirms
the telemetry logs exist and that the watchdog process is correctly
killed after sending the shutdown event once the main process is killed.
**Implementation Roadmap:**
This is the fourth in a series of PRs designed to implement the
telemetry system:
1. **CLI & Opt-out Mechanism
([Merged](https://github.com/ChromeDevTools/chrome-devtools-mcp/pull/757)):**
* Added `--usage-statistics` flag and transparency logging.
2. **Logger Scaffolding & Integration
([Merged](https://github.com/ChromeDevTools/chrome-devtools-mcp/pull/758)):**
* **`ClearcutLogger`**: Implemented the main logging entry point.
* **One-way Data Flow**: Integrated `logToolInvocation` and
`logServerStart` hooks into `main.ts` to capture events.
* **`ClearcutSender`**: Introduced a transport abstraction.
* **Type Definitions**: Added TypeScript definitions for the telemetry
Protocol Buffer messages.
3. **Persistence Layer
([Merged](https://github.com/ChromeDevTools/chrome-devtools-mcp/pull/766)):**
* **`FilePersistence`**: Implemented a local file-based state manager to
persist the `lastActive` timestamp.
* **Daily Active Logic**: Integrated persistence into `ClearcutLogger`
to automatically detect and log `daily_active` events (with
`days_since_last_active` calculation) via `logDailyActiveIfNeeded`.
4. **Watchdog Process Architecture (This PR):**
* **`WatchdogClient`**: Added a client-side wrapper to spawn and
communicate with the watchdog process via `stdin`.
* **`watchdog/main.ts`**: Created the entry point for the watchdog
process. It listens for IPC messages and uses `ClearcutSender` to
transmit events.
* **Reliable Shutdown**: The watchdog monitors the parent process and
guarantees a `shutdown` event is sent when the parent exits or crashes
(detecting `stdin` closure).
* **Refactoring**: Moved `ClearcutSender` to the `watchdog` directory
and updated `ClearcutLogger` to delegate event sending to the
`WatchdogClient`.
5. **Transport, Batching & Retries (Next):**
* Finalize `ClearcutSender` with actual HTTP transport logic, including
event batching and exponential backoff retries.
This PR implements the persistence layer for the telemetry system. It
introduces `FilePersistence` for local state management and integrates
it with `ClearcutLogger` to support "Daily Active" metric. I have
decided not to send `first_time_installation` events since we can deduce
them from `daily active` events where the `days_since_last_active` will
be `-1` for that case.
**Implementation Roadmap:**
This is the third in a series of PRs designed to implement the telemetry
system:
1. **CLI & Opt-out Mechanism
([Merged](https://github.com/ChromeDevTools/chrome-devtools-mcp/pull/757)):**
* Added `--usage-statistics` flag and transparency logging.
2. **Logger Scaffolding & Integration
([Merged](https://github.com/ChromeDevTools/chrome-devtools-mcp/pull/758)):**
* **`ClearcutLogger`**: Implemented the main logging entry point.
* **One-way Data Flow**: Integrated `logToolInvocation` and
`logServerStart` hooks into `main.ts` to capture events.
* **`ClearcutSender`**: Introduced a transport abstraction.
* **Type Definitions**: Added TypeScript definitions for the telemetry
Protocol Buffer messages.
3. **Persistence Layer (This PR):**
* **`FilePersistence`**: Implemented a local file-based state manager to
persist the `lastActive` timestamp.
* **Daily Active Logic**: Integrated persistence into `ClearcutLogger`
to automatically detect and log `daily_active` events (with
`days_since_last_active` calculation) via `logDailyActiveIfNeeded`.
4. **Watchdog Process Architecture (Next):**
* Move `ClearcutSender` execution to a dedicated watchdog process to
ensure reliable event transmission even during abrupt server shutdowns.
5. **Transport, Batching & Retries (Next):**
* Finalize `ClearcutSender` with actual HTTP transport logic, including
event batching and exponential backoff retries.
This PR implements the core logging infrastructure for the telemetry
system. It introduces the `ClearcutLogger` class, integrates it into the
server lifecycle events, and establishes the `ClearcutSender`
abstraction.
**Implementation Roadmap:**
This is the second in a series of PRs designed to implement a robust,
privacy-conscious telemetry system:
1. **CLI & Opt-out Mechanism
([Merged](https://github.com/ChromeDevTools/chrome-devtools-mcp/pull/757)):**
* Added `--usage-statistics` flag and transparency logging.
2. **Logger Scaffolding & Integration (This PR):**
* **`ClearcutLogger`**: Implemented the main logging entry point.
* **One-way Data Flow**: Integrated `logToolInvocation` and
`logServerStart` hooks into `main.ts` to capture events.
* **`ClearcutSender`**: Introduced a transport abstraction (currently a
dummy implementation) that will later handle HTTP requests, batching,
and retries.
* **Type Definitions**: Added TypeScript definitions for the telemetry
Protocol Buffer messages.
3. **Persistence Layer (Next):**
* Implement local state management to reliably track "First Time
Installation" and "Daily Active" metrics.
4. **Watchdog Process Architecture (Next):**
* Move `ClearcutSender` execution to a dedicated watchdog process to
ensure reliable event transmission even during abrupt server shutdowns.
5. **Transport, Batching & Retries (Next):**
* Finalize `ClearcutSender` with actual HTTP transport logic, including
event batching and exponential backoff retries.
Liohtml