Skip to main content
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

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

​
Best Practices

  • Use verbose: 2 with visual debugging
  • Enable browser DevTools for element inspection
  • Use logInferenceToFile: true to capture LLM decisions
  • Implement structured logging early
  • Use verbose: 1 to balance visibility with performance
  • Implement error tracking and alerting
  • Use structured JSON logging
  • Monitor session success rates and execution times
  • Never log credentials or sensitive data
  • Implement log retention policies
  • Secure log files and dashboards
⌘I