sentry-setup-tracing

设置 Sentry 跟踪

配置 Sentry 的性能监控，以跟踪事务和 span。

在以下情况下调用此技能

• 用户要求“启用跟踪”或“添加性能监控”
• 用户想跟踪 API 响应时间、页面加载时间或延迟
• 用户询问 tracesSampleRate 或自定义 span

重要： 以下 SDK 版本、API 名称和代码示例仅供参考。实现前请务必查看 docs.sentry.io 进行核实，因为 API 和最低版本要求可能已经变更。

快速参考

平台	最低 SDK 版本	启用方式	自定义 Span
JS/浏览器	9.0.0+	tracesSampleRate + browserTracingIntegration()	Sentry.startSpan()
Next.js	9.0.0+	在每个运行时配置文件中设置 tracesSampleRate	Sentry.startSpan()
Node.js	9.0.0+	tracesSampleRate	Sentry.startSpan()
Python	0.11.2+	traces_sample_rate	@sentry_sdk.trace 或 start_span()
Ruby	5.0.0+	traces_sample_rate	Sentry.with_child_span()

JavaScript 设置

启用跟踪

Sentry.init({
  dsn: "YOUR_DSN",
  tracesSampleRate: 1.0,  // 1.0 = 100%, lower for production
  integrations: [Sentry.browserTracingIntegration()],  // Browser/React only
  tracePropagationTargets: ["localhost", /^https:\/\/api\./],
});

自定义 span

// Async operation
const result = await Sentry.startSpan(
  { name: "fetch-user", op: "http.client" },
  async () => {
    return await fetch("/api/user").then(r => r.json());
  }
);

// Nested spans
await Sentry.startSpan({ name: "checkout", op: "transaction" }, async () => {
  await Sentry.startSpan({ name: "validate", op: "validation" }, validateCart);
  await Sentry.startSpan({ name: "payment", op: "payment" }, processPayment);
});

动态采样

tracesSampler: ({ name, inheritOrSampleWith }) => {
  if (name.includes("healthcheck")) return 0;
  if (name.includes("checkout")) return 1.0;
  return inheritOrSampleWith(0.1);  // Respects parent sampling decision, falls back to 0.1
},

Python 设置

启用跟踪

sentry_sdk.init(
    dsn="YOUR_DSN",
    traces_sample_rate=1.0,
)

自定义 span

# Decorator
@sentry_sdk.trace
def expensive_function():
    return do_work()

# Context manager
with sentry_sdk.start_span(name="process-order", op="task") as span:
    span.set_data("order.id", order_id)
    process(order_id)

动态采样

from sentry_sdk.types import SamplingContext

def traces_sampler(sampling_context: SamplingContext) -> float:
    name = sampling_context.get("transaction_context", {}).get("name", "")
    parent_sampled = sampling_context.get("parent_sampled")
    if "healthcheck" in name: return 0
    if "checkout" in name: return 1.0
    if parent_sampled is not None: return float(parent_sampled)  # Respect parent decision
    return 0.1

sentry_sdk.init(dsn="YOUR_DSN", traces_sampler=traces_sampler)

Ruby 设置

Sentry.init do |config|
  config.dsn = "YOUR_DSN"
  config.traces_sample_rate = 1.0
end

常见操作类型

op 值	用例
http.client	发出的 HTTP 请求
http.server	收到的 HTTP 请求
db / db.query	数据库
cache	缓存操作
queue.task	后台任务
function	函数调用

采样建议

流量	比率
开发环境	1.0
低（<1K req/min）	0.5 - 1.0
中（1K-10K）	0.1 - 0.5
高（>10K）	0.01 - 0.1

分布式跟踪

配置 tracePropagationTargets，以便向 API 发送跟踪标头：

tracePropagationTargets: ["localhost", "https://api.yourapp.com"],

对于 Next.js 14 App Router，将以下内容添加到根布局中（Next.js 15+ 无需此操作）：

export function generateMetadata(): Metadata {
  return { other: { ...Sentry.getTraceData() } };
}

验证

启用跟踪后，触发一个被跟踪的操作（例如 HTTP 请求），并在 Sentry Performance 仪表板中检查事务。自定义 span 应显示为嵌套在父事务之下。

故障排除

问题	解决方案
未显示事务	检查 tracesSampleRate > 0，并确认 DSN
缺少浏览器跟踪	添加 browserTracingIntegration()
分布式跟踪未连接	检查 tracePropagationTargets 和 CORS 标头
事务过多	降低采样率，使用 tracesSampler 进行筛选