在代码埋点时如何选择 Sentry 的 error…

当你为代码添加可观测性埋点、不确定某个值或事件该用日志、span、span 属性还是指标时，用这套决策框架判断该发出哪种信号。

适用场景

解决思路

1. 先明确四种信号各自回答的问题：Errors 回答“什么刚坏了”（堆栈+异常类型，聚合成可指派追踪的 Issue）；Traces 回答“请求是否按预期流转”（带计时的 span 瀑布，多为自动埋点）；Logs 回答“代码此刻的真实状态及原因”（结构化事件：配置、开关、输入输出、所做的决策）；Metrics 回答“随时间如何趋势变化”（可切分、可图表化、可告警的 counter/gauge/distribution）。
2. 用一句话记忆区分：log 是单个请求的故事（针），metric 是聚合（草堆是否正常），trace 是时间花在哪，error 是需要堆栈和负责人的东西。
3. 用决策表做直觉判断：崩溃要看堆栈→Error；耗时/哪一步慢→Traces/Spans；请求是否走了预期步骤→Traces/Spans；代码做决策时的状态→Log；函数收到和返回了什么→Log；X 发生频率/速率是否正常→Metric；部署后是否有变化→Metric。
4. 解决 span 属性与 metric 的重叠：关于单个请求流转、读该 trace 时想看的上下文→span 属性（随 span 出现在瀑布中）；想跨所有请求做图表、告警、按时间切分的独立值→metric。同一个数值可以两者都要，例如 span 上放 candidate_count 读单请求，metric 发 recommendations.served 看速率。
5. 解决 log 与 span 的重叠：span 是流程中带计时的节点（多为自动埋点，很少手写）；log 是该节点内部决策点的状态（总是有意手写）。span 回答“在哪、多久”，log 回答“当时什么是真的、为什么”。
6. 解决 log 与 metric 的重叠：log 用来找到出问题的那一个具体请求（针）；metric 告诉你有多少请求出问题（草堆）。不要通过数日志行来推导速率，直接发 metric。
7. 解决 error 与 log 的重叠：需要堆栈并应作为 Issue 追踪→error；意外但已处理、值得记录的情况→log；确实非关键但带 traceback→用 logger.warning(exc_info=True) 把 trace 留在日志里，避免污染 error feed。
8. 按信号匹配保留策略：Traces 采样，用 traces_sample_rate 保留代表性切片（开发高、生产低）；Errors 默认捕获，基线无需考虑采样；Logs 和 Metrics 不采样，全量保留并用 before_send_log 和 before_send_metric 过滤——因为日志的意义就是找到那一个罕见出错的请求，采样掉就找不到了。
9. 利用四种信号同源共享 trace_id 自动关联：每条 log 和 metric 都绑定到其 trace，可从 metric 尖峰直接下钻到背后的样本。
10. 把精力放在有意埋点的 20%：约 80% 的 span 由框架和数据库集成自动埋点，你几乎不写；刻意要做的是在代码做出值得日后追问的选择处，加一两个 span 属性丰富流程、一条决策点 log、一个 metric。
11. 实现前先核对 SDK API：文中代码示例仅作说明，需对照 docs.sentry.io 和对应 sentry-*-sdk 技能确认确切签名与最低版本。
12. 确定要发什么后交接给 setup：安装 SDK 并开启 tracing/logs/metrics 交给对应的 sentry-<platform>-sdk 技能（如 sentry-python-sdk、sentry-nextjs-sdk、sentry-node-sdk）；埋点 LLM/agent 调用交给 sentry-setup-ai-monitoring。
13. 若 logs 和 metrics 尚未开启（多数项目未开，且所有套餐都包含），先路由到 SDK 技能开启，再回来决定放什么。

适用边界 · 注意事项

• 本技能只决定“发什么信号”，不负责“如何为特定技术栈开启各支柱”，后者应交给对应的 sentry-*-sdk 技能。
• 文中的 SDK API 与代码示例仅作说明，不能直接照抄实现，需先对照官方文档核实签名与版本。
• 不适用于埋点 LLM/agent 调用的具体设置，那属于 sentry-setup-ai-monitoring 的范畴。