sentry-setup-tracing

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Setup Sentry Tracing

设置Sentry Tracing

Configure Sentry's performance monitoring to track transactions and spans.

配置Sentry的性能监控以跟踪事务和跨度。

Invoke This Skill When

在以下场景调用此技能

User asks to "enable tracing" or "add performance monitoring"
User wants to track API response times, page loads, or latency
User asks about
```
tracesSampleRate
```
or custom spans

用户要求"启用追踪"或"添加性能监控"
用户希望跟踪API响应时间、页面加载或延迟
用户询问
```
tracesSampleRate
```
或自定义跨度

Quick Reference

快速参考

Platform	Enable	Custom Span
JS/Browser	`tracesSampleRate` + `browserTracingIntegration()`	`Sentry.startSpan()`
Next.js	`tracesSampleRate` (auto-integrated)	`Sentry.startSpan()`
Node.js	`tracesSampleRate`	`Sentry.startSpan()`
Python	`traces_sample_rate`	`@sentry_sdk.trace` or `start_span()`
Ruby	`traces_sample_rate`	`start_span()`

平台	启用方式	自定义跨度
JS/浏览器	`tracesSampleRate` + `browserTracingIntegration()`	`Sentry.startSpan()`
Next.js	`tracesSampleRate` （自动集成）	`Sentry.startSpan()`
Node.js	`tracesSampleRate`	`Sentry.startSpan()`
Python	`traces_sample_rate`	`@sentry_sdk.trace` 或 `start_span()`
Ruby	`traces_sample_rate`	`start_span()`

JavaScript Setup

JavaScript设置

Enable tracing

启用追踪

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\./],
});

javascript

Sentry.init({
  dsn: "YOUR_DSN",
  tracesSampleRate: 1.0,  // 1.0 = 100%, 生产环境可降低
  integrations: [Sentry.browserTracingIntegration()],  // 仅浏览器/React使用
  tracePropagationTargets: ["localhost", /^https:\/\/api\./],
});

Custom spans

自定义跨度

javascript

// 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);
});

javascript

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

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

Dynamic sampling

动态采样

javascript

tracesSampler: ({ name, parentSampled }) => {
  if (name.includes("healthcheck")) return 0;
  if (name.includes("checkout")) return 1.0;
  if (parentSampled !== undefined) return parentSampled;
  return 0.1;
},

javascript

tracesSampler: ({ name, parentSampled }) => {
  if (name.includes("healthcheck")) return 0;
  if (name.includes("checkout")) return 1.0;
  if (parentSampled !== undefined) return parentSampled;
  return 0.1;
},

Python Setup

Python设置

Enable tracing

启用追踪

python

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

python

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

Custom spans

自定义跨度

python

undefined

python

undefined

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)

undefined

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

undefined

Dynamic sampling

动态采样

python

def traces_sampler(ctx):
    name = ctx.get("transaction_context", {}).get("name", "")
    if "healthcheck" in name: return 0
    if "checkout" in name: return 1.0
    return 0.1

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

python

def traces_sampler(ctx):
    name = ctx.get("transaction_context", {}).get("name", "")
    if "healthcheck" in name: return 0
    if "checkout" in name: return 1.0
    return 0.1

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

Ruby Setup

Ruby设置

ruby

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

ruby

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

Common Operation Types

常见操作类型

`op` Value	Use Case
`http.client`	Outgoing HTTP
`http.server`	Incoming HTTP
`db` / `db.query`	Database
`cache`	Cache operations
`task`	Background jobs
`function`	Function calls

`op` 值	使用场景
`http.client`	对外HTTP请求
`http.server`	对内HTTP请求
`db` / `db.query`	数据库操作
`cache`	缓存操作
`task`	后台任务
`function`	函数调用

Sampling Recommendations

采样建议

Traffic	Rate
Development	`1.0`
Low (<1K req/min)	`0.5 - 1.0`
Medium (1K-10K)	`0.1 - 0.5`
High (>10K)	`0.01 - 0.1`

流量情况	采样率
开发环境	`1.0`
低流量（<1K请求/分钟）	`0.5 - 1.0`
中等流量（1K-10K）	`0.1 - 0.5`
高流量（>10K）	`0.01 - 0.1`

Distributed Tracing

分布式追踪

Configure

tracePropagationTargets

to send trace headers to your APIs:

javascript

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

For Next.js 14+ App Router, add to root layout:

typescript

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

配置

tracePropagationTargets

以将追踪标头发送到你的API：

javascript

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

对于Next.js 14+ App Router，添加到根布局：

typescript

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

Troubleshooting

故障排除

Issue	Solution
Transactions not appearing	Check `tracesSampleRate > 0` , verify DSN
Browser traces missing	Add `browserTracingIntegration()`
Distributed traces disconnected	Check `tracePropagationTargets` , CORS headers
Too many transactions	Lower sample rate, use `tracesSampler` to filter

问题	解决方案
事务未显示	检查 `tracesSampleRate > 0` ，验证DSN
浏览器追踪缺失	添加 `browserTracingIntegration()`
分布式追踪断开	检查 `tracePropagationTargets` 、CORS标头
事务数量过多	降低采样率，使用 `tracesSampler` 过滤