Log improvement (format) (#599)

* first format for logging (not final?), verbose levels

* build errors fix for e2e tests

* prettier

* fix dev dep

* peer deps

* fix example

* revert inference logger

* verbose 1

* changeset

---------

Co-authored-by: Anirudh Kamath <[email protected]>
Co-authored-by: Sean McGuire <[email protected]>

Author: 3 people

Diff for: .changeset/lemon-walls-wish.md

@@ -0,0 +1,5 @@
+---
+"@browserbasehq/stagehand": minor
+---
+
+cleaner logging with pino

Diff for: docs/logging.md

@@ -0,0 +1,184 @@
+# Stagehand Logging System
+
+The Stagehand logging system uses [Pino](https://getpino.io/) to provide structured, efficient, and configurable logging.
+
+## Log Levels
+
+Stagehand uses three primary log levels:
+
+| Level | Name  | Description                             |
+| ----- | ----- | --------------------------------------- |
+| 0     | error | Critical errors and important warnings  |
+| 1     | info  | Standard information messages (default) |
+| 2     | debug | Detailed information for debugging      |
+
+The verbosity of logging is controlled by the `verbose` option when creating a Stagehand instance:
+
+```typescript
+const stagehand = new Stagehand({
+  verbose: 2, // Show all logs up to debug level
+  // other options...
+});
+```
+
+## Using the Logger
+
+The logging system is automatically initialized with your Stagehand instance. You can access it directly via:
+
+```typescript
+// Log an error
+stagehand.log({
+  message: "An error occurred",
+  level: 0,
+  category: "error",
+});
+
+// Log info (level 1 is default)
+stagehand.log({
+  message: "Operation completed",
+  category: "operation",
+});
+
+// Log debug information
+stagehand.log({
+  message: "Debug details",
+  level: 2,
+  category: "debug",
+  auxiliary: {
+    details: {
+      value: JSON.stringify({ key: "value" }),
+      type: "object",
+    },
+  },
+});
+```
+
+## Inference Logging
+
+For detailed logging of inference operations (act, extract, observe), Stagehand provides specialized logging:
+
+```typescript
+// Enable inference logging to file
+const stagehand = new Stagehand({
+  logInferenceToFile: true,
+  // other options...
+});
+```
+
+When enabled, inference logs are written to the `inference_summary` directory in your project.
+
+## Pretty Printing
+
+By default, logs in development are formatted with colors and readable timestamps using Pino's pretty formatting. For production environments or when sending logs to external systems, you can disable pretty printing.
+
+## Customizing Logging
+
+### Using Your Own Logger
+
+You can provide your own custom logger when creating a Stagehand instance:
+
+```typescript
+const stagehand = new Stagehand({
+  logger: (logLine) => {
+    // Your custom logging logic here
+    console.log(`[${logLine.category}] ${logLine.message}`);
+  },
+  // other options...
+});
+```
+
+When you provide a custom logger, Stagehand will automatically disable its internal Pino logger to prevent duplicate logging. Your logger will receive all log events directly.
+
+### Configuring Pino
+
+If you want to use Pino but with custom configuration:
+
+```typescript
+import { StagehandLogger } from "@browserbasehq/stagehand/lib/logger";
+
+// Create a custom configured logger
+const customLogger = new StagehandLogger({
+  pretty: true,
+  level: "debug",
+  // Other Pino options...
+});
+
+// Pass it to Stagehand
+const stagehand = new Stagehand({
+  logger: (logLine) => customLogger.log(logLine),
+  // other options...
+});
+```
+
+## Advanced Usage
+
+### Creating a New StagehandLogger Instance
+
+You can create a standalone logger for use in your application:
+
+```typescript
+import { StagehandLogger } from "@browserbasehq/stagehand/lib/logger";
+
+const logger = new StagehandLogger({
+  pretty: true,
+  level: "debug",
+});
+
+logger.info("Information message");
+logger.debug("Debug message", { details: "some data" });
+logger.error("Error message", { error: "details" });
+```
+
+### Configuring Log Output
+
+You can direct logs to a file or other destination:
+
+```typescript
+import fs from "fs";
+import { StagehandLogger } from "@browserbasehq/stagehand/lib/logger";
+
+const fileStream = fs.createWriteStream("./logs/application.log", {
+  flags: "a",
+});
+
+const logger = new StagehandLogger({
+  destination: fileStream,
+});
+```
+
+### Disabling Pino Explicitly
+
+If you want to handle all logging yourself without using Pino:
+
+```typescript
+import { StagehandLogger } from "@browserbasehq/stagehand/lib/logger";
+
+const logger = new StagehandLogger(
+  {
+    usePino: false,
+  },
+  (logLine) => {
+    // Your custom logging logic
+    console.log(`[${logLine.level}] ${logLine.message}`);
+  },
+);
+```
+
+## Troubleshooting
+
+If you're not seeing logs:
+
+1. Check your `verbose` setting - it may be too low for the log levels you're trying to see
+2. Verify that your log messages have the correct level set
+3. If using a custom logger, ensure it's correctly handling the log messages
+
+If you're seeing duplicate logs:
+
+1. Make sure you're not creating multiple instances of StagehandLogger that log to the same output
+2. If providing a custom logger to Stagehand, it will automatically disable the internal Pino logger
+
+If logs are not being written to files:
+
+1. Ensure you have write permissions to the target directory
+2. Check that the `logInferenceToFile` option is enabled
+3. Verify that the destination path exists or can be created

Diff for: lib/index.ts

@@ -41,6 +41,7 @@ import { ApiResponse, ErrorResponse } from "@/types/api";
 import { AgentExecuteOptions, AgentResult } from "../types/agent";
 import { StagehandAgentHandler } from "./handlers/agentHandler";
 import { StagehandOperatorHandler } from "./handlers/operatorHandler";
+import { StagehandLogger } from "./logger";
 
 import {
   StagehandError,
@@ -60,6 +61,21 @@ const BROWSERBASE_REGION_DOMAIN = {
   "ap-southeast-1": "wss://connect.apse1.browserbase.com",
 };
 
+// Initialize the global logger
+let globalLogger: StagehandLogger;
+
+const defaultLogger = async (logLine: LogLine) => {
+  if (!globalLogger) {
+    // Create a global logger with Pino enabled for the default logger
+    // but disable it in test environments
+    globalLogger = new StagehandLogger({
+      pretty: true,
+      // Let StagehandLogger auto-detect test environment and disable Pino if needed
+    });
+  }
+  globalLogger.log(logLine);
+};
+
 async function getBrowser(
   apiKey: string | undefined,
   projectId: string | undefined,
@@ -137,7 +153,7 @@ async function getBrowser(
         logger({
           category: "init",
           message: "failed to resume session",
-          level: 1,
+          level: 0,
           auxiliary: {
             error: {
               value: error.message,
@@ -196,7 +212,6 @@ async function getBrowser(
       message: browserbaseSessionID
         ? "browserbase session resumed"
         : "browserbase session started",
-      level: 0,
       auxiliary: {
         sessionUrl: {
           value: sessionUrl,
@@ -220,7 +235,6 @@ async function getBrowser(
     logger({
       category: "init",
       message: "launching local browser",
-      level: 0,
       auxiliary: {
         headless: {
           value: headless.toString(),
@@ -233,7 +247,6 @@ async function getBrowser(
       logger({
         category: "init",
         message: "local browser launch options",
-        level: 0,
         auxiliary: {
           localLaunchOptions: {
             value: JSON.stringify(localBrowserLaunchOptions),
@@ -361,10 +374,6 @@ async function applyStealthScripts(context: BrowserContext) {
   });
 }
 
-const defaultLogger = async (logLine: LogLine) => {
-  console.log(logLineToString(logLine));
-};
-
 export class Stagehand {
   private stagehandPage!: StagehandPage;
   private stagehandContext!: StagehandContext;
@@ -395,6 +404,8 @@ export class Stagehand {
   private cleanupCalled = false;
   public readonly actTimeoutMs: number;
   public readonly logInferenceToFile?: boolean;
+  private stagehandLogger: StagehandLogger;
+
   protected setActivePage(page: StagehandPage): void {
     this.stagehandPage = page;
   }
@@ -492,15 +503,31 @@ export class Stagehand {
     },
   ) {
     this.externalLogger = logger || defaultLogger;
+
+    // Initialize the Stagehand logger
+    this.stagehandLogger = new StagehandLogger(
+      {
+        pretty: true,
+        usePino: !logger, // Only use Pino if no custom logger is provided
+      },
+      this.externalLogger,
+    );
+
     this.enableCaching =
       enableCaching ??
       (process.env.ENABLE_CACHING && process.env.ENABLE_CACHING === "true");
+
     this.llmProvider =
       llmProvider || new LLMProvider(this.logger, this.enableCaching);
+
     this.intEnv = env;
     this.apiKey = apiKey ?? process.env.BROWSERBASE_API_KEY;
     this.projectId = projectId ?? process.env.BROWSERBASE_PROJECT_ID;
+
     this.verbose = verbose ?? 0;
+    // Update logger verbosity level
+    this.stagehandLogger.setVerbosity(this.verbose);
+
     this.debugDom = debugDom ?? false;
     if (llmClient) {
       this.llmClient = llmClient;
@@ -556,11 +583,15 @@ export class Stagehand {
       if (this.cleanupCalled) return;
       this.cleanupCalled = true;
 
-      console.log(`[${signal}] received. Ending Browserbase session...`);
+      this.stagehandLogger.info(
+        `[${signal}] received. Ending Browserbase session...`,
+      );
       try {
         await this.close();
       } catch (err) {
-        console.error("Error ending Browserbase session:", err);
+        this.stagehandLogger.error("Error ending Browserbase session:", {
+          error: String(err),
+        });
       } finally {
         // Exit explicitly once cleanup is done
         process.exit(0);
@@ -604,7 +635,7 @@ export class Stagehand {
     }
 
     if (initOptions) {
-      console.warn(
+      this.stagehandLogger.warn(
         "Passing parameters to init() is deprecated and will be removed in the next major version. Use constructor options instead.",
       );
     }
@@ -646,7 +677,7 @@ export class Stagehand {
         this.browserbaseSessionID,
         this.localBrowserLaunchOptions,
       ).catch((e) => {
-        console.error("Error in init:", e);
+        this.stagehandLogger.error("Error in init:", { error: String(e) });
         const br: BrowserResult = {
           context: undefined,
           debugUrl: undefined,
@@ -721,9 +752,8 @@ export class Stagehand {
   log(logObj: LogLine): void {
     logObj.level = logObj.level ?? 1;
 
-    if (this.externalLogger) {
-      this.externalLogger(logObj);
-    }
+    // Use our Pino-based logger
+    this.stagehandLogger.log(logObj);
 
     this.pending_logs_to_send_to_browserbase.push({
       ...logObj,

Diff for: lib/llm/AnthropicClient.ts

@@ -57,7 +57,7 @@ export class AnthropicClient extends LLMClient {
     logger({
       category: "anthropic",
       message: "creating chat completion",
-      level: 1,
+      level: 2,
       auxiliary: {
         options: {
           value: JSON.stringify(optionsWithoutImage),
@@ -241,7 +241,7 @@ export class AnthropicClient extends LLMClient {
     logger({
       category: "anthropic",
       message: "response",
-      level: 1,
+      level: 2,
       auxiliary: {
         response: {
           value: JSON.stringify(response),
@@ -293,7 +293,7 @@ export class AnthropicClient extends LLMClient {
     logger({
       category: "anthropic",
       message: "transformed response",
-      level: 1,
+      level: 2,
       auxiliary: {
         transformedResponse: {
           value: JSON.stringify(transformedResponse),
@@ -332,7 +332,7 @@ export class AnthropicClient extends LLMClient {
         logger({
           category: "anthropic",
           message: "error creating chat completion",
-          level: 1,
+          level: 0,
           auxiliary: {
             requestId: {
               value: options.requestId,