superlog-debug

Superlog 生产环境调试

当用户正在调查生产环境中发生的问题时，先查询他们的实际遥测数据，再分析代码。Superlog 会采集用户各项服务的 OpenTelemetry 跟踪、日志和指标——对于“这个 500 错误为什么会发生？”/“这次部署正常吗？”/“发生了什么变化？”这类问题，答案几乎总在其中。

何时启用

一旦用户表示正在了解生产环境的实际运行情况，就立即启用。例如：

• “用户无法登录”/“结账功能出问题了”/“生产环境中一直返回 500 错误”
• “这次部署正常吗？”/“我的 PR 有没有导致回归？”
• “/api/foo 现在的 p95 是多少？”/“过去一小时有多少错误？”
• “worker 昨晚的运行情况如何？”
• 事件频道消息、Sentry/PagerDuty 链接、值班通知。

以下情况无需启用：

• 工作仅限本地（工作树开发、测试、类型错误、lint）。
• 用户已粘贴相关日志/跟踪/span。
• 问题纯粹是在问“这段代码的结构是怎样的？”，与生产环境无关。

前提条件：必须安装 Superlog MCP

以下工具由 Superlog MCP 服务提供。如果当前 Agent 无法使用这些工具，请先安装。

对于 Claude Code：

claude mcp add --transport http superlog https://api.superlog.sh/mcp

对于 Codex：

codex mcp add superlog --url https://api.superlog.sh/mcp
codex mcp login superlog

对于 Cursor 和其他客户端：从 https://superlog.sh/ → Connect 复制 mcpServers 代码段。

安装后，重启 Agent，并通过 MCP 首次使用时触发的 OAuth 流程进行身份验证。

每个会话的首次调用

superlog.get_active_project

如果这不是用户正在调试的项目，请切换项目：

superlog.list_projects
superlog.set_active_project { project_id: "<id>" }

你也可以在任何单次调用中传入 project_id，而不更改会话状态。如果用户将多个环境配置为独立项目（例如 prod 和 staging），请在查询前确认要查询哪个环境。

工具速查

所有查询工具默认使用当前项目和最近 1 小时的数据。使用 range: { since, until } 覆盖范围——两者都接受 ISO-8601（"2026-05-28T14:00:00Z"）或 ClickHouse 表达式（"now() - INTERVAL 30 MINUTE"）。

工具	用途
superlog.list_services	确认所选时间范围内哪些服务发送了遥测数据
superlog.query_logs	搜索日志正文；按 service、severity、resource_attrs、log_attrs 筛选
superlog.query_traces	查找耗时较长或出错的 span；按 service、span_name、min_duration_ms、status_code、span_attrs 筛选
superlog.query_metrics	按 metric_name + service 获取近期指标数据点
superlog.list_alerts / get_alert	检查是否已有现成告警覆盖用户遇到的问题
superlog.list_dashboards / get_dashboard	从头构建查询前，先查找受影响功能现有的仪表板

query_logs 提示

• severity 会以不区分大小写的方式匹配存储的 OTel severity 文本。请使用 SDK 实际输出的简写形式——"ERROR"、"WARN"、"INFO"、"DEBUG"——不要使用 "WARNING"，因为存储的文本是 WARN，因此不会匹配任何内容。请积极筛选——事件期间通常从仅筛选错误开始最合适。
• search 会对日志正文进行不区分大小写的子字符串匹配。成本低、效果好，适合查找堆栈跟踪或特定消息。
• log_attrs 筛选每条记录的属性（例如 event.name、应用为每条日志设置的自定义结构化字段）。
• resource_attrs 筛选 OTel 资源中的服务级别属性（例如 deployment.environment.name=production、service.version=1.42.0）。请使用当前的 OTel semconv 键——deployment.environment.name 已取代旧的 deployment.environment，近期 SDK 上的应用只会输出新键。每个条目还接受可选的 op，值为 eq（默认值）、neq 或 not_contains。
• 响应会为每条日志包含一个 resource_attrs 映射，因此无需再次调用，就能从结果中读取服务、环境和版本信息。
• 在任何 span 之外输出的日志，其 trace_id / span_id 字符串将为空——这是预期行为，不是 bug。不要仅仅因为部分日志缺少 trace 上下文，就断定 trace 管道出了问题。

