# How the ClearcutLogger Telemetry System Works in chrome-devtools-mcp and What Data It Collects

> Learn how the ClearcutLogger telemetry system in chrome-devtools-mcp works. Discover the data collected across its API, IPC, and HTTP layers for tool usage and active metrics.

- Repository: [ChromeDevTools/chrome-devtools-mcp](https://github.com/chromedevtools/chrome-devtools-mcp)
- Tags: internals
- Published: 2026-02-16

---

**The ClearcutLogger telemetry system in chrome-devtools-mcp captures usage events through a three-layer pipeline—comprising the ClearcutLogger API, WatchdogClient IPC layer, and ClearcutSender HTTP dispatcher—collecting tool invocations, server lifecycle events, and daily active metrics while enforcing rate limits, session rotation, and reliable delivery.**

The chrome-devtools-mcp repository implements a comprehensive telemetry pipeline to monitor extension usage and performance. At the core of this system lies the **ClearcutLogger telemetry system**, which serializes events into protobuf-style payloads and transmits them to Google's Clearcut logging service. Understanding this architecture reveals how the extension balances observability with user privacy and system reliability.

## Three-Layer Architecture of the ClearcutLogger Telemetry System

The system consists of three tightly-coupled components that isolate network operations from the main MCP process.

### ClearcutLogger API Layer ([`src/telemetry/ClearcutLogger.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/telemetry/ClearcutLogger.ts))

The `ClearcutLogger` class serves as the primary interface for the rest of the MCP codebase. It initializes a `WatchdogClient` and a persistence layer, then exposes high-level methods such as `logToolInvocation`, `logServerStart`, and `logDailyActiveIfNeeded`. Each method constructs a protobuf-style payload defined in [`src/telemetry/types.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/telemetry/types.ts) and forwards it to the watchdog process via IPC.

### WatchdogClient IPC Layer ([`src/telemetry/WatchdogClient.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/telemetry/WatchdogClient.ts))

The `WatchdogClient` acts as a thin wrapper that spawns a detached child process ([`src/telemetry/watchdog/main.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/telemetry/watchdog/main.ts)). It translates high-level payloads into JSON lines and writes them to the child's stdin, ensuring the main process remains non-blocking even during network transmission.

### ClearcutSender Dispatch Layer ([`src/telemetry/watchdog/ClearcutSender.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/telemetry/watchdog/ClearcutSender.ts))

Running inside the watchdog process, `ClearcutSender` manages the actual network transmission. It buffers events in memory, rotates a session ID every 24 hours, throttles transmission according to Clearcut's rate-limit hints, and issues HTTPS `POST` requests to the endpoint `https://play.googleapis.com/log?format=json_proto`.

## Data Flow and Event Lifecycle

The telemetry data flows through the system as follows:

```

MCP code → ClearcutLogger → WatchdogClient (IPC) → ClearcutSender (buffer → HTTP POST) → Clearcut service

```

When the MCP server invokes `logToolInvocation`, the event immediately enters the `ClearcutSender` buffer. The sender accumulates events until either the buffer reaches capacity, the periodic flush timer triggers (default 15 minutes), or the process shuts down.

## What Data the ClearcutLogger Telemetry System Collects

