Enabling Sentry Distributed Tracing in a Microservices Stack: Decision Guide

Decision Context

When you add distributed tracing to a microservices architecture, you must decide how to instrument each service and what level of control you need. Sentry offers several paths:

• Automatic SDK instrumentation – minimal code changes, but limited to SDK‑provided spans.
• Manual span creation – fine‑grained control, but requires boilerplate.
• OpenTelemetry + Sentry bridge – unified tracing across teams, but adds a dependency layer.

Key constraints to weigh:

• Language support – not all SDKs expose the same tracing APIs.
• Cost & performance – tracing doubles event payload; sampling is essential.
• Security & privacy – traces may carry request bodies; filtering is mandatory.

Feature Options

• Auto‑Instrumentation (SDK) – e.g., raven-python, @sentry/node, sentry-go.
  • Pros: Zero code changes, consistent trace IDs.
  • Cons: Limited custom span support.
• Manual Spans – use startSpan / finishSpan APIs.
  • Pros: Full control over span names, tags, and timing.
  • Cons: Boilerplate, risk of missing spans.
• OpenTelemetry + Sentry Bridge – export OTLP traces to Sentry.
  • Pros: Works across languages, can share traces with other tools.
  • Cons: Requires OTLP exporter and bridge configuration.

Trade‑Offs Table

Option	Setup Effort	Granularity	Performance Impact	Cost Control
SDK Auto‑Instrumentation	Low – add init code	Medium – SDK spans only	Low – automatic sampling	Built‑in sampling, but payload grows with request size
Manual Spans	High – code changes per service	High – full control	High – more spans = more data	Manual sampling via SDK config
OpenTelemetry Bridge	Medium – install OTLP exporter, bridge	High – any OTLP span	Medium – OTLP overhead + Sentry	Sampling via OTLP and Sentry

Implementation Steps

1. Choose a path – for most teams, start with SDK auto‑instrumentation and add manual spans only where needed.
2. Configure SDK – add the tracing option and set a sampling rate.

   // Node.js example – run in the service entry point
   const Sentry = require('@sentry/node');
   const Tracing = require('@sentry/tracing');
   
   Sentry.init({
     dsn: 'https://{PUBLIC_KEY}@sentry.io/{PROJECT_ID}',
     tracesSampleRate: 0.1, // sample 10% of requests
     integrations: [
       new Tracing.Integrations.Express({ app }) // auto‑instrument Express
     ],
   });
   

   Run on the host where the service starts; needs read permissions for environment variables.

3. Propagate trace context – most SDKs automatically inject the traceparent header. Verify by inspecting outbound HTTP headers or by adding a console.log(req.headers) in a sample request.
4. Add a custom span (if needed) – for a database call that isn’t auto‑instrumented.

   const span = Sentry.getCurrentHub().getScope().getTransaction().startChild({
     op: 'db.query',
     description: 'SELECT * FROM users'
   });
   try {
     // perform DB operation
   } finally {
     span.finish();
   }
   

   Ensure the span is finished in a finally block to avoid orphaned spans.

5. Enable OpenTelemetry bridge (optional) – if you have existing OTLP exporters.

   npm install @sentry/opentelemetry
   // In your OTLP exporter init
   const { SentryExporter } = require('@sentry/opentelemetry');
   const exporter = new SentryExporter({ dsn: 'https://...' });
   

Validation Checklist

• Send a test request to Service A and confirm a trace appears under Performance > Traces in the Sentry UI.
• Inspect the trace hierarchy – the root span should be the HTTP request, with child spans for each downstream call.
• Check the traceparent header in Service B’s logs to verify propagation.
• Verify that custom spans appear as children of the appropriate parent span.
• Monitor the traces event count in the Sentry project settings; adjust tracesSampleRate if usage exceeds budget.
• Run sentry-cli stats --org <org> --project <proj> to confirm payload size and cost metrics remain within limits.

Common Pitfalls & Mitigations

• Missing trace IDs – ensure each service uses the same SDK version and that traceparent is not stripped by reverse proxies.
• Excessive payload – set tracesSampleRate to a low value (e.g., 0.01) during rollout, then increase gradually.
• Sensitive data leakage – configure beforeSendTransaction to filter request bodies or headers.
• Inconsistent span names – adopt a naming convention (e.g., db.query, http.client) and document it.

Conclusion

Start with SDK auto‑instrumentation to get end‑to‑end traces quickly. Add manual spans only for critical operations that the SDK misses. If your stack already uses OpenTelemetry, the Sentry bridge gives you the best of both worlds. Keep an eye on sampling, payload, and privacy settings to maintain a healthy cost and performance profile.