sentry-instrumentation-guide

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

All Skills > Feature Setup > Instrumentation Guide

所有Skills > 功能设置 > 插桩指南

Sentry Instrumentation Guide: When to Reach for What

Sentry插桩指南：如何选择合适的信号

Errors, traces, logs, and metrics are the four kinds of telemetry most apps run on, and they overlap enough that the choice is rarely obvious. You can stuff context into a span attribute instead of logging it. You can count log lines instead of emitting a metric. You can add a duration to a log and call it a span.

But each signal exists because it answers a different question and feeds a different workflow once it lands. Reaching for the wrong one means the data is technically there but useless for the job you actually have later. This skill is the decision framework: given a value or an event in front of you, which signal should carry it, and why.

It decides what to emit. For how to turn each pillar on for a given stack, hand off to the

sentry-*-sdk

skills and

sentry-setup-ai-monitoring

Errors、traces、logs和metrics是大多数应用依赖的四类遥测数据，它们之间存在足够多的重叠，因此选择哪一种往往并不明确。你可以将上下文信息放入span attribute而非log中，也可以通过统计log行数来替代发送metric，还可以给log添加时长并将其视为span。

但每种信号的存在都是因为它要回答不同的问题，并且在到达系统后服务于不同的工作流。选错信号意味着数据技术上存在，但对你后续实际要完成的工作毫无用处。本Skill提供决策框架：当你面对某个值或事件时，应该用哪种信号来传递它，以及原因是什么。

它负责决定要发送什么信号。至于针对特定技术栈如何启用各个支柱功能，请交给

sentry-*-sdk

系列Skill和

sentry-setup-ai-monitoring

处理。

Invoke This Skill When

何时调用本Skill

You're instrumenting a piece of code and unsure whether something should be a log, a span, a span attribute, or a metric
You're deciding "what to instrument where" across a service or request handler
You're reviewing existing instrumentation for gaps (e.g. an error feed that's empty while users report problems)
A coding agent needs a consistent rule for choosing between errors, traces, logs, and metrics

Important: The SDK APIs and code samples here are illustrative. Verify exact signatures and minimum versions against docs.sentry.io and the relevant

sentry-*-sdk

skill before implementing.

你在为某段代码插桩时，不确定应该使用log、span、span attribute还是metric
你正在决定跨服务或请求处理器的“在何处插桩什么内容”
你正在检查现有插桩是否存在遗漏（例如，用户报告问题但错误反馈为空）
编码Agent需要一套一致的规则来在errors、traces、logs和metrics之间做选择

重要提示：此处的SDK API和代码示例仅作说明。在实现前，请对照docs.sentry.io和对应的

sentry-*-sdk

Skill验证确切的签名和最低版本要求。

The Four Signals, One Question Each

四类信号，各对应一个问题

Signal	The question it answers	Docs
Errors	"What just broke?" — a stack trace and exception type, grouped into a deduplicated Issue that gets assigned and tracked to resolution. If your code threw, it's an error.	Issues
Traces	"Did the request flow the way it was supposed to?" — a waterfall of timed spans. Mostly auto-instrumented.	Trace Explorer
Logs	"What was true at this point in the code, and why?" — the system's state at one moment as a structured event: config, flags, inputs/outputs, the decision that was made.	Logs
Metrics	"How's this trending over time?" — counters, gauges, distributions you can slice by attribute and chart, alert on, or compare across a deploy.	Metrics

A useful mental split: a log is one request's story (the needle), a metric is the aggregate (whether the haystack is normal), a trace is where the time went, and an error is the thing that needs a stack trace and an owner.

信号	要回答的问题	文档
Errors	“刚才哪里出问题了？”——包含堆栈跟踪和异常类型，会被归类为去重后的Issue并分配跟踪直至解决。如果代码抛出异常，就属于error。	Issues
Traces	“请求是否按预期流程执行？”——由带时间戳的span组成的瀑布流。大多为自动插桩。	Trace Explorer
Logs	“代码执行到此处时的状态是什么，原因是什么？”——某一时刻系统状态的结构化事件：配置、标志、输入/输出、做出的决策。	Logs
Metrics	“这一指标随时间的趋势如何？”——可按属性拆分、绘制图表、设置警报或跨部署版本比较的计数器、仪表盘、分布数据。	Metrics

