sentry-setup-tracing

Setup Sentry Tracing

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

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

Important: The SDK versions, API names, and code samples below are examples. Always verify against docs.sentry.io before implementing, as APIs and minimum versions may have changed.

Quick Reference

Platform	Min SDK	Enable	Custom Span
JS/Browser	9.0.0+	tracesSampleRate + browserTracingIntegration()	Sentry.startSpan()
Next.js	9.0.0+	tracesSampleRate in each runtime config file	Sentry.startSpan()
Node.js	9.0.0+	tracesSampleRate	Sentry.startSpan()
Python	0.11.2+	traces_sample_rate	@sentry_sdk.trace or start_span()
Ruby	5.0.0+	traces_sample_rate	Sentry.with_child_span()

JavaScript Setup

Enable tracing

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

Custom spans

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

Dynamic sampling

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 Setup

Enable tracing

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

Custom spans

# 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)

Dynamic sampling

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 Setup

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
queue.task	Background jobs
function	Function calls

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

Distributed Tracing

Configure tracePropagationTargets to send trace headers to your APIs:

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

For Next.js 14 App Router, add to root layout (not needed in Next.js 15+):

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

Verification

After enabling tracing, trigger a traced operation (e.g., an HTTP request) and check the Sentry Performance dashboard for transactions. Custom spans should appear nested under the parent transaction.

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