brd-browser-debug

Bright Data — 浏览器会话调试器

使用 Browser Sessions API 诊断 Bright Data Scraping Browser 会话。获取实时会话数据并进行智能分类：错误诊断、带宽分析、验证码报告，以及检测近期会话中的模式。

设置

设置你的 API 密钥：

export BRIGHTDATA_API_KEY="your-api-key"

从 Bright Data 控制面板 → API 令牌获取密钥。

无需配置 zone——zone 会作为字段包含在会话数据中。

用法

列出近期会话并进行分类

不带参数调用 /brd-browser-debug。

API 参考： GET /browser_sessions

获取会话

首先进行一次调用，使用 limit=100（最大值），并按时间从近到远排序：

GET https://api.brightdata.com/browser_sessions?limit=100&sort=timestamp&order=desc
Authorization: Bearer $BRIGHTDATA_API_KEY

分页： 响应包含 total、has_more 和 next_offset。如果 has_more 为 true，且分析需要更多数据（例如，检测带宽异常值需要更大的样本），则使用 offset=<next_offset> 获取下一页。继续获取，直到数据足够或 has_more 为 false。

可用筛选条件——当用户指定范围时应用：

• status=failed|finished|running — 筛选特定会话状态
• api_name=<zone> — 筛选特定 Bright Data zone
• target_url=<domain> — 按目标域名筛选（例如 ksp.co.il）
• start_date / end_date — ISO 8601 日期时间范围
• sort=timestamp|duration|bandwidth，搭配 order=asc|desc

如果用户询问特定 zone、日期范围或域名，请应用相应筛选条件，而不是获取所有会话后再在客户端进行筛选。

分类步骤

1. 提供健康状况摘要：响应中的 total，以及已完成 / 失败 / 正在运行的会话数。
2. 最新会话——无论状态如何，始终重点说明（详细程度与单会话模式相同）。
3. 失败的会话——针对每次失败，列出会话 ID、时间戳、持续时间和带宽，然后依据下文“诊断失败会话”部分的信号推断原因。
4. 模式检测——如果有 3 个或更多会话共享相同的 error.code，则判定为系统性问题：

   “有 3 个会话因 custom_headers 失败——你覆盖了 Bright Data 禁止修改的标头。请从代码中移除 page.setExtraHTTPHeaders()。”

5. 带宽异常值——按 target_url 域名对会话分组。对于会话数达到 3 个或更多的每个域名，计算带宽中位数。将带宽超过该域名中位数 2 倍的会话标记为异常值，并注明该会话是否失败，以及在结束前是否消耗了异常高的带宽。
6. 验证码活动——报告遇到验证码的会话数，以及验证码是否已解决。
7. 最后给出一句话结论：最重要的发现和影响最大的修复措施。

检查单个会话

调用方式为 /brd-browser-debug <session_id>。

API 参考： GET /browser_sessions/{session_id}

1. 调用：

   GET https://api.brightdata.com/browser_sessions/<session_id>
   Authorization: Bearer $BRIGHTDATA_API_KEY
   

   如果未找到会话 ID，则返回 404 — 告知用户并停止。

2. 使用响应字段进行深入分析：

   • 状态（status）：running / finished / failed
   • 区域（api_name）：处理该会话的 Bright Data 区域
   • 时间戳（timestamp）：ISO 8601 格式 — 以便于本地阅读的格式显示
   • 时长（duration）：秒（可为 null）— 如果失败时小于 2 s，则标记（会话几乎尚未启动）
   • 带宽（bandwidth）：将字节转换为 MB
   • 导航次数（navigations）：如果为 0，则标记（未加载任何内容）
   • 验证码（captcha）：solved / none / detected / failed 之一 — detected 表示出现了挑战，但未解决；failed 表示尝试解决但未成功
   • 路由：target_url → end_url — 标记明显偏离的情况（不同域名、登录墙、错误页面）
   • 错误（error.code + error.message）：使用下方“诊断失败会话”中的信号推断原因

3. 以一行结论收尾。

根据对话上下文自动检测

当对话中出现 Bright Data 浏览器问题时 — 包括 puppeteer 堆栈跟踪、错误代码、提及 brd.superproxy.io、用户描述会话失败，或爬虫返回空结果／非预期结果（例如“找到 0 个类别”“获取到 0 个商品”或条目数少于预期）：

• 如果输出中能看到会话 ID → 对其进行单会话深入分析。
• 如果输出中看不到会话 ID → 列出并分类处理，按相关目标域名筛选。将最新的会话标记为最可能的原因。
• 将对话中出现的错误或异常行为与 API 返回结果交叉核对。若会话成功结束且带宽正常，但爬虫获取到 0 条结果，则问题可能出在客户端选择器／提取逻辑，而非代理。

功能

• 智能分类处理：按失败模式自动对会话分组，而非仅列出会话
• 动态带宽异常值检测：按域名比较会话，并标记超过中位数 2 倍的会话
• 验证码报告：显示验证码命中率和解决率
• 错误推断：综合分析会话信号，推断问题所在
• 零配置：从环境变量读取 API 密钥，无需配置区域

诊断失败会话

不要仅凭错误代码判断。请交叉核对所有可用的会话信号，以推断问题所在：

• 时长 + 导航次数：如果会话在小于 2 s 时失败且导航次数为 0，则说明未能通过连接阶段 — 可能是配置或身份验证问题。如果会话运行数分钟后才失败，则说明可能是运行时问题（抓取过程中被拦截、空闲超时、网络中断）。
• 与其他会话相比的带宽：失败会话消耗的带宽与成功会话相近，说明可能已到达目标，但在提取过程中失败。带宽接近零的失败会话则未能加载任何内容。
• 验证码字段：如果 captcha 为 detected 但未能解决，则会话因未解决的挑战而停止 — 建议在该区域启用验证码解决功能。
• target_url 与 end_url：明显偏离（不同域名、登录页面、错误页面）表示会话被重定向到预期目标之外。
• error.message：使用原始消息文本描述发生的情况 — 不要超出消息内容进行猜测或臆造。如果原因不明确，请引导用户联系 Bright Data 支持。