Skip to main content

Documentation Index

Fetch the complete documentation index at: https://stagehand-shrey-check-v3-metrics-docs.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

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

  • 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