Skip to content
lzh博客

Logging

为 Stagehand 工作流配置日志、调试与错误跟踪。

文档索引

可在此获取完整文档索引：https://docs.stagehand.dev/llms.txt

在进一步浏览前，可使用该文件发现所有可用页面。

Logging

Section titled “Logging”

为 Stagehand 工作流设置日志、调试与错误跟踪

Stagehand 提供了全面的日志能力，帮助你调试自动化工作流、跟踪执行过程并诊断问题。你可以为开发与生产环境配置日志级别、结构化输出以及调试工具。

快速开始

Section titled “快速开始”

根据你的运行环境选择合适的日志配置：

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


const stagehand = new Stagehand({
  env: "LOCAL",
  verbose: 2,  // 完整调试输出
  // restOfYourConfiguration...
});

运行日志

Section titled “运行日志”

在自动化执行期间记录实时事件日志。

详细级别

Section titled “详细级别”

控制你希望在日志中看到的细节程度：

适用场景： 开发阶段、排查特定问题

const stagehand = new Stagehand({
  verbose: 2,  // 最详细
  // restOfYourConfiguration...
});
示例输出
[12:34:56] DEBUG: Capturing DOM snapshot
[12:34:57] DEBUG: DOM contains 847 elements
[12:34:58] DEBUG: LLM inference started
[12:34:59] DEBUG: LLM response: {"selector": "#btn-submit", "method": "click"}
[12:35:00] INFO: act completed successfully

日志输出目标

Section titled “日志输出目标”

日志可以发送到不同的目标，包括你的控制台以及外部可观测平台：

快速、结构化、带颜色的 JSON 日志器，并输出到控制台。

适用场景： 开发、预发布，或未接入外部可观测系统的生产环境；也适合管理多个 Stagehand 实例。

// 默认启用 —— Pino 会自动处理控制台输出
const stagehand = new Stagehand({
  verbose: 1,
  // restOfYourConfiguration...
});
以下情况下会自动禁用
  • process.env.NODE_ENV === "test"
  • process.env.JEST_WORKER_ID !== undefined（Jest 测试）
  • process.env.PLAYWRIGHT_TEST_BASE_DIR !== undefined（Playwright 测试）
  • process.env.CI === "true"（CI/CD 环境）

为什么会自动禁用？ Pino 会使用 worker threads 做美化输出，这在测试运行器中可能导致问题。

基于文件的会话日志

Section titled “基于文件的会话日志”

通过设置配置目录，你可以为所有 Stagehand 操作启用详细的基于文件的日志记录。这会为 agent.execute、act、observe、extract、CDP 事件以及 LLM 请求/响应创建完整日志。

设置方法

Section titled “设置方法”

将以下内容加入你的 shell 配置文件（如 ~/.zshrc、~/.bashrc 等）：

Terminal window
export BROWSERBASE_CONFIG_DIR=~/.config/browserbase

然后重新加载 shell，或执行 source ~/.zshrc。

使用方式

Section titled “使用方式”

像平时一样运行你的 Stagehand 脚本：

Terminal window
tsx run_some_script_that_imports_stagehand.ts

日志会写入 ~/.config/browserbase/sessions/<session-id>/，其中 latest 符号链接会指向最近一次会话。

查看日志

Section titled “查看日志”

跟随查看所有日志的实时输出：