一个实用的思维区分方式：log是单个请求的详情（大海捞针中的“针”），metric是聚合数据（判断整个“针堆”是否正常），trace记录时间消耗的去向，而error是需要堆栈跟踪和负责人处理的问题。

The Decision Table

决策表

Use this as a gut check:

What you want to know	Reach for
Something crashed, show the stack trace	Error
How long did this take? Which step is slow?	Traces / Spans
Did the request flow through the steps I expected?	Traces / Spans
What was the state when the code made this decision?	Log
What did this function receive and return?	Log
How often does X happen? Is the rate normal?	Metric
Did something change after the deploy?	Metric

用以下内容快速判断：

你想了解的内容	选择的信号
某个组件崩溃了，需要查看堆栈跟踪	Error
这个操作耗时多久？哪一步很慢？	Traces / Spans
请求是否按我预期的步骤流转？	Traces / Spans
代码做出该决策时的状态是什么？	Log
这个函数接收了什么参数，返回了什么结果？	Log
X事件发生的频率是多少？该频率是否正常？	Metric
部署后是否有什么变化？	Metric

Resolving the Overlaps

解决重叠问题

The same value can legitimately appear in more than one signal. These four tiebreakers cover almost every real case. (Full reasoning, gotchas, and the "why not just log everything / emit one wide event?" arguments live in

references/choosing-signals.md

Span attribute or metric? Context about one request's flow that you want while reading that trace → span attribute (it rides on the span in the waterfall). A standalone value you want to chart, alert on, or slice over time across all requests → metric. The same number can warrant both:
```
candidate_count
```
on the span to read one request,
```
recommendations.served
```
as a metric to watch the rate.
Log or span? The span is the timed node in the flow (mostly auto-instrumented, you rarely write it). The log is the decision-point state inside that node (you always write it on purpose). Span answers where and how long; log answers what was true and why.
Log or metric? A log finds the one specific request that went wrong (the needle). A metric tells you how many requests went wrong (the haystack). Don't derive a rate by counting log lines — emit the metric directly.
Error or log? Needs a stack trace and should be tracked as an Issue → error. An unexpected-but-handled condition worth recording → log. Truly non-critical with a traceback →
```
logger.warning(exc_info=True)
```
keeps the trace in logs without creating noise in the error feed.

同一个值可能合理出现在多个信号中。以下四个判断标准几乎能覆盖所有实际场景。（完整的推理、注意事项以及“为什么不把所有内容都记录为log / 发送一个宽泛的事件？”等讨论，请查看

references/choosing-signals.md

。）

span attribute还是metric？ 如果你在查看单个trace时需要了解该请求流程的上下文信息 → span attribute（它会附加在瀑布流中的span上）。如果你需要一个独立的值来绘制图表、设置警报，或是跨所有请求按时间维度拆分分析 → metric。同一个数值可能同时需要两种方式：将
```
candidate_count
```
作为span attribute来查看单个请求，将
```
recommendations.served
```
作为metric来监控频率。
log还是span？ span是流程中的带时间节点（大多为自动插桩，你几乎不需要手动编写）。log是该节点内决策点的状态（你需要有目的地手动编写）。span回答在哪里和耗时多久；log回答状态是什么以及原因是什么。
log还是metric？ log用于找到出问题的那个特定请求（“针”）。metric用于告诉你有多少请求出了问题（“针堆”）。不要通过统计log行数来推导频率——直接发送metric。
error还是log？ 需要堆栈跟踪且应作为Issue跟踪 → error。意外但已处理的、值得记录的情况 → log。真正非关键且带有回溯信息的情况 → 使用
```
logger.warning(exc_info=True)
```
将跟踪信息保留在log中，同时避免在错误反馈中产生噪音。

Sampling vs Filtering — Match Retention to the Question

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

Each signal's retention falls out of the question it answers:

Traces are sampled. You don't need every request to understand where time goes, so keep a representative slice via
```
traces_sample_rate
```
(higher in dev, lower in production).
Errors are captured by default. No sampling to think about for the baseline.
Logs and metrics are NOT sampled. You keep every one and filter instead, with
```
before_send_log
```
and
```
before_send_metric
```
. This is the point: the whole reason for a log is to find the one rare request that went sideways, and you can't find what you sampled away.

(For the exact sampling and filtering config in your language, see the matching SDK skill's

references/tracing.md

and

references/metrics.md

Because all four signals come from one SDK, they share a

trace_id

and correlate on their own — every log and metric is tied to its trace, so you can drill from a metric spike straight into the samples behind it.

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

Traces会被采样。你不需要保留每个请求来了解时间消耗的去向，因此通过
```
traces_sample_rate
```
保留具有代表性的样本（开发环境采样率较高，生产环境较低）。
Errors默认会被捕获。基础配置无需考虑采样。
Logs和Metrics不会被采样。你需要保留所有数据并通过
```
before_send_log
```
和
```
before_send_metric
```
进行过滤。这是关键：log的作用就是找到那个罕见的出问题请求，而你无法找到被采样丢弃的数据。

（关于你所用语言的具体采样和过滤配置，请查看对应SDK Skill的

references/tracing.md

和

references/metrics.md

。）

由于四类信号都来自同一个SDK，它们共享

trace_id

并自动关联——每个log和metric都与其trace绑定，因此你可以从metric峰值直接深入查看背后的样本。

What Deliberate Instrumentation Looks Like

刻意插桩的示例

Roughly 80% of spans are auto-instrumented by your framework and database integrations — you write almost none of them. The deliberate work is the other 20%: a span attribute or two to enrich the flow, a decision-point log, and a metric, placed at the spots where your code makes a choice worth questioning later.

references/instrumentation-examples.md

walks through a single request handler instrumented end to end, in both Python and JavaScript/TypeScript, showing the span attribute, the log, and the metric side by side on the same decision.

大约80%的span由你的框架和数据库集成自动插桩——你几乎不需要手动编写。需要刻意处理的是剩下的20%：添加一两个span attribute来丰富流程信息，记录决策点的log，以及设置metric，将它们放在代码中做出值得后续验证的决策的位置。

references/instrumentation-examples.md

详细演示了一个完整的请求处理器插桩过程，涵盖Python和JavaScript/TypeScript两种语言，展示了在同一个决策点上，span attribute、log和metric的使用方式。

Handing Off to Setup

转至设置环节

This skill tells you what to emit. To actually wire a pillar up:

Install the SDK and turn on tracing, logs, and metrics → the matching
```
sentry-<platform>-sdk
```
skill (e.g.
```
sentry-python-sdk
```
,
```
sentry-nextjs-sdk
```
,
```
sentry-node-sdk
```
). Each has per-feature reference files for tracing, logging, metrics, and more.
Instrument LLM / agent calls →
```
sentry-setup-ai-monitoring
```
.

Logs and metrics are the two pillars most projects haven't turned on yet, and both are included on every plan. If they aren't enabled, route to the SDK skill first, then come back here to decide what to put where.

本Skill告诉你要发送什么信号。要实际配置各个支柱功能：

安装SDK并启用tracing、logs和metrics → 使用对应的
```
sentry-<platform>-sdk
```
Skill（例如
```
sentry-python-sdk
```
、
```
sentry-nextjs-sdk
```
、
```
sentry-node-sdk
```
）。每个Skill都包含针对tracing、logging、metrics等功能的参考文档。
为LLM / Agent调用插桩 → 使用
```
sentry-setup-ai-monitoring
```
。

Logs和metrics是大多数项目尚未启用的两个支柱功能，且所有套餐都包含这两项。如果它们尚未启用，请先查看SDK Skill进行配置，然后再回到此处决定在何处放置什么内容。