Stagehand provides comprehensive logging capabilities to help you debug automation workflows, track execution, and diagnose issues. Configure logging levels, structured output, and debugging tools for both development and production environments.

​
Logging Configuration

import { Stagehand } from "@browserbasehq/stagehand";

const stagehand = new Stagehand({
  env: "BROWSERBASE", // or "LOCAL"
  verbose: 1, // 0 = errors only, 1 = info, 2 = debug
});

​
Verbose Levels

  • Level 0: Errors only - minimal output for production
  • Level 1: Info - includes successful operations and important events
  • Level 2: Debug - comprehensive logging including internal operations

​
Structured Logging

​
Log Line Format

Each log entry contains structured information: 
interface LogLine {
  category: 'browser' | 'action' | 'llm' | 'error' | 'stagehand' | 'cache';
  message: string;
  level: 0 | 1 | 2; // error | info | debug
  timestamp: string;
  auxiliary?: {
    executionTime?: { value: string; unit: string };
    sessionId?: string;
    url?: string;
    [key: string]: any;
  };
}

​
Custom Logger

class AdvancedLogger {
  private logFile?: string;
  
  constructor(logFile?: string) {
    this.logFile = logFile;
  }
  
  log = (logLine: any) => {
    const timestamp = new Date().toISOString();
    const colors = {
      browser: '\x1b[34m', // blue
      action: '\x1b[32m',  // green
      llm: '\x1b[35m',     // magenta
      error: '\x1b[31m',   // red
      stagehand: '\x1b[36m', // cyan
      cache: '\x1b[33m',   // yellow
    };
    
    const color = colors[logLine.category] || '\x1b[0m';
    const reset = '\x1b[0m';
    
    // Console output with colors
    console.log(`${color}[${logLine.category}]${reset} ${logLine.message}`);
    
    // Log execution time if available
    if (logLine.auxiliary?.executionTime) {
      console.log(` ${logLine.auxiliary.executionTime.value}${logLine.auxiliary.executionTime.unit}`);
    }
    
    // Log additional context
    if (logLine.auxiliary && Object.keys(logLine.auxiliary).length > 0) {
      console.log('  Context:', JSON.stringify(logLine.auxiliary, null, 2));
    }
    
    // File logging (optional)
    if (this.logFile) {
      const logEntry = {
        timestamp,
        ...logLine
      };
      require('fs').appendFileSync(this.logFile, JSON.stringify(logEntry) + '\n');
    }
  }
}

// Usage
const logger = new AdvancedLogger('./automation.log');
const stagehand = new Stagehand({
  env: "BROWSERBASE",
  verbose: 2,
  logger: logger.log
});

​
Detailed Logging Features

​
LLM Inference Logging

Enable detailed logging of all LLM interactions: 
const stagehand = new Stagehand({
  env: "BROWSERBASE",
  logInferenceToFile: true,  // Creates inference_summary/ directory
  verbose: 2
});
The inference_summary/ directory structure: 
inference_summary/                   
├── act_summary/            
│   ├── 20240329_080446068.json    
│   ├── 20240329_080447019.json   
│   └── act_summary.json          
├── extract_summary/               
│   ├── 20240329_081205123.json    
│   └── extract_summary.json       
└── observe_summary/                
    ├── 20240329_081634891.json    
    └── observe_summary.json

​
Log Analysis & Debugging

​
Common Log Patterns

{
  "category": "action", 
  "message": "act completed successfully",
  "level": 1,
  "auxiliary": {
    "executionTime": {"value": "1250", "unit": "ms"},
    "url": "https://example.com",
    "sessionId": "session-123"
  }
}

​
Best Practices