query_traces 提示

• HTTP 状态码位于 span_attrs 中，而不是 status_code 中。 OTel 的 status_code 表示语义上的 OK/ERROR/UNSET；根据 OTel HTTP semconv，只有 5xx 服务器响应会自动将 span 标记为 ERROR。要查找 4xx 响应，请使用：

  span_attrs: [{ key: "http.response.status_code", value: "404" }]
  

• status_code 筛选器接受枚举形式（STATUS_CODE_OK、STATUS_CODE_ERROR、STATUS_CODE_UNSET），但响应中每个 span 返回的值是标题大小写形式（"Ok"、"Error"、"Unset"）——不要尝试将响应值与枚举进行相等匹配。

• 要查找“耗时较长的 X 请求”，请使用 service + span_name + min_duration_ms: 1000。

• 要按路由筛选，请使用带有 http.route 的 span_attrs（模板，例如 /api/users/:id）——不要使用基数较高的原始 URL。

• 对数据库调用，请按指向 DB 主机的类 HTTP 客户端 span 筛选，或者按 db.system 筛选（如果应用的检测会输出该属性；部分 SDK 不会输出——请先检查示例 span 的 span_attrs）。

• 每个返回的 span 都包含 span_attrs 和 resource_attrs，因此可以直接从结果中读取服务版本、环境和实例信息。

query_metrics 提示

• 始终传入 metric_name（通常也传入 service）。不传这些参数也能调用，但会返回最近写入的任意数据，这通常不是你想要的。
• 每个返回的数据点都包含 kind（gauge/sum/histogram/summary）、metric_name、unit、service，以及每个数据点的 attributes（序列维度——路由、状态、租户等）和 resource_attrs。请使用 attributes 来区分数据点所属的序列。
• gauge/sum 数据点带有标量 value。histogram/summary 数据点没有标量值：它们带有 count 和 sum（直方图还带有 min/max）。因此，对于直方图，平均值 = sum / count，而 value 为 null——这是预期行为，请读取 count/sum/min/max。
• 要计算速率，请在两个时间窗口内获取底层计数器，然后自行计算差值，不要指望 MCP 为你计算。要计算延迟百分位数，请构建仪表板小组件（仪表板查询层会重建直方图分位数）；原始 query_metrics 数据点不会直接提供 p95。

调查手册

“现在生产环境中的 X 是否发生故障？”

1. 使用过去 30 分钟的 list_services 查询：该服务是否有数据上报？没有数据本身也是一种信号。
2. 使用 query_logs 查询过去 30 分钟的数据，参数为 service: "<svc>"、severity: "ERROR"。逐字引用一条示例堆栈跟踪给用户。
3. 使用 query_traces 查询，参数为 service: "<svc>"、status_code: "STATUS_CODE_ERROR"，和／或通过 span_attrs 筛选 http.response.status_code，以捕获 4xx 错误。
4. 如果错误集中在某个路由上，拉取该路由最近耗时最长的跟踪，并查看失败操作的 SpanAttributes（数据库语句、下游 URL、异常消息）。

“这个端点很慢”

1. 使用 query_traces 查询，指定 service，再指定 span_name 或 span_attrs: [{ key: "http.route", value: "/api/foo" }]，并设置 min_duration_ms: 1000，查询过去 1 小时的数据。
2. 按耗时对跨度排序／目测，并展开 span_attrs（以及用于查看服务版本／环境的 resource_attrs）。留意：耗时很长的数据库调用（耗时较长，且 http.host 指向数据库，或设置了 db.system）、下游 HTTP 扇出、队列等待。
3. 如果找到耗时较长的子操作，直接按该跨度名称重新查询，查看它是普遍缓慢，还是仅在此路由上缓慢。

“我的部署是否导致了回归？”

1. 记下部署时间戳（如果不明显，请询问用户）。
2. 使用 query_logs，针对受影响的服务查询 severity: "ERROR"，分别覆盖部署前后两个等长时间窗口。比较数量和唯一错误特征。
3. 使用 query_metrics 查询两个时间窗口内的请求速率、错误率和延迟指标。
4. 使用 query_traces 查询部署后的 status_code: "STATUS_CODE_ERROR"。如果应用会标记发布版本，可通过 resource_attrs: [{ key: "service.version", value: "<new-version>" }] 限定范围。返回的跨度包含 resource_attrs，因此你可以确认每个错误由哪个版本产生。