Terminal window
tail -f ~/.config/browserbase/sessions/latest/*.log

或者只观察特定类型的日志：

Terminal window
# 仅查看 LLM 请求与响应
tail -f ~/.config/browserbase/sessions/latest/llm_events.log


# 仅查看 CDP（Chrome DevTools Protocol）事件
tail -f ~/.config/browserbase/sessions/latest/cdp_events.log

日志文件

Section titled “日志文件”

每个会话目录都包含以下文件：

文件内容
llm_events.logact、extract、observe 以及 agent 操作的 LLM 请求与响应
cdp_events.logChrome DevTools Protocol 调用与事件
stagehand.log通用 Stagehand 操作与状态变化

LLM 推理调试

Section titled “LLM 推理调试”

警告

仅限开发环境 —— 会生成较大的文件，并且其中包含页面内容。请勿在生产环境中使用。

将完整的 LLM 请求/响应转储保存到磁盘，便于离线分析。你可以准确查看发送给 LLM 的 DOM 内容，以及它为何选错元素。

const stagehand = new Stagehand({
  env: "LOCAL",
  verbose: 2,
  logInferenceToFile: true,  // 将文件写入 ./inference_summary/
});

每次 LLM 调用都会生成带时间戳的文件：

./inference_summary/
├── act_summary/
│   ├── act_summary.json                      # 汇总指标
│   ├── 20250127_123456_act_call.txt          # LLM 请求
│   ├── 20250127_123456_act_response.txt      # LLM 响应
│   ├── 20250127_123501_act_call.txt
│   └── 20250127_123501_act_response.txt
├── extract_summary/
│   ├── extract_summary.json
│   ├── 20250127_123510_extract_call.txt
│   ├── 20250127_123510_extract_response.txt
│   ├── 20250127_123511_metadata_call.txt
│   └── 20250127_123511_metadata_response.txt
└── observe_summary/
    ├── observe_summary.json
    └── ...

文件类型：

调用文件（Call File）

包含完整的 LLM 请求：

{
  "modelCall": "act",
  "messages": [
    {
      "role": "system",
      "content": "You are a browser automation assistant. You have access to these actions:\n- click\n- type\n- scroll\n..."
    },
    {
      "role": "user",
      "content": "Click the sign in button\n\nDOM:\n<html>\n  <body>\n    <button id=\"btn-1\">Sign In</button>\n    <button id=\"btn-2\">Sign Up</button>\n  </body>\n</html>"
    }
  ]
}
响应文件（Response File）

包含 LLM 的输出：

{
  "modelResponse": "act",
  "rawResponse": {
    "selector": "#btn-1",
    "method": "click",
    "reasoning": "Found sign in button with ID btn-1"
  }
}
汇总文件（Summary File）

汇总所有调用及其指标：

{
  "act_summary": [
    {
      "act_inference_type": "act",
      "timestamp": "20250127_123456",
      "LLM_input_file": "20250127_123456_act_call.txt",
      "LLM_output_file": "20250127_123456_act_response.txt",
      "prompt_tokens": 3451,
      "completion_tokens": 45,
      "inference_time_ms": 951
    },
    {
      "act_inference_type": "act",
      "timestamp": "20250127_123501",
      "LLM_input_file": "20250127_123501_act_call.txt",
      "LLM_output_file": "20250127_123501_act_response.txt",
      "prompt_tokens": 2890,
      "completion_tokens": 38,
      "inference_time_ms": 823
    }
  ]
}

参考

Section titled “参考”

日志配置

Section titled “日志配置”

所有日志选项都通过 Stagehand 构造函数传入：

const stagehand = new Stagehand({
  // ... 其他配置（env、model 等）


  // 日志选项：
  verbose?: 0 | 1 | 2;                   // 日志级别（默认：1）
  logger?: (line: LogLine) => void;      // 外部日志器函数
  disablePino?: boolean;                 // 禁用 Pino 后端（默认：false）
  logInferenceToFile?: boolean;          // 将 LLM 请求保存到磁盘（默认：false）
});
选项默认值说明
verbose1日志级别：0 = 仅错误，1 = 信息，2 = 调试
loggerundefined用于外部平台的自定义日志函数
disablePinofalse禁用 Pino（测试环境中会自动为 true）
logInferenceToFilefalse将 LLM 请求保存到磁盘

日志结构

Section titled “日志结构”

每条日志都遵循统一的结构化格式：

interface LogLine {
  message: string;              // "act completed successfully"
  level?: 0 | 1 | 2;            // error | info | debug
  category?: string;            // "action", "llm", "browser", "cache"
  timestamp?: string;           // ISO 8601 时间戳
  auxiliary?: {                 // 附加的结构化元数据
    [key: string]: {
      value: string;            // 序列化后的值
      type: "object" | "string" | "integer" | "float" | "boolean";
    };
  };
}
日志示例 
{
  "category": "action",
  "message": "act completed successfully",
  "level": 1,
  "timestamp": "2025-01-27T12:35:00.123Z",
  "auxiliary": {
    "selector": {
      "value": "#btn-submit",
      "type": "string"
    },
    "executionTime": {
      "value": "1250",
      "type": "integer"
    }
  }
}

下一步

Section titled “下一步”

现在你已经完成日志配置，可以继续查看更多调试与监控工具，详见可观测性指南：

History API

跟踪所有 LLM 操作（act、extract、observe、agent），包括参数、结果与时间戳。非常适合调试操作序列以及回放工作流。

Metrics API

实时监控 token 使用量与性能。跟踪每次操作的成本，识别高开销调用，并优化资源使用。

LLM Inference Debugging

将完整的 LLM 请求/响应转储保存到磁盘。准确查看发送给 LLM 的 DOM，以及它为何做出特定决策。

Browserbase Session Monitoring

通过会话录制、网络监控和实时浏览器检查，以可视化方式观察你的自动化流程（仅 Browserbase）。

-
0:000:00
Blog Docs Books About
概览

First Steps

Introduction Quickstart Installation AI Rules

The Basics

Agent Act Extract Observe Evals

Configuration

Browser Observability Logging Models

Best Practices

Caching Actions Cost Optimization Deterministic Agent Using Multiple Tabs Deploying Stagehand History Tracking Computer Use Agents Agent Fallbacks Prompting Best Practices MCP Integrations Speed Optimization

Integrations

Playwright Puppeteer Selenium