observability

可观测性技能

使用 OpenTelemetry、控制台日志、网络请求和分布式追踪监控与调试 Web 和 Node.js 应用程序。

使用时机

满足以下情况时会启用此技能：

• 用户询问分布式追踪
• 用户希望关联前端和后端请求
• 用户提到 OpenTelemetry、Jaeger、Zipkin 或追踪
• 用户需要调试跨服务的请求流
• 用户希望监控应用程序行为

功能

分布式追踪

browser-devtools-cli o11y get-trace-id
browser-devtools-cli o11y new-trace-id
browser-devtools-cli o11y set-trace-id --trace-id "abc123def456..."

控制台监控

browser-devtools-cli o11y get-console-messages
browser-devtools-cli --json o11y get-console-messages --type warning
browser-devtools-cli --json o11y get-console-messages --search "error"

网络可观测性

browser-devtools-cli --json o11y get-http-requests
browser-devtools-cli --json o11y get-http-requests --resource-type fetch
browser-devtools-cli --json o11y get-http-requests --status '{"min":400}'

性能指标

browser-devtools-cli --json o11y get-web-vitals
browser-devtools-cli --json o11y get-web-vitals --wait-ms 3000
browser-devtools-cli --json o11y get-web-vitals --include-debug

OpenTelemetry 集成

追踪上下文

Browser DevTools MCP 可以注入和提取 W3C Trace Context 标头：

• traceparent：包含 trace-id、span-id 和追踪标志
• tracestate：供应商专属的追踪信息

关联流程

Browser Session
    │
    ├─► trace-id: abc123
    │
    ▼
Frontend Request
    │
    ├─► Header: traceparent: 00-abc123-def456-01
    │
    ▼
Backend Service
    │
    ├─► Logs with trace-id: abc123
    │
    ▼
Observability Platform
    │
    └─► Full trace visualization

后端可观测性（node-devtools-cli）

将前端追踪与后端行为关联时，使用 node-devtools-cli 检查 Node.js 进程：

# Connect to backend
node-devtools-cli --session-id backend debug connect --pid 12345

# Get console logs from Node process (can correlate with trace ID in logs)
node-devtools-cli --session-id backend --json debug get-logs
node-devtools-cli --session-id backend --json debug get-logs --search "trace"

# Optional: set tracepoints on backend handlers to capture call context
node-devtools-cli --session-id backend debug put-tracepoint \
  --url-pattern "routes/api.ts" \
  --line-number 25

调试工作流

SESSION="--session-id trace-session"

# 1. Generate new trace ID
browser-devtools-cli $SESSION o11y new-trace-id

# 2. Navigate (requests will carry trace ID)
browser-devtools-cli $SESSION navigation go-to --url "https://app.example.com"
browser-devtools-cli $SESSION sync wait-for-network-idle

# 3. Perform actions
browser-devtools-cli $SESSION interaction click --selector "#submit"
browser-devtools-cli $SESSION sync wait-for-network-idle

# 4. Get trace ID for backend correlation
browser-devtools-cli $SESSION o11y get-trace-id

# 5. Check console errors
browser-devtools-cli $SESSION --json o11y get-console-messages --type error

# 6. Check network requests
browser-devtools-cli $SESSION --json o11y get-http-requests

# 7. Cleanup
browser-devtools-cli session delete trace-session

使用现有追踪 ID

SESSION="--session-id trace-session"

# Set trace ID from backend
browser-devtools-cli $SESSION o11y set-trace-id --trace-id "abc123def456789..."

# Navigate (requests will use this trace ID)
browser-devtools-cli $SESSION navigation go-to --url "https://app.example.com"

# All subsequent requests carry the trace ID
browser-devtools-cli $SESSION interaction click --selector "#api-call"

配置

环境变量

变量	描述	默认值
OTEL_ENABLE	启用 OpenTelemetry	false
OTEL_SERVICE_NAME	服务标识符	frontend
OTEL_EXPORTER_TYPE	导出目标	none
OTEL_EXPORTER_HTTP_URL	收集器端点	-
OTEL_EXPORTER_HTTP_HEADERS	身份验证标头	-

导出器类型

类型	描述
none	已禁用
console	输出到控制台
otlp/http	发送到 OTLP 收集器

常见平台

Jaeger

OTEL_EXPORTER_HTTP_URL=http://localhost:4318

Grafana Tempo

OTEL_EXPORTER_HTTP_URL=http://tempo:4318

Honeycomb

OTEL_EXPORTER_HTTP_URL=https://api.honeycomb.io
OTEL_EXPORTER_HTTP_HEADERS=x-honeycomb-team=YOUR_API_KEY

Datadog

OTEL_EXPORTER_HTTP_URL=http://localhost:4318

最佳实践

1. 为每个测试场景生成新的追踪 ID
2. 在错误报告中记录追踪 ID
3. 先检查控制台中的 JavaScript 错误
4. 筛选相关端点的网络请求
5. 关联前端和后端的时间戳
6. 使用包含追踪上下文的结构化日志
7. 设置 OTEL 导出器以全面查看追踪