“这个服务昨晚在做什么？”

1. 使用隔夜时间范围的 list_services 确认服务是否持续上报数据。
2. 先使用 query_logs 查询该时间窗口内 severity: "ERROR" 的日志，再查询 severity: "WARN" 的日志，查看是否存在聚集现象和时段规律。
3. 使用 query_metrics 查询该服务的关键业务计数器，发现下降或激增情况。

“用户是否正在访问这段代码路径？”

1. 使用 query_traces 查询，指定 service 和 span_name（或通过 span_attrs 按 feature.flag 或 tenant.id 等自定义业务属性筛选）。
2. 如果计数为零，请对照源代码仔细核对跨度名称和属性键——这里的拼写错误是导致误报的头号原因。

输出规范

• 先给出发现，不要先讲方法。“过去 15 分钟内，api 中有 47 条 ERROR 日志，全部是来自 db.query 的 TimeoutError”，比用一段话说明调用了哪些工具更好。
• 引用真实证据：时间戳、跟踪 ID、跨度 ID、准确的错误消息。用户应能根据这些信息在 Superlog UI 中进一步查看。
• 说明时间窗口：“过去 30 分钟”／“自 14:00 UTC 起”。不说明时间窗口的发现无法采取行动。
• 区分零和未知。“没有匹配的跨度”意味着查询已运行但没有返回结果——请明确说明。“我无法查询，因为当前项目不是该服务所属的项目”是另一回事；请如实说明。
• 不要过度给出建议。如果遥测数据显示服务运行正常，就直接说明，然后停止。不要为了显得忙碌而硬凑“下一步”。

与其他上下文配合

Superlog MCP 只能看到用户的应用通过 OpenTelemetry 导出的内容。它看不到：

• 数据库的行级状态——直接查询数据库（如果已安装 Postgres/MySQL MCP，也可以通过它查询）。
• 未进入 OTel 管道的云服务提供商主机／容器日志（CloudWatch、GCP Logging、Fly 日志、Railway 日志等）。
• 队列深度（SQS、RabbitMQ，……），除非应用明确为其发出指标。
• 应用从未进行插桩的任何内容。

如果 MCP 未返回某个服务的任何内容，不要据此断定该服务没有活动——先检查遥测是否确实到达了接收端。即使服务仍在运行，且主机层有大量活动，缺失或配置错误的导出器、错误的 service.name，或项目不匹配的接收密钥，都可能导致“MCP 什么也看不到”。如果用户需要修复安装配置，superlog-onboard 技能会介绍安装方面的内容。

有一种特定故障需要优先排查：**每个接收请求都返回 401，尽管令牌有效。**这是因为令牌使用了错误的请求头名称。接收端只会从 x-api-key: <token> 或 Authorization: Bearer <token> 中读取令牌（必须包含字面前缀 Bearer ）；其他任何形式——api-key、x-superlog-token，或不带 Bearer 的 Authorization: <token>——都会导致每个请求都返回 401，因此看起来像是安装损坏，实际上密钥没有问题。要独立于应用的导出器配置，快速确认密钥是否有效：

curl -i -X POST https://intake.superlog.sh/v1/traces \
  -H "x-api-key: sl_public_..." \
  -H "content-type: application/json" --data '{"resourceSpans":[]}'
# 2xx → key is valid; the app is sending the wrong header. Fix the exporter to use x-api-key.
# 401 → the token itself is wrong/revoked.

硬性规则

• 默认只读。query_* 和 list_* 调用是安全的。create_alert、update_dashboard、delete_* 等操作会修改用户账户——除非用户明确要求，否则绝不调用；即使用户明确要求，也要先确认具体更改。
• **不要在聊天中复述 span／日志属性中出现的完整接收令牌或密钥。**如必须提及，请截断。
• **不要悄悄切换当前项目。**如果调用 set_active_project，请告知用户你已执行该操作及其原因。
• **问题问多深，就回答多深。**用户问“生产环境正常吗？”，想要的是 2 行回答，而不是全面执行 12 次查询。只有调查需要时才深入。