企业官网建设流程全解析

• 人工智能
• AI 技能
• AI 插件
• 开发工具

导读

当你在代码里看到一段防御性逻辑、一个被硬编码的阈值（如“clamp 到 100”）或一次重试策略时，最自然的疑问是：“这段代码为什么要这样写？”答案往往不在源码里，而在代码落地那一刻的生产环境中。本文以 pstack 的why技能中 datadog.md 源文档为主体，系统讲解如何把 Datadog 当作“基础设施可观测性证据源”，通过监控指标、Dashboard、APM Trace、日志、事故记录等遥测数据，还原代码被写出来时的生产现实，从而推断其设计动机。读完本文，你将掌握一套完整的 Datadog MCP 检索路径、证据判定标准与常见陷阱规避方法，并了解它在 pstack 并行调查体系中的角色定位。

Datadog 在why技能中的定位

pstack 是一个面向 Claude Code、Codex 等 Agent 运行时的技能栈。其中why技能（见 SKILL.md）专门回答“代码为什么是现在这个样子”一类问题——设计理由、权衡、触发它的边界场景、外部约束或废弃代码的历史成因。

why技能的默认姿势是并行派生子 Agent（investigator），每个 investigator 只负责一类证据源：

类别索引见 source-playbook.md。Datadog 对应的就是“基础设施可观测性”这一类：当目标代码在响应超时、重试、限流、熔断等基础设施信号时，这个来源往往藏着真正的动机。

从源码结构看，investigator 的提示词由 investigator-prompt.md 模板拼装而成：模板给出通用调查纪律，再追加与证据类别匹配的单一 playbook 文件——即本文主角datadog.md。也就是说，这份文档在真实调查流程中会原样进入 Datadog investigator 的上下文，成为它的操作手册。

Datadog 里有什么：七类可当证据的遥测资产

datadog.md开篇就点明 Datadog 的核心价值：它保存的是运行时记录——生产环境里实际发生过什么，而不是计划或讨论过什么。这种“现实 vs 计划”的对比，正是它区别于工单、文档、聊天记录的证据价值所在。

文档列出了七类可检索的遥测资产：

• Metrics（指标）。团队埋点的计数器、Gauge、直方图。文档特别强调：一个指标的存在本身就是证据——有人觉得这个数字值得被盯着看。
• Monitors & alerts（监控与告警）。团队决定“值得半夜把人叫醒”的条件。例如一个在rate_limit_hit > 10/min时触发的监控，直接证明团队担心过这个阈值。
• Dashboards（仪表盘）。人工编排的视图，图表揭示团队认为某个子系统里什么重要。
• APM traces & spans（链路追踪）。请求级运行时数据，回答“为什么这么慢”“为什么这里超时”。
• Logs（日志）。高吞吐事件记录，常常包含促使防御性代码诞生的错误条件。
• Incidents（事故记录）。带时间线的正式事故档案，以及链接的事后复盘（postmortem）。
• Notebooks（笔记本）。探索性调查记录，常含假设与分析。

一句话总结这份证据源的“为什么”价值：Datadog 回答“代码被写出来时，生产现实是什么样”，而这往往解释了代码为什么会是现在这个形状。例如代码里频繁出现的空值检查、重试逻辑、超时处理、限流保护，其动机几乎总能在某个时段的监控尖峰、告警触发或事故时间线里找到对应物。

检索路径：六步从宽到窄的搜索流程

datadog.md给出的检索方法论是“先宽后窄”（start broad, then narrow），通过 Datadog MCP 工具完成。完整流程如下：

第 1 步：识别目标所属的服务

search_datadog_services (按名称或团队过滤) search_datadog_service_dependencies (查看上游/下游依赖)

先确定代码归属的服务及其依赖关系，后续所有检索才有正确的限定范围。

第 2 步：先看 Dashboard 和 Monitor——它们告诉你团队在乎什么

search_datadog_dashboards (query: 功能名、服务名、符号名) search_datadog_monitors (同样的查询词)

当某个 Dashboard 或 Monitor 覆盖了目标时，记下它的查询语句和被盯的阈值。文档给出一条关键洞察：“阈值”往往是“为什么这里被 clamp 在 N”的答案。例如代码把某值限制为 100，而监控在请求超过 100/min 时告警——二者一一对应，动机就浮出水面了。

第 3 步：检索目标周围的指标

search_datadog_metrics (按名称模式，如功能名或符号名) get_datadog_metric_context (元数据：描述、单位、tags) get_datadog_metric (时序数据；"PR 合并日期前后有没有尖峰？")

将指标轨迹与目标代码的增改日期做关联，是强有力的旁证。文档给出的示例句式是：payment_timeout指标在 2023-11-03 出现尖峰，而重试逻辑在 2023-11-06 合并——时间上的咬合构成了“指标异常驱动代码变更”的推断链。

第 4 步：日志——要窄，不要倾倒

search_datadog_logs (用符号、错误串、功能名检索，设置 use_log_patterns=true) analyze_datadog_logs (SQL 式聚合，仅在需要计数时使用)

日志体量巨大，文档强烈建议使用带时间边界的查询（例如变更前后各 30 天）。无约束的全量搜索浪费时间，还可能直接超时。能用analyze_datadog_logs做聚合时，不要倾倒原始日志。

第 5 步：APM spans 与 traces

aggregate_spans (统计："这个端点多久失败一次？") search_datadog_spans (检查单条 span) get_datadog_trace (按 trace ID 获取具体链路)

适用于超时、重试、慢路径与跨服务行为分析。

第 6 步：事故记录

