refactor: eliminate internal Logger (debug npm) in favor of Effect structured logging (#115)

Remove all `new Logger(...)` instantiations used for internal logging across 24
files. Effect logging (logInfo, logWarning, logError, logDebug) flows through
OTLP → Loki with structured attributes and span correlation, replacing the
debug npm module's unstructured stderr output.

Conversion patterns by context:
- Effect generators: yield* Effect.logInfo(...)
- Sync/callback: runForkInServer(Effect.logWarning(...))
- Own ManagedRuntime (encoder, cdp-session): this.runtime.runFork(Effect.log*(...))
- Signal handlers/child processes: console.error(JSON.stringify({...}))

The Logger class itself remains — it's embedded in the SDK interface (types.ts
handler signatures, browser constructors, per-request instantiation). That
migration is Phase B (future work).

Author: DivMode

src/browserless.ts

@@ -62,7 +62,6 @@ type routeInstances =
   | BrowserWebsocketRoute;
 
 export class Browserless extends EventEmitter {
-  protected logger: BlessLogger;
   protected browserManager: BrowserManager;
   protected config: Config;
   protected fileSystem: FileSystem;
@@ -114,7 +113,6 @@ export class Browserless extends EventEmitter {
   } = {}) {
     super();
     this.Logger = LoggerOverride ?? BlessLogger;
-    this.logger = new this.Logger('index');
     this.config = config || new Config();
     this.metrics = metrics || new Metrics();
     this.token = token || new Token(this.config);
@@ -158,8 +156,10 @@ export class Browserless extends EventEmitter {
         route.browser.name.toLowerCase().includes(b),
       )
     ) {
-      this.logger.warn(
-        `Ignoring route "${route.path}" because it is not supported on arm64 platforms (route requires browser "${route.browser.name}").`,
+      runForkInServer(
+        Effect.logWarning(
+          `Ignoring route "${route.path}" because it is not supported on arm64 platforms (route requires browser "${route.browser.name}").`,
+        ),
       );
       return false;
     }
@@ -486,8 +486,10 @@ export class Browserless extends EventEmitter {
         .filter((e, i, a) => a.findIndex((r) => r.name === e.name) !== i)
         .map((r) => r.name)
         .forEach((name) => {
-          this.logger.warn(
-            `Found duplicate routing names. Route names must be unique: ${name}`,
+          runForkInServer(
+            Effect.logWarning(
+              `Found duplicate routing names. Route names must be unique: ${name}`,
+            ),
           );
         });
 

src/browsers/browser-launcher.ts

@@ -33,6 +33,7 @@ import { Page } from 'puppeteer-core';
 import micromatch from 'micromatch';
 import path from 'path';
 
+import { runForkInServer } from '../otel-runtime.js';
 import { SessionRegistry } from '../session/session-registry.js';
 import { SessionCoordinator } from '../session/session-coordinator.js';
 
@@ -57,8 +58,6 @@ export class BrowserLauncher {
     FirefoxPlaywright.name,
     WebKitPlaywright.name,
   ];
-  private log = new Logger('browser-launcher');
-
   constructor(
     private config: Config,
     private hooks: Hooks,
@@ -268,14 +267,14 @@ export class BrowserLauncher {
               onTabReplayComplete: (metadata) => {
                 if (isReplayCapable(browser)) {
                   browser.sendTabReplayComplete(metadata).catch((e) => {
-                    launcher.log.warn(`Failed to send tab replay event: ${e instanceof Error ? e.message : String(e)}`);
+                    runForkInServer(Effect.logWarning(`Failed to send tab replay event: ${e instanceof Error ? e.message : String(e)}`));
                   });
                 }
               },
               onAntibotReport: (report) => {
                 if (browser instanceof ChromiumCDP) {
                   browser.emitAntibotReport(report).catch((e) => {
-                    launcher.log.warn(`Failed to emit antibot report: ${e instanceof Error ? e.message : String(e)}`);
+                    runForkInServer(Effect.logWarning(`Failed to emit antibot report: ${e instanceof Error ? e.message : String(e)}`));
                   });
                 }
               },
@@ -328,7 +327,7 @@ export class BrowserLauncher {
     if (found) {
       const [browser, session] = found;
       ++session.numbConnected;
-      this.log.debug(`Located browser with ID ${id}`);
+      runForkInServer(Effect.logDebug(`Located browser with ID ${id}`));
       return browser;
     }
 
@@ -370,7 +369,7 @@ export class BrowserLauncher {
       if (found) {
         const session = this.registry.get(found.browser)!;
         ++session.numbConnected;
-        this.log.debug(`Page connection: session ${session.id} numbConnected=${session.numbConnected} pageId=${id}`);
+        runForkInServer(Effect.logDebug(`Page connection: session ${session.id} numbConnected=${session.numbConnected} pageId=${id}`));
         return found.browser;
       }
 

src/browsers/index.ts

@@ -42,7 +42,6 @@ import type { VideoManager } from '../video/video-manager.js';
  * This class was reduced from 1270 lines to ~200 lines.
  */
 export class BrowserManager {
-  protected log = new Logger('browser-manager');
   protected chromeBrowsers = [ChromiumCDP, ChromeCDP, EdgeCDP];
 
   // Extracted components

src/cdp-proxy.ts

@@ -3,10 +3,11 @@ import WebSocket from 'ws';
 const WebSocketServer = (WebSocket as any).Server as typeof import('ws').WebSocketServer;
 import { Duplex } from 'stream';
 import { IncomingMessage } from 'http';
-import { Config, Logger } from '@browserless.io/browserless';
+import { Config } from '@browserless.io/browserless';
 import { Duration, Effect, Exit, FiberSet, Queue, Schedule, Schema, Scope, Stream } from 'effect';
 
 import { incCounter, proxyDroppedMessages, wsLifecycle } from './effect-metrics.js';
+import { runForkInServer } from './otel-runtime.js';
 import { CloudflareConfig } from './shared/cloudflare-detection.js';
 import { CdpSessionId, TargetId } from './shared/cloudflare-detection.js';
 import { BROWSER_WS_PING_INTERVAL, BROWSER_WS_PONG_TIMEOUT_MS } from './session/cf/cf-schedules.js';
@@ -114,7 +115,6 @@ export class CDPProxy {
   private clientOutbound: Queue.Queue<ClientOutboundMessage> | null = null;
   private isClosing = false;
   private closeRequested = false;
-  private log = new Logger('cdp-proxy');
   private getTabCount?: () => number;
   private readonly proxyScope = Scope.makeUnsafe();
   private readonly fibers = Effect.runSync(
@@ -190,7 +190,7 @@ export class CDPProxy {
           const ws = this.browserWs!;
           const onOpen = () => {
             ws.removeListener('error', onError);
-            this.log.trace(`Connected to browser: ${this.browserWsEndpoint}`);
+            runForkInServer(Effect.logDebug('Connected to browser').pipe(Effect.annotateLogs({ endpoint: this.browserWsEndpoint })));
             resume(Effect.void);
           };
           const onError = (err: Error) => {
@@ -222,7 +222,7 @@ export class CDPProxy {
         // Setup AFTER successful upgrade
         this.clientWs = clientWs;
         Effect.runSync(incCounter(wsLifecycle, { type: 'proxy_client', action: 'create' }));
-        this.log.trace('Client WebSocket upgraded');
+        runForkInServer(Effect.logDebug('Client WebSocket upgraded'));
 
         // Scope-bound outbound queue: all client WS sends go through here.
         this.clientOutbound = Effect.runSync(Queue.unbounded<ClientOutboundMessage>());
@@ -254,12 +254,12 @@ export class CDPProxy {
         const sessionId = this.browserWsEndpoint.split('/').pop() || '';
         if (sessionId) {
           this.emitClientEvent('Browserless.sessionInfo', { sessionId }).catch((e) => {
-            this.log.debug(`Failed to emit sessionInfo: ${e instanceof Error ? e.message : String(e)}`);
+            runForkInServer(Effect.logDebug('Failed to emit sessionInfo').pipe(Effect.annotateLogs({ error: e instanceof Error ? e.message : String(e) })));
           });
         }
 
         clientWs.on('error', (err: Error) => {
-          this.log.warn(`Client WebSocket error: ${err.message}`);
+          runForkInServer(Effect.logWarning('Client WebSocket error').pipe(Effect.annotateLogs({ error: err.message })));
           this.handleClose();
         });
       })(),
@@ -366,7 +366,7 @@ export class CDPProxy {
                 // Sync check — fast path when CdpSession is tracking targets
                 const count = this.getTabCount();
                 if (count >= limit) {
-                  this.log.warn(`Tab limit reached (${count}/${limit}), rejecting Target.createTarget`);
+                  runForkInServer(Effect.logWarning('Tab limit reached, rejecting Target.createTarget').pipe(Effect.annotateLogs({ count: String(count), limit: String(limit) })));
                   void this.sendClientError(msg.id, -32000, `Tab limit exceeded (${count}/${limit})`);
                   return;
                 }
@@ -390,9 +390,10 @@ export class CDPProxy {
             const clickCount = p?.clickCount ?? 0;
             // Full CDP sessionId — maps to a specific target (tab/OOPIF)
             const cdpSessionId = msg.sessionId ?? 'page';
-            this.log.warn(
-              `[PYDOLL-MOUSE] ${type} x=${x} y=${y} button=${button} clicks=${clickCount} cdpSession=${cdpSessionId}`,
-            );
+            runForkInServer(Effect.logWarning('[PYDOLL-MOUSE] dispatch').pipe(Effect.annotateLogs({
+              type: String(type), x: String(x), y: String(y), button: String(button),
+              clickCount: String(clickCount), cdpSession: String(cdpSessionId),
+            })));
           }
         } catch {
           // ignore parse errors
@@ -407,7 +408,7 @@ export class CDPProxy {
           if (msg.method) {
             const sid = msg.sessionId ? ` [sid=${msg.sessionId.substring(0, 16)}]` : '';
             const params = msg.params ? JSON.stringify(msg.params).substring(0, 200) : '{}';
-            this.log.info(`[CDP→Chrome] id=${msg.id} ${msg.method}${sid} ${params}`);
+            runForkInServer(Effect.logInfo('[CDP→Chrome]').pipe(Effect.annotateLogs({ id: String(msg.id), method: msg.method, sid: sid.trim(), params })));
           }
         } catch { /* ignore */ }
       }
@@ -431,7 +432,7 @@ export class CDPProxy {
             if (this.cdpDebug && msg.method) {
               const sid = msg.sessionId ? ` [sid=${msg.sessionId.substring(0, 16)}]` : '';
               const params = msg.params ? JSON.stringify(msg.params).substring(0, 150) : '{}';
-              this.log.info(`[Chrome→CDP] ${msg.method}${sid} ${params}`);
+              runForkInServer(Effect.logInfo('[Chrome→CDP]').pipe(Effect.annotateLogs({ method: msg.method, sid: sid.trim(), params })));
             }
           }
         } catch { /* ignore parse errors */ }
@@ -443,12 +444,12 @@ export class CDPProxy {
 
     // Handle close from either side
     this.clientWs.on('close', () => {
-      this.log.trace('Client WebSocket closed');
+      runForkInServer(Effect.logDebug('Client WebSocket closed'));
       this.handleClose();
     });
 
     this.browserWs.on('close', () => {
-      this.log.trace('Browser WebSocket closed');
+      runForkInServer(Effect.logDebug('Browser WebSocket closed'));
       this.handleClose();
     });
 
@@ -469,7 +470,7 @@ export class CDPProxy {
         Effect.tryPromise(() => this.onBeforeClose!()).pipe(
           Effect.timeout(Duration.millis(ON_BEFORE_CLOSE_TIMEOUT_MS)),
           Effect.catch((e) => Effect.sync(() => {
-            this.log.warn(`onBeforeClose failed: ${e instanceof Error ? e.message : String(e)}`);
+            runForkInServer(Effect.logWarning('onBeforeClose failed').pipe(Effect.annotateLogs({ error: e instanceof Error ? e.message : String(e) })));
           })),
         ),
       );
@@ -490,7 +491,7 @@ export class CDPProxy {
       if (!Queue.offerUnsafe(this.clientOutbound!, {
         data: message,
         onSent: resolve,
-        onError: (err) => { this.log.warn(`Failed to send CDP response id=${id}: ${err.message}`); reject(err); },
+        onError: (err) => { runForkInServer(Effect.logWarning('Failed to send CDP response').pipe(Effect.annotateLogs({ id: String(id), error: err.message }))); reject(err); },
       })) {
         Effect.runSync(incCounter(proxyDroppedMessages, { direction: 'client' }));
         resolve();
@@ -505,7 +506,7 @@ export class CDPProxy {
       if (!Queue.offerUnsafe(this.clientOutbound!, {
         data: payload,
         onSent: resolve,
-        onError: (err) => { this.log.warn(`Failed to send CDP error id=${id}: ${err.message}`); reject(err); },
+        onError: (err) => { runForkInServer(Effect.logWarning('Failed to send CDP error').pipe(Effect.annotateLogs({ id: String(id), error: err.message }))); reject(err); },
       })) {
         Effect.runSync(incCounter(proxyDroppedMessages, { direction: 'client' }));
         resolve();
@@ -528,13 +529,13 @@ export class CDPProxy {
       const targets: Array<{ type: string }> = result?.targetInfos ?? [];
       const count = targets.filter(t => t.type === 'page').length;
       if (count >= limit) {
-        this.log.warn(`Tab limit reached (${count}/${limit}), rejecting Target.createTarget`);
+        runForkInServer(Effect.logWarning('Tab limit reached, rejecting Target.createTarget').pipe(Effect.annotateLogs({ count: String(count), limit: String(limit) })));
         void this.sendClientError(msgId, -32000, `Tab limit exceeded (${count}/${limit})`);
         return;
       }
     } catch (e) {
       // If we can't determine tab count, allow the request through
-      this.log.debug(`Tab count check failed, allowing Target.createTarget: ${e instanceof Error ? e.message : String(e)}`);
+      runForkInServer(Effect.logDebug('Tab count check failed, allowing Target.createTarget').pipe(Effect.annotateLogs({ error: e instanceof Error ? e.message : String(e) })));
     }
     // Under limit or check failed — forward to browser
     this.sendToBrowser(data, isBinary);
@@ -549,15 +550,15 @@ export class CDPProxy {
    */
   async emitClientEvent(method: string, params: object): Promise<void> {
     if (!this.clientOutbound) {
-      this.log.warn(`Cannot inject event ${method}: queue not initialized`);
+      runForkInServer(Effect.logWarning('Cannot inject event: queue not initialized').pipe(Effect.annotateLogs({ method })));
       return;
     }
     const message = JSON.stringify({ method, params });
     return new Promise<void>((resolve, reject) => {
       const offered = Queue.offerUnsafe(this.clientOutbound!, {
         data: message,
-        onSent: () => { this.log.trace(`Injected CDP event: ${method}`); resolve(); },
-        onError: (err) => { this.log.warn(`Failed to inject CDP event ${method}: ${err.message}`); reject(err); },
+        onSent: () => { runForkInServer(Effect.logDebug('Injected CDP event').pipe(Effect.annotateLogs({ method }))); resolve(); },
+        onError: (err) => { runForkInServer(Effect.logWarning('Failed to inject CDP event').pipe(Effect.annotateLogs({ method, error: err.message }))); reject(err); },
       });
       if (!offered) {
         Effect.runSync(incCounter(proxyDroppedMessages, { direction: 'client' }));
@@ -590,7 +591,7 @@ export class CDPProxy {
     if (this.cdpDebug) {
       const sid = sessionId ? ` [sid=${sessionId.substring(0, 16)}]` : '';
       const p = JSON.stringify(params).substring(0, 200);
-      this.log.info(`[SOLVER→Chrome] ${method}${sid} ${p}`);
+      runForkInServer(Effect.logInfo('[SOLVER→Chrome]').pipe(Effect.annotateLogs({ method, sid: sid.trim(), params: p })));
     }
 
     return conn.sendPromise(method, params, sessionId, timeoutMs);
@@ -678,12 +679,12 @@ export class CDPProxy {
    */
   async sendReplayComplete(metadata: ReplayCompleteParams): Promise<void> {
     await this.emitClientEvent('Browserless.replayComplete', metadata);
-    this.log.info(`Sent replay complete event: ${metadata.id}`);
+    runForkInServer(Effect.logInfo('Sent replay complete event').pipe(Effect.annotateLogs({ replay_id: metadata.id })));
   }
 
   async sendTabReplayComplete(metadata: TabReplayCompleteParams): Promise<void> {
     await this.emitClientEvent('Browserless.tabReplayComplete', metadata);
-    this.log.info(`Sent tab replay complete event: targetId=${metadata.targetId}`);
+    runForkInServer(Effect.logInfo('Sent tab replay complete event').pipe(Effect.annotateLogs({ targetId: metadata.targetId })));
   }
 
   /**
@@ -732,15 +733,15 @@ export class CDPProxy {
       });
 
       if (!gotPong) {
-        this.log.warn('Browser WS heartbeat timeout — Chrome not responding, closing session');
+        runForkInServer(Effect.logWarning('Browser WS heartbeat timeout — Chrome not responding, closing session'));
         this.handleClose();
       }
     });
 
     this.forkManaged(
       tick().pipe(
         Effect.catch((e) => Effect.sync(() => {
-          this.log.warn(`Browser WS ping failed, closing session: ${e instanceof Error ? e.message : String(e)}`);
+          runForkInServer(Effect.logWarning('Browser WS ping failed, closing session').pipe(Effect.annotateLogs({ error: e instanceof Error ? e.message : String(e) })));
           this.handleClose();
         })),
         Effect.repeat(Schedule.fixed(BROWSER_WS_PING_INTERVAL)),
@@ -779,10 +780,10 @@ export class CDPProxy {
 
     const clientState = this.clientWs?.readyState;
     const browserState = this.browserWs?.readyState;
-    this.log.info(
-      `CDPProxy closing: clientWs=${clientState === WebSocket.OPEN ? 'OPEN' : clientState} ` +
-      `browserWs=${browserState === WebSocket.OPEN ? 'OPEN' : browserState}`
-    );
+    runForkInServer(Effect.logInfo('CDPProxy closing').pipe(Effect.annotateLogs({
+      clientWs: clientState === WebSocket.OPEN ? 'OPEN' : String(clientState),
+      browserWs: browserState === WebSocket.OPEN ? 'OPEN' : String(browserState),
+    })));
 
     // Await scope close so all acquireRelease finalizers fire before onClose
     this.closePromise = Effect.runPromise(Scope.close(this.proxyScope, Exit.void))

src/container/container.ts

@@ -1,4 +1,6 @@
-import { Logger } from '@browserless.io/browserless';
+import { Effect } from 'effect';
+
+import { runForkInServer } from '../otel-runtime.js';
 
 /**
  * Service factory function type.
@@ -36,7 +38,6 @@ interface ServiceRegistration<T> {
 export class ServiceContainer {
   private services: Map<string, ServiceRegistration<unknown>> = new Map();
   private resolving: Set<string> = new Set(); // For circular dependency detection
-  private log = new Logger('container');
 
   /**
    * Register a singleton service.
@@ -48,7 +49,7 @@ export class ServiceContainer {
     dependencies: string[] = []
   ): this {
     if (this.services.has(name)) {
-      this.log.warn(`Service "${name}" is being overwritten`);
+      runForkInServer(Effect.logWarning(`Service "${name}" is being overwritten`));
     }
 
     this.services.set(name, {
@@ -70,7 +71,7 @@ export class ServiceContainer {
     dependencies: string[] = []
   ): this {
     if (this.services.has(name)) {
-      this.log.warn(`Service "${name}" is being overwritten`);
+      runForkInServer(Effect.logWarning(`Service "${name}" is being overwritten`));
     }
 
     this.services.set(name, {
@@ -88,7 +89,7 @@ export class ServiceContainer {
    */
   registerInstance<T>(name: string, instance: T): this {
     if (this.services.has(name)) {
-      this.log.warn(`Service "${name}" is being overwritten with instance`);
+      runForkInServer(Effect.logWarning(`Service "${name}" is being overwritten with instance`));
     }
 
     this.services.set(name, {
@@ -160,7 +161,7 @@ export class ServiceContainer {
    * Call this at startup to fail fast.
    */
   validate(): void {
-    this.log.debug('Validating service container...');
+    runForkInServer(Effect.logDebug('Validating service container...'));
 
     // Check for missing dependencies
     for (const [name, registration] of this.services) {
@@ -200,7 +201,7 @@ export class ServiceContainer {
       visit(name);
     }
 
-    this.log.debug(`Validated ${this.services.size} services`);
+    runForkInServer(Effect.logDebug(`Validated ${this.services.size} services`));
   }
 
   /**