Chrome DevTools for coding agents
chore: implement telemetry persistence and daily active logging (#769)
Ergün Erdoğmuşa3de5e4227a8
diff --git a/src/main.ts b/src/main.tsindex 2e65903b..a4976c0f 100644--- a/src/main.ts+++ b/src/main.ts@@ -228,4 +228,5 @@ const transport = new StdioServerTransport();await server.connect(transport);logger('Chrome DevTools MCP Server connected');logDisclaimers();+void clearcutLogger?.logDailyActiveIfNeeded();void clearcutLogger?.logServerStart(computeFlagUsage(args, cliOptions));diff --git a/src/telemetry/clearcut-logger.ts b/src/telemetry/clearcut-logger.tsindex 17b53420..8b86de21 100644--- a/src/telemetry/clearcut-logger.ts+++ b/src/telemetry/clearcut-logger.ts@@ -4,14 +4,22 @@* SPDX-License-Identifier: Apache-2.0*/+import {logger} from '../logger.js';+import {ClearcutSender} from './clearcut-sender.js';+import type {LocalState, Persistence} from './persistence.js';+import {FilePersistence} from './persistence.js';import type {FlagUsage} from './types.js';+const MS_PER_DAY = 24 * 60 * 60 * 1000;+export class ClearcutLogger {+ #persistence: Persistence;#sender: ClearcutSender;- constructor(sender?: ClearcutSender) {- this.#sender = sender ?? new ClearcutSender();+ constructor(options?: {persistence?: Persistence; sender?: ClearcutSender}) {+ this.#persistence = options?.persistence ?? new FilePersistence();+ this.#sender = options?.sender ?? new ClearcutSender();}async logToolInvocation(args: {@@ -35,4 +43,48 @@ export class ClearcutLogger {},});}++ async logDailyActiveIfNeeded(): Promise<void> {+ try {+ const state = await this.#persistence.loadState();++ if (this.#shouldLogDailyActive(state)) {+ let daysSince = -1;+ if (state.lastActive) {+ const lastActiveDate = new Date(state.lastActive);+ const now = new Date();+ const diffTime = Math.abs(now.getTime() - lastActiveDate.getTime());+ daysSince = Math.ceil(diffTime / MS_PER_DAY);+ }++ await this.#sender.send({+ daily_active: {+ days_since_last_active: daysSince,+ },+ });++ // Update persistence+ state.lastActive = new Date().toISOString();+ await this.#persistence.saveState(state);+ }+ } catch (err) {+ logger('Error in logDailyActiveIfNeeded:', err);+ }+ }++ #shouldLogDailyActive(state: LocalState): boolean {+ if (!state.lastActive) {+ return true;+ }+ const lastActiveDate = new Date(state.lastActive);+ const now = new Date();++ // Compare UTC dates+ const isSameDay =+ lastActiveDate.getUTCFullYear() === now.getUTCFullYear() &&+ lastActiveDate.getUTCMonth() === now.getUTCMonth() &&+ lastActiveDate.getUTCDate() === now.getUTCDate();++ return !isSameDay;+ }}diff --git a/src/telemetry/persistence.ts b/src/telemetry/persistence.tsnew file mode 100644index 00000000..5b133649--- /dev/null+++ b/src/telemetry/persistence.ts@@ -0,0 +1,74 @@+/**+ * @license+ * Copyright 2026 Google LLC+ * SPDX-License-Identifier: Apache-2.0+ */++import fs from 'node:fs/promises';+import os from 'node:os';+import path from 'node:path';+import process from 'node:process';++import {logger} from '../logger.js';++export interface LocalState {+ lastActive: string; // ISO 8601 UTC date string+}++const STATE_FILE_NAME = 'telemetry_state.json';+function getDataFolder(): string {+ const homedir = os.homedir();+ const {env} = process;+ const name = 'chrome-devtools-mcp';++ if (process.platform === 'darwin') {+ return path.join(homedir, 'Library', 'Application Support', name);+ }++ if (process.platform === 'win32') {+ const localAppData =+ env.LOCALAPPDATA || path.join(homedir, 'AppData', 'Local');+ return path.join(localAppData, name, 'Data');+ }++ return path.join(+ env.XDG_DATA_HOME || path.join(homedir, '.local', 'share'),+ name,+ );+}++export interface Persistence {+ loadState(): Promise<LocalState>;+ saveState(state: LocalState): Promise<void>;+}++export class FilePersistence implements Persistence {+ #dataFolder: string;++ constructor(dataFolderOverride?: string) {+ this.#dataFolder = dataFolderOverride ?? getDataFolder();+ }++ async loadState(): Promise<LocalState> {+ try {+ const filePath = path.join(this.#dataFolder, STATE_FILE_NAME);+ const content = await fs.readFile(filePath, 'utf-8');+ return JSON.parse(content) as LocalState;+ } catch {+ return {+ lastActive: '',+ };+ }+ }++ async saveState(state: LocalState): Promise<void> {+ const filePath = path.join(this.#dataFolder, STATE_FILE_NAME);+ try {+ await fs.mkdir(this.#dataFolder, {recursive: true});+ await fs.writeFile(filePath, JSON.stringify(state, null, 2), 'utf-8');+ } catch (error) {+ // Ignore errors during state saving to avoid crashing the server+ logger(`Failed to save telemetry state to ${filePath}:`, error);+ }+ }+}diff --git a/src/telemetry/types.ts b/src/telemetry/types.tsindex c6e1cb19..7e823454 100644--- a/src/telemetry/types.ts+++ b/src/telemetry/types.ts@@ -13,7 +13,6 @@ export interface ChromeDevToolsMcpExtension {tool_invocation?: ToolInvocation;server_start?: ServerStart;daily_active?: DailyActive;- first_time_installation?: FirstTimeInstallation;}export interface ToolInvocation {@@ -30,8 +29,6 @@ export interface DailyActive {days_since_last_active: number;}-export type FirstTimeInstallation = Record<string, never>;-export type FlagUsage = Record<string, boolean | string | number | undefined>;// Clearcut API interfacesdiff --git a/tests/telemetry/clearcut-logger.test.ts b/tests/telemetry/clearcut-logger.test.tsindex b41c6da4..c0a11456 100644--- a/tests/telemetry/clearcut-logger.test.ts+++ b/tests/telemetry/clearcut-logger.test.ts@@ -5,43 +5,145 @@*/import assert from 'node:assert';-import {describe, it, mock} from 'node:test';+import {describe, it, afterEach, beforeEach} from 'node:test';++import sinon from 'sinon';import {ClearcutLogger} from '../../src/telemetry/clearcut-logger.js';import {ClearcutSender} from '../../src/telemetry/clearcut-sender.js';+import type {Persistence} from '../../src/telemetry/persistence.js';+import {FilePersistence} from '../../src/telemetry/persistence.js';describe('ClearcutLogger', () => {- it('should log tool invocation via sender', async () => {- const sender = new ClearcutSender();- const sendSpy = mock.method(sender, 'send');- const loggerInstance = new ClearcutLogger(sender);-- await loggerInstance.logToolInvocation({- toolName: 'test-tool',- success: true,- latencyMs: 100,+ let mockPersistence: sinon.SinonStubbedInstance<Persistence>;+ let mockSender: sinon.SinonStubbedInstance<ClearcutSender>;++ beforeEach(() => {+ mockPersistence = sinon.createStubInstance(FilePersistence, {+ loadState: Promise.resolve({+ lastActive: '',+ }),+ });+ mockSender = sinon.createStubInstance(ClearcutSender);+ mockSender.send.resolves();+ });++ afterEach(() => {+ sinon.restore();+ });++ describe('logToolInvocation', () => {+ it('sends correct payload', async () => {+ const logger = new ClearcutLogger({+ persistence: mockPersistence,+ sender: mockSender,+ });+ await logger.logToolInvocation({+ toolName: 'test_tool',+ success: true,+ latencyMs: 123,+ });++ assert(mockSender.send.calledOnce);+ const extension = mockSender.send.firstCall.args[0];+ assert.strictEqual(extension.tool_invocation?.tool_name, 'test_tool');+ assert.strictEqual(extension.tool_invocation?.success, true);+ assert.strictEqual(extension.tool_invocation?.latency_ms, 123);});+ });++ describe('logServerStart', () => {+ it('logs flag usage', async () => {+ const logger = new ClearcutLogger({+ persistence: mockPersistence,+ sender: mockSender,+ });++ await logger.logServerStart({headless: true});- assert.strictEqual(sendSpy.mock.callCount(), 1);- const event = sendSpy.mock.calls[0].arguments[0];- assert.deepStrictEqual(event.tool_invocation, {- tool_name: 'test-tool',- success: true,- latency_ms: 100,+ // Should have logged server start+ const calls = mockSender.send.getCalls();+ const serverStartCall = calls.find(call => {+ return !!call.args[0].server_start;+ });++ assert(serverStartCall);+ assert.strictEqual(+ serverStartCall.args[0].server_start?.flag_usage?.headless,+ true,+ );});});- it('should log server start via sender', async () => {- const sender = new ClearcutSender();- const sendSpy = mock.method(sender, 'send');- const loggerInstance = new ClearcutLogger(sender);+ describe('logDailyActiveIfNeeded', () => {+ it('logs daily active if needed (lastActive > 24h ago)', async () => {+ const yesterday = new Date();+ yesterday.setDate(yesterday.getDate() - 1);++ mockPersistence.loadState.resolves({+ lastActive: yesterday.toISOString(),+ });++ const logger = new ClearcutLogger({+ persistence: mockPersistence,+ sender: mockSender,+ });++ await logger.logDailyActiveIfNeeded();++ const calls = mockSender.send.getCalls();+ const dailyActiveCall = calls.find(call => {+ return !!call.args[0].daily_active;+ });++ assert(dailyActiveCall, 'Should have logged daily active');+ assert(mockPersistence.saveState.called);+ });++ it('does not log daily active if not needed (today)', async () => {+ mockPersistence.loadState.resolves({+ lastActive: new Date().toISOString(),+ });++ const logger = new ClearcutLogger({+ persistence: mockPersistence,+ sender: mockSender,+ });++ await logger.logDailyActiveIfNeeded();++ const calls = mockSender.send.getCalls();+ const dailyActiveCall = calls.find(call => {+ return !!call.args[0].daily_active;+ });++ assert(!dailyActiveCall, 'Should NOT have logged daily active');+ assert(mockPersistence.saveState.notCalled);+ });++ it('logs daily active with -1 if lastActive is missing', async () => {+ mockPersistence.loadState.resolves({+ lastActive: '',+ });++ const logger = new ClearcutLogger({+ persistence: mockPersistence,+ sender: mockSender,+ });++ await logger.logDailyActiveIfNeeded();- await loggerInstance.logServerStart({headless: true});+ const calls = mockSender.send.getCalls();+ const dailyActiveCall = calls.find(call => {+ return !!call.args[0].daily_active;+ });- assert.strictEqual(sendSpy.mock.callCount(), 1);- const event = sendSpy.mock.calls[0].arguments[0];- assert.deepStrictEqual(event.server_start, {- flag_usage: {headless: true},+ assert(dailyActiveCall, 'Should have logged daily active');+ assert.strictEqual(+ dailyActiveCall.args[0].daily_active?.days_since_last_active,+ -1,+ );+ assert(mockPersistence.saveState.called);});});});diff --git a/tests/telemetry/persistence.test.ts b/tests/telemetry/persistence.test.tsnew file mode 100644index 00000000..9bacada9--- /dev/null+++ b/tests/telemetry/persistence.test.ts@@ -0,0 +1,70 @@+/**+ * @license+ * Copyright 2026 Google LLC+ * SPDX-License-Identifier: Apache-2.0+ */++import assert from 'node:assert';+import crypto from 'node:crypto';+import fs from 'node:fs/promises';+import os from 'node:os';+import path from 'node:path';+import {describe, it, afterEach, beforeEach} from 'node:test';++import * as persistence from '../../src/telemetry/persistence.js';++describe('FilePersistence', () => {+ let tmpDir: string;++ beforeEach(async () => {+ tmpDir = path.join(+ await fs.realpath(os.tmpdir()),+ `telemetry-test-${crypto.randomUUID()}`,+ );+ await fs.mkdir(tmpDir, {recursive: true});+ });++ afterEach(async () => {+ await fs.rm(tmpDir, {recursive: true, force: true});+ });++ describe('loadState', () => {+ it('returns default state if file does not exist', async () => {+ const filePersistence = new persistence.FilePersistence(tmpDir);+ const state = await filePersistence.loadState();+ assert.deepStrictEqual(state, {+ lastActive: '',+ });+ });++ it('returns stored state if file exists', async () => {+ const expectedState = {+ lastActive: '2023-01-01T00:00:00.000Z',+ };+ await fs.writeFile(+ path.join(tmpDir, 'telemetry_state.json'),+ JSON.stringify(expectedState),+ );++ const filePersistence = new persistence.FilePersistence(tmpDir);+ const state = await filePersistence.loadState();+ assert.deepStrictEqual(state, expectedState);+ });+ });++ describe('saveState', () => {+ it('saves state to file', async () => {+ const state = {+ lastActive: '2023-01-01T00:00:00.000Z',+ };+ const filePersistence = new persistence.FilePersistence(tmpDir);+ await filePersistence.saveState(state);++ const content = await fs.readFile(+ path.join(tmpDir, 'telemetry_state.json'),+ 'utf-8',+ );+ assert.deepStrictEqual(JSON.parse(content), state);+ });+ });+});