chore: make Clearcut logger a global singleton (#1999)

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.

Author: yulunz

src/bin/chrome-devtools-mcp-main.ts

@@ -10,6 +10,7 @@ import process from 'node:process';
 
 import {createMcpServer, logDisclaimers} from '../index.js';
 import {logger, saveLogsToFile} from '../logger.js';
+import {ClearcutLogger} from '../telemetry/ClearcutLogger.js';
 import {computeFlagUsage} from '../telemetry/flagUtils.js';
 import {StdioServerTransport} from '../third_party/index.js';
 import {checkForUpdates} from '../utils/check-for-updates.js';
@@ -32,12 +33,12 @@ if (process.env['CHROME_DEVTOOLS_MCP_CRASH_ON_UNCAUGHT'] !== 'true') {
 }
 
 logger(`Starting Chrome DevTools MCP Server v${VERSION}`);
-const {server, clearcutLogger} = await createMcpServer(args, {
+const {server} = await createMcpServer(args, {
   logFile,
 });
 const transport = new StdioServerTransport();
 await server.connect(transport);
 logger('Chrome DevTools MCP Server connected');
 logDisclaimers(args);
-void clearcutLogger?.logDailyActiveIfNeeded();
-void clearcutLogger?.logServerStart(computeFlagUsage(args, cliOptions));
+void ClearcutLogger.get()?.logDailyActiveIfNeeded();
+void ClearcutLogger.get()?.logServerStart(computeFlagUsage(args, cliOptions));

src/index.ts

@@ -134,9 +134,8 @@ export async function createMcpServer(
     logFile?: fs.WriteStream;
   },
 ) {
-  let clearcutLogger: ClearcutLogger | undefined;
   if (serverArgs.usageStatistics) {
-    clearcutLogger = new ClearcutLogger({
+    ClearcutLogger.initialize({
       logFile: serverArgs.logFile,
       appVersion: VERSION,
       clearcutEndpoint: serverArgs.clearcutEndpoint,
@@ -175,7 +174,7 @@ export async function createMcpServer(
   server.server.oninitialized = () => {
     const clientName = server.server.getClientVersion()?.name;
     if (clientName) {
-      clearcutLogger?.setClientName(clientName);
+      ClearcutLogger.get()?.setClientName(clientName);
     }
     if (server.server.getClientCapabilities()?.roots) {
       void updateRoots();
@@ -360,7 +359,7 @@ export async function createMcpServer(
             isError: true,
           };
         } finally {
-          void clearcutLogger?.logToolInvocation({
+          void ClearcutLogger.get()?.logToolInvocation({
             toolName: tool.name,
             params,
             schema,
@@ -380,7 +379,7 @@ export async function createMcpServer(
 
   await loadIssueDescriptions();
 
-  return {server, clearcutLogger};
+  return {server};
 }
 
 export const logDisclaimers = (args: ReturnType<typeof parseArguments>) => {

src/telemetry/ClearcutLogger.ts

@@ -171,20 +171,41 @@ function detectOsType(): OsType {
   }
 }
 
+export interface ClearcutLoggerOptions {
+  appVersion: string;
+  logFile?: string;
+  persistence?: Persistence;
+  watchdogClient?: WatchdogClient;
+  clearcutEndpoint?: string;
+  clearcutForceFlushIntervalMs?: number;
+  clearcutIncludePidHeader?: boolean;
+}
+
+// Not const to allow resetting the instance for testing purposes.
+let _clearcut_logger_instance: ClearcutLogger | undefined;
+
 export class ClearcutLogger {
   #persistence: Persistence;
   #watchdog: WatchdogClient;
   #mcpClient: McpClient;
 
-  constructor(options: {
-    appVersion: string;
-    logFile?: string;
-    persistence?: Persistence;
-    watchdogClient?: WatchdogClient;
-    clearcutEndpoint?: string;
-    clearcutForceFlushIntervalMs?: number;
-    clearcutIncludePidHeader?: boolean;
-  }) {
+  static initialize(options: ClearcutLoggerOptions): ClearcutLogger {
+    if (_clearcut_logger_instance) {
+      throw new Error('ClearcutLogger is already initialized');
+    }
+    _clearcut_logger_instance = new ClearcutLogger(options);
+    return _clearcut_logger_instance;
+  }
+
+  static get(): ClearcutLogger | undefined {
+    return _clearcut_logger_instance;
+  }
+
+  static resetForTesting(): void {
+    _clearcut_logger_instance = undefined;
+  }
+
+  private constructor(options: ClearcutLoggerOptions) {
     this.#persistence = options.persistence ?? new FilePersistence();
     this.#watchdog =
       options.watchdogClient ??

tests/telemetry/ClearcutLogger.test.ts

@@ -25,6 +25,7 @@ describe('ClearcutLogger', () => {
   let mockWatchdogClient: sinon.SinonStubbedInstance<WatchdogClient>;
 
   beforeEach(() => {
+    ClearcutLogger.resetForTesting();
     mockPersistence = sinon.createStubInstance(FilePersistence, {
       loadState: Promise.resolve({
         lastActive: '',
@@ -35,11 +36,12 @@ describe('ClearcutLogger', () => {
 
   afterEach(() => {
     sinon.restore();
+    ClearcutLogger.resetForTesting();
   });
 
   describe('logToolInvocation', () => {
     it('sends correct payload', async () => {
-      const logger = new ClearcutLogger({
+      const logger = ClearcutLogger.initialize({
         persistence: mockPersistence,
         appVersion: '1.0.0',
         watchdogClient: mockWatchdogClient,
@@ -60,7 +62,7 @@ describe('ClearcutLogger', () => {
       assert.strictEqual(msg.payload.tool_invocation?.latency_ms, 123);
     });
     it('sends sanitized params', async () => {
-      const logger = new ClearcutLogger({
+      const logger = ClearcutLogger.initialize({
         persistence: mockPersistence,
         appVersion: '1.0.0',
         watchdogClient: mockWatchdogClient,
@@ -107,7 +109,7 @@ describe('ClearcutLogger', () => {
 
     for (const {name, expected} of clients) {
       it(`maps ${name} client correctly`, async () => {
-        const logger = new ClearcutLogger({
+        const logger = ClearcutLogger.initialize({
           persistence: mockPersistence,
           appVersion: '1.0.0',
           watchdogClient: mockWatchdogClient,
@@ -126,7 +128,7 @@ describe('ClearcutLogger', () => {
 
   describe('logServerStart', () => {
     it('logs flag usage', async () => {
-      const logger = new ClearcutLogger({
+      const logger = ClearcutLogger.initialize({
         persistence: mockPersistence,
         appVersion: '1.0.0',
         watchdogClient: mockWatchdogClient,
@@ -150,7 +152,7 @@ describe('ClearcutLogger', () => {
         lastActive: yesterday.toISOString(),
       });
 
-      const logger = new ClearcutLogger({
+      const logger = ClearcutLogger.initialize({
         persistence: mockPersistence,
         appVersion: '1.0.0',
         watchdogClient: mockWatchdogClient,
@@ -171,7 +173,7 @@ describe('ClearcutLogger', () => {
         lastActive: new Date().toISOString(),
       });
 
-      const logger = new ClearcutLogger({
+      const logger = ClearcutLogger.initialize({
         persistence: mockPersistence,
         appVersion: '1.0.0',
         watchdogClient: mockWatchdogClient,
@@ -188,7 +190,7 @@ describe('ClearcutLogger', () => {
         lastActive: '',
       });
 
-      const logger = new ClearcutLogger({
+      const logger = ClearcutLogger.initialize({
         persistence: mockPersistence,
         appVersion: '1.0.0',
         watchdogClient: mockWatchdogClient,
@@ -292,4 +294,46 @@ describe('ClearcutLogger', () => {
       );
     });
   });
+
+  describe('Singleton', () => {
+    it('returns undefined if not initialized', () => {
+      assert.strictEqual(ClearcutLogger.get(), undefined);
+    });
+
+    it('returns instance after initialization', () => {
+      const logger = ClearcutLogger.initialize({
+        persistence: mockPersistence,
+        appVersion: '1.0.0',
+        watchdogClient: mockWatchdogClient,
+      });
+      assert.strictEqual(ClearcutLogger.get(), logger);
+    });
+
+    it('throws error if initialized twice', () => {
+      ClearcutLogger.initialize({
+        persistence: mockPersistence,
+        appVersion: '1.0.0',
+        watchdogClient: mockWatchdogClient,
+      });
+
+      assert.throws(() => {
+        ClearcutLogger.initialize({
+          persistence: mockPersistence,
+          appVersion: '1.0.0',
+          watchdogClient: mockWatchdogClient,
+        });
+      }, /ClearcutLogger is already initialized/);
+    });
+
+    it('resets instance for testing', () => {
+      ClearcutLogger.initialize({
+        persistence: mockPersistence,
+        appVersion: '1.0.0',
+        watchdogClient: mockWatchdogClient,
+      });
+
+      ClearcutLogger.resetForTesting();
+      assert.strictEqual(ClearcutLogger.get(), undefined);
+    });
+  });
 });