sentry-instrumentation-guide

所有技能 > 功能设置 > 埋点指南

Sentry 埋点指南：何时选择哪种信号

错误、追踪、日志和指标是大多数应用所依赖的四种遥测信号，它们之间有足够多的重叠，因此很难直接做出选择。你可以把上下文塞进跨度属性，而不记录日志；也可以统计日志行数，而不发送指标；还可以在日志中添加持续时间，并把它称为跨度。

但每种信号之所以存在，是因为它回答了不同的问题，并且在数据上报后会用于不同的工作流。选择错误的信号意味着数据虽然确实存在，却无法用于你之后真正要完成的工作。这项技能提供了决策框架：面对一个值或事件时，应该用哪种信号来承载它，为什么？

它决定要发送什么。至于如何为特定技术栈启用各项信号，请转到 sentry-*-sdk 技能和 sentry-setup-ai-monitoring。

适用场景

• 你正在为一段代码添加埋点，但不确定应该使用日志、跨度、跨度属性还是指标
• 你正在决定如何为某个服务或请求处理程序添加埋点
• 你正在检查现有埋点是否有遗漏（例如，用户报告问题，但错误动态中却空空如也）
• 编码 Agent 需要一套统一规则，以便在错误、追踪、日志和指标之间做出选择

**重要提示：**此处的 SDK API 和代码示例仅供说明。实现前，请通过 docs.sentry.io 和相关的 sentry-*-sdk 技能核实准确的签名和最低版本要求。

四种信号，各自回答一个问题

信号	回答的问题	文档
错误	“刚才哪里出了问题？”——一条堆栈跟踪和异常类型，会归并到去重后的问题中，并分配负责人、跟踪至解决。如果代码抛出了异常，那就是错误。	问题
追踪	“请求是否按预期流转？”——由计时跨度组成的瀑布图。大多会自动埋点。	追踪浏览器
日志	“代码运行到这里时，状态如何？原因是什么？”——系统在某一时刻的状态，以结构化事件的形式记录：配置、标志、输入/输出，以及所做的决策。	日志
指标	“这种情况随时间呈现怎样的趋势？”——计数器、仪表和分布数据，可以按属性筛选并制成图表、设置告警，或对比不同部署。	指标

一种实用的理解方式是：日志记录单个请求的故事（大海捞针中的那根针），指标反映整体情况（干草堆是否正常），追踪显示时间花在了哪里，而错误是需要堆栈跟踪和负责人处理的事项。

决策表

可用以下内容快速判断：

你想了解什么	选择
某处发生了崩溃，显示堆栈跟踪	错误
耗时多久？哪个步骤较慢？	追踪 / 跨度
请求是否经过了预期的各个步骤？	追踪 / 跨度
代码做出此决策时，状态如何？	日志
此函数收到了什么，又返回了什么？	日志
X 发生的频率如何？这个频率是否正常？	指标
部署后是否发生了变化？	指标

解决重叠问题

同一个值合理地出现在多个信号中并不罕见。以下四条判断规则几乎涵盖了所有实际情况。（完整的推理、易踩的坑，以及“为什么不直接记录所有内容／发出一个宽泛事件？”的讨论，见 references/choosing-signals.md。）

• Span 属性还是指标？ 想在查看轨迹时了解单个请求的流程中的上下文 → span 属性（它会显示在瀑布图中的 span 上）。想要绘制图表、设置告警或按时间查看所有请求中的独立值 → 指标。同一个数值可能两者都需要：在 span 上记录 candidate_count 以查看单个请求，用 recommendations.served 作为指标来监控速率。
• 日志还是 span？ Span 是流程中计时的节点（大多由自动埋点生成，你很少需要手动编写）。日志是该节点内部的决策点状态（始终由你有意编写）。Span 回答在哪里以及持续了多久；日志回答实际情况如何以及原因是什么。
• 日志还是指标？ 日志能找到出问题的某个具体请求（大海捞针）。指标能告诉你有多少请求出了问题（整片大海）。不要通过统计日志行数来推导速率——直接发出指标。
• 错误还是日志？ 需要堆栈跟踪且应作为 Issue 跟踪 → 错误。值得记录的意外但已处理情况 → 日志。如果情况确实不重要但带有回溯信息，使用 logger.warning(exc_info=True)，将跟踪信息保留在日志中，同时避免污染错误流。

采样与过滤——让保留策略匹配问题

每种信号的保留策略取决于它要回答的问题：

• 轨迹会采样。 要了解时间花在哪里，不需要记录每个请求，因此可以通过 traces_sample_rate 保留具有代表性的一部分（开发环境中比例较高，生产环境中较低）。
• 默认会捕获错误。 基线配置无需考虑采样。
• 日志和指标不会采样。 你会保留每一条，再通过 before_send_log 和 before_send_metric 进行过滤。这正是关键所在：记录日志的全部意义就是找到那个偶尔出问题的请求，而你无法找到已被采样丢弃的内容。

（有关所用语言的具体采样和过滤配置，请参阅对应 SDK 技能中的 references/tracing.md 和 references/metrics.md。）

由于这四种信号都来自同一个 SDK，它们共享 trace_id 并会自动关联——每条日志和每项指标都与其轨迹关联，因此你可以从指标激增处直接深入查看背后的采样数据。

有意埋点是什么样的

大约 80% 的 span 由框架和数据库集成自动埋点生成——你几乎不需要编写它们。有意埋点的工作占另外 20%：添加一两个 span 属性来丰富流程，在决策点记录日志，并在代码中做出值得日后追问的选择处添加指标。

references/instrumentation-examples.md 通过一个完整埋点的请求处理程序，展示了从头到尾的流程，分别使用 Python 和 JavaScript/TypeScript 编写，并排展示同一个决策对应的 span 属性、日志和指标。

转到设置步骤

这项技能告诉你要发出什么信号。要实际配置某个支柱：

• 安装 SDK 并启用追踪、日志和指标 → 对应的 sentry-<platform>-sdk 技能（例如 sentry-python-sdk、sentry-nextjs-sdk、sentry-node-sdk）。每项技能都提供按功能划分的参考文件，涵盖追踪、日志记录、指标等内容。
• 为 LLM / Agent 调用埋点 → sentry-setup-ai-monitoring。

日志和指标是大多数项目尚未启用的两个支柱，而且所有套餐都包含它们。如果尚未启用，请先转到 SDK 技能，然后再回到这里决定各项内容应放在哪里。