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

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)

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 and forwards it to the watchdog process via IPC.

WatchdogClient IPC Layer (src/telemetry/WatchdogClient.ts)

The WatchdogClient acts as a thin wrapper that spawns a detached child process (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)

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. 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:

{
  "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:

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):

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

Customizing the Clearcut endpoint and disabling the PID header:

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), WatchdogClient IPC layer (src/telemetry/WatchdogClient.ts), and ClearcutSender HTTP dispatcher (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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}