All events conform to the protobuf interface `ChromeDevToolsMcpExtension` defined in [`src/telemetry/types.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/telemetry/types.ts). The system captures four explicit event types enriched with automatic metadata.

### Tool Invocation Events

The `tool_invocation` event records every CLI tool execution via `logToolInvocation`. The payload includes:
- `tool_name`: Identifier of the invoked tool
- `success`: Boolean indicating execution success
- `latency_ms`: Duration of the operation in milliseconds

### Server Lifecycle Events

Two events track the MCP server's operational state:
- `server_start`: Emitted via `logServerStart`, capturing `flag_usage` (a key-value map of command-line flags used during initialization)
- `server_shutdown`: Emitted when the parent process exits, signaling the end of the session with an empty payload

### Daily Active Metrics

The `daily_active` event, triggered by `logDailyActiveIfNeeded`, records user engagement through the `days_since_last_active` field. This metric calculates the interval since the last recorded activity, enabling accurate DAU (Daily Active User) tracking without exposing precise timestamps.

### Automatic Enrichment Fields

Before transmission, `ClearcutSender` appends three metadata fields to every event:
- `os_type`: Host operating system (mapped from the `OsType` enum)
- `app_version`: MCP version supplied at startup
- `session_id`: Random UUID that rotates every 24 hours to group events into logical sessions

The final JSON payload sent to the Clearcut endpoint follows this structure:

```json
{
  "log_source": 2839,
  "request_time_ms": "1708000000000",
  "client_info": { "client_type": 47 },
  "log_event": [
    {
      "event_time_ms": "1707999999000",
      "source_extension_json": "{\"tool_invocation\":{\"tool_name\":\"devtools\",\"success\":true,\"latency_ms\":123},\"os_type\":3,\"app_version\":\"1.0.0\",\"session_id\":\"a1b2c3\"}"
    }
  ]
}

```

## Reliability and Transmission Guarantees

The ClearcutLogger telemetry system implements several mechanisms to ensure reliable delivery without blocking the main MCP process.

### Buffering and Memory Management

Events accumulate in an in-memory buffer within `ClearcutSender` up to `MAX_BUFFER_SIZE` (1000 events). When the buffer reaches capacity, the oldest events are dropped to prevent unbounded memory growth.

### Flush Scheduling and Shutdown Handling

A periodic timer triggers flushes every 15 minutes by default. Additionally, the system forces a final flush when the parent process shuts down, ensuring the `server_shutdown` event and any pending buffered events reach the Clearcut service.

### Rate Limiting and Retry Logic

The sender respects Clearcut's rate-limiting hints via the `next_request_wait_millis` response field, defaulting to a minimum 30-second backoff. Transient errors (HTTP 429 or 5xx status codes) trigger automatic retries, while permanent errors (other 4xx codes) result in batch discard to prevent infinite loops.

### Session Rotation

To maintain manageable session sizes, `ClearcutSender` generates a new random UUID for `session_id` every 24 hours. This rotation groups events into logical daily sessions while preserving user privacy through non-persistent identifiers.

## Implementation Examples

The following snippets demonstrate how the MCP codebase interacts with the ClearcutLogger telemetry system.

Logging a tool invocation from MCP core:

```typescript
import {ClearcutLogger} from './telemetry/ClearcutLogger.js';

const logger = new ClearcutLogger({
  appVersion: '1.2.3',
  clearcutEndpoint: process.env.CLEARCUT_ENDPOINT, // optional override
});

await logger.logToolInvocation({
  toolName: 'devtools',
  success: true,
  latencyMs: 215,
});

```

Sending a daily-active ping (automatically called on startup):

```typescript
await logger.logDailyActiveIfNeeded(); // decides based on persisted state

```

Customizing the Clearcut endpoint and disabling the PID header:

```typescript
const logger = new ClearcutLogger({
  appVersion: '1.2.3',
  clearcutEndpoint: 'https://example.com/custom-log',
  clearcutIncludePidHeader: false,
});

```

These examples illustrate the only public surface; buffering, retries, and shutdown handling remain encapsulated within the watchdog process and `ClearcutSender`.

## Summary

- The **ClearcutLogger telemetry system** in chrome-devtools-mcp uses a three-layer architecture: the `ClearcutLogger` API ([`src/telemetry/ClearcutLogger.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/telemetry/ClearcutLogger.ts)), `WatchdogClient` IPC layer ([`src/telemetry/WatchdogClient.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/telemetry/WatchdogClient.ts)), and `ClearcutSender` HTTP dispatcher ([`src/telemetry/watchdog/ClearcutSender.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/telemetry/watchdog/ClearcutSender.ts)).
- **Data collected** includes tool invocations (name, success, latency), server lifecycle events (startup flags, shutdown signals), and daily active metrics, enriched with OS type, app version, and rotating 24-hour session IDs.
- **Reliability mechanisms** include in-memory buffering (1000 events), 15-minute flush intervals, rate-limit respect with 30-second minimum backoff, and 24-hour session rotation.
- **Implementation** requires only the `ClearcutLogger` class, with all network and retry logic isolated in the detached watchdog process to ensure non-blocking operation.

## Frequently Asked Questions

### What is the ClearcutLogger telemetry system in chrome-devtools-mcp?

The ClearcutLogger telemetry system is the internal observability pipeline that captures usage metrics from the chrome-devtools-mcp extension. It serializes events into protobuf-style payloads and transmits them to Google's Clearcut logging service via HTTPS, enabling the team to monitor tool performance and adoption without blocking the main MCP server process.

### What specific data does the ClearcutLogger collect from users?

The system collects four primary event types: tool invocations (including `tool_name`, `success` boolean, and `latency_ms`), server startup configurations (`flag_usage` map), server shutdown signals, and daily active user metrics (`days_since_last_active`). Each event is automatically enriched with the operating system type, MCP `app_version`, and a rotating 24-hour `session_id` that preserves privacy while grouping related events.

### How does the ClearcutLogger handle network failures or rate limiting?

The `ClearcutSender` component implements a robust retry mechanism that respects Clearcut's rate-limiting hints via the `next_request_wait_millis` response field, defaulting to a minimum 30-second backoff. Transient errors (HTTP 429 or 5xx status codes) trigger automatic retries, while permanent errors (other 4xx codes) result in batch discard to prevent infinite loops. An in-memory buffer stores up to 1000 events, with forced flushes every 15 minutes and on process shutdown.

### Can developers customize or disable the ClearcutLogger telemetry system?

Developers can customize the telemetry endpoint by passing a `clearcutEndpoint` option to the `ClearcutLogger` constructor, allowing redirection to custom logging infrastructure. They can also disable the PID header transmission via the `clearcutIncludePidHeader` boolean flag. However, the buffering, retry logic, and session management remain encapsulated within the watchdog process and cannot be modified without changing the source code in [`src/telemetry/watchdog/ClearcutSender.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/telemetry/watchdog/ClearcutSender.ts).