search_datadog_incidents (按标题、团队、日期范围) get_datadog_incident (获取单条事故的完整详情)

如果目标代码看起来是防御性的（防守型），就检索它新增时间前后的事故。一条时间线里包含“为 X 添加了防御性检查”字样的事故记录，几乎是直接证据。

什么算这里的“好证据”

datadog.md给出了五类强证据形态，供 investigator 在调查中识别：

• 一条监控的查询与阈值，正好匹配代码强制的约束（代码 clamp 到 100，监控在请求超过 100/min 时告警）；
• 一个由目标代码作者创建的 Dashboard，其 widget 与代码度量或防御的内容对应；
• 一个在代码合并前出现生产尖峰、合并后趋于平稳的指标；
• 一条引用目标代码、相同符号或相同错误串的事故记录；
• 在变更前的窗口期、被时间戳固定下来的日志，显示防御性代码恰好要阻止的特定错误模式。

五类常见陷阱

datadog.md用较大篇幅列出误用这份证据的典型错误，是全文最具实操价值的部分：

1. 相关性不等于因果（Correlation is not causation）。PR 前的尖峰与 PR 后的平稳只是提示性证据，不是定论——同一窗口期可能有其他变更同时落地。务必检查邻近的 PR。
2. 对找到的图表过度拟合（Overfitting to the chart you found）。Datadog 可视化是人做的，反映了那个人的视角。名为“retry success rate”的图表只能证明团队关心重试成功率，不能证明某一行代码存在的理由。
3. 遥测消失（Vanished telemetry）。指标可能被重命名、删除或只有很短的保留期。找不到相关窗口的数据是一个“缺口（gap）”，而不是“空结果（null result）”。
4. 大规模噪声（Noise at scale）。检索常见字符串会命中成千上万条日志。要用服务、tag、时间积极收窄，用analyze_datadog_logs聚合而非倾倒原始日志。
5. 埋点不等于成因（Instrumented != caused）。一个指标的存在说明有人觉得值得测量某件事，不代表代码因为它而被加入。要用提交/PR 日期交叉印证。

这五条陷阱与why技能的置信度框架高度同构：epistemics.md（见 epistemics.md）把每条结论划分到 Direct / Supported / Inferred / Speculative / Unknown 五级，而 Datadog 证据天然偏向“Inferred”——指标尖峰与代码日期咬合是强间接证据，但必须用“appears to”“likely”“suggests”等措辞呈现，不能写成 “because”。

与事故复盘交叉角度的配合

在why技能的调查设计中，datadog.md不是孤立使用的。当目标代码呈现防御性特征（空值检查、重试逻辑、超时处理、限流、特性开关、出口防护、OOM 处理）时，investigator 还会额外拿到一份交叉角度文档 incident-postmortem.md。

该文档明确要求 Datadog 侧做这样一件事：用search_datadog_incidents检索正式事故记录（带时间线），并留意“作为 postmortem action item 而创建的 Dashboard 与 Monitor”——事故后的整改动作往往直接催生新的监控与代码变更。当一个 Datadog 事故 ID 出现在 Linear 工单里、又出现在 Notion 复盘里、再在 Slack 线程中被链接到目标 PR，且修复后产品分析侧的错误事件计数下降时，跨来源的相互印证会让证据强度显著提升。

Investigator 的输出要求

datadog.md结尾规定了 Datadog investigator 对每个相关条目应返回的内容格式：

• 类型（dashboard / monitor / metric / log pattern / trace / incident / notebook）
• 标题或名称
• 链接或标识符（dashboard ID、monitor ID、metric 名称、incident ID）
• 所有者/作者与创建、修改日期
• 与问题相关的具体条件、查询或引文（尽可能逐字引用）
• 相关性：它对目标代码说明了什么，以及连接强度如何

这一输出结构与 investigator-prompt.md 要求的“What I Searched / Direct Evidence Found / Indirect Evidence / Contradictions / Gaps”格式衔接：investigator 只负责如实收集证据、记录查询词与空缺，不做结论；结论由 synthesizer-prompt.md 定义的合成器在 “The Question / What We Found / What We Can Reasonably Infer / Competing Hypotheses / What We Don't Know / Sources Consulted / Confidence Summary” 结构中产出。因此，Datadog investigator 的返回应保持“枯燥而精确”，一条带精确引用的逐字引文胜过一段听起来合理的概括。

适配套件：同一 playbook 迁移到其他可观测性平台

source-playbook.md明确说明datadog.md是“基础设施可观测性”类别的示例 playbook，可适配到同类 MCP：New Relic、Honeycomb、Grafana、Splunk。迁移时保持证据类别不变——你要找的还是“基础设施与运行时现实如何驱动了代码”——只需把 MCP 工具名替换为目标平台对应的检索工具，检索策略（先宽后窄、先 Dashboard/Monitor 再指标、时间边界约束日志、事故记录兜底）与证据判定标准均可原样复用。

小结

把datadog.md放在整个why技能中看，它的角色非常清晰：当代码形状疑似被生产现实塑形时，Datadog 是“运行时真相”的唯一保管者。掌握这六步检索流程、五类强证据形态与五条陷阱，你就能在并行调查中高效提取出“指标尖峰驱动重试逻辑”“监控阈值解释 clamp 数值”“事故时间线催生防御性检查”这类高价值推断，并诚实地标注它们的证据强度——这正是 pstackwhy技能区别于普通代码考古的地方：它不仅找到“发生了什么”，还清楚地告诉你“我们凭什么这么推断”。

• 人工智能
• AI 技能
• AI 插件
• 开发工具