Designed for Claude Code, also compatible with Codex and OpenClaw
Sentry Architecture Variants
Overview
Choose the right Sentry SDK, project layout, and tracing strategy for each
application architecture. Every pattern below uses Sentry SDK v8 APIs —
@sentry/node, @sentry/browser, @sentry/react, @sentry/react-native,
@sentry/aws-serverless, and @sentry/google-cloud-serverless. The goal is
one coherent trace from the user's device through every backend hop, regardless
of how many runtimes or deployment targets sit in between.
HTTP tracing works automatically — SDK v8 propagates sentry-trace and baggage headers on all outbound HTTP requests. For service mesh (Istio/Linkerd), headers pass through transparently. For non-HTTP transports (gRPC, message queues), see event-driven pattern below and microservices deep-dive.
Serverless — Lambda and Cloud Functions
Serverless SDKs wrap your handler to auto-capture errors and flush events before the runtime freezes.
import * asSentryfrom'@sentry/react';
Sentry.init({
dsn: process.env.REACT_APP_SENTRY_DSN,
release: process.env.REACT_APP_VERSION,
tracesSampleRate: 0.1,
replaysOnErrorSampleRate: 1.0,
integrations: [
Sentry.browserTracingIntegration(),
Sentry.replayIntegration({ maskAllText: true, blockAllMedia: true }),
],
// Must match your API domain or frontend-to-backend traces breaktracePropagationTargets: ['localhost', /^https:\/\/api\.yourapp\.com/],
});
Route-based transactions, error boundaries, and session replay configuration: see frontend SPA deep-dive.
Mobile — React Native
import * asSentryfrom'@sentry/react-native';
Sentry.init({
dsn: process.env.SENTRY_DSN,
tracesSampleRate: 0.2,
integrations: [
Sentry.reactNativeTracingIntegration({
routingInstrumentation: Sentry.reactNavigationIntegration(),
}),
],
tracePropagationTargets: [/^https:\/\/api\.yourapp\.com/],
enableNativeCrashHandling: true,
attachScreenshot: true,
attachViewHierarchy: true,
});
exportdefaultSentry.wrap(App);
// Upload source maps + dSYMs in CI — see mobile deep-dive
Full navigation instrumentation and CI upload commands: see mobile deep-dive.
Step 3 — Wire Up Hybrid and Cross-Platform Tracing
For systems that span multiple architectures, connect traces end-to-end. The trace flow for a typical hybrid system:
@sentry/react creates a transaction on user click
Browser SDK adds sentry-trace + baggage headers to fetch()
API gateway (@sentry/node) auto-continues the trace
API gateway calls payment-service — headers propagate via HTTP
payment-service publishes to Kafka — headers injected manually (see event-driven pattern)
Worker (@sentry/node) continues trace from Kafka headers
Result: single trace ID visible across all services in Sentry Trace View. Backend-to-frontend correlation requires tracePropagationTargets in the browser SDK matching your API domains. Without this, the browser SDK will not attach trace headers and traces break at the browser-to-server boundary. See hybrid deep-dive.
Architecture decision matrix:
Architecture
Projects
Tracing Strategy
SDK Flush
Key Gotcha
Monolith
1
Single-service spans
Automatic
Module tag cardinality — keep under 50
Microservices
1 per service
Distributed via HTTP headers
Automatic
Missing baggage breaks sampling
Serverless
1 per function group
Per-invocation, auto-flush
wrapHandler()
Double-flush causes timeout
Event-driven
1 per consumer group
continueTrace() from headers
Manual periodic
DLQ needs separate error capture
Frontend SPA
1
browserTracingIntegration()
Automatic (beacon)
tracePropagationTargets required
Mobile
1
reactNativeTracingIntegration()
Automatic
Source maps + dSYMs required
Hybrid
Mix of above
End-to-end header propagation
Per-component
One missing link breaks whole trace
Output
After applying the appropriate pattern, you will have:
Architecture-specific Sentry.init() configuration with correct SDK package
Distributed tracing connected across all services (HTTP, gRPC, and message queues)
Serverless handlers wrapped with automatic error capture and event flushing
Event-driven consumers that continue producer traces via message headers
Frontend SPA with route-based transactions, session replay, and backend trace correlation
Mobile app with native crash reporting, screenshot capture, and navigation tracing
Hybrid systems with end-to-end trace visibility from browser/mobile through every backend hop
Error Handling
Error
Cause
Solution
Distributed traces broken
Missing header propagation
Verify sentry-trace AND baggage headers in every inter-service call
Lambda events lost after timeout
Calling flush() inside wrapHandler
Remove manual flush() — wrapHandler auto-flushes
Kafka consumer traces disconnected
Headers not serialized as strings
Call .toString() on Kafka message headers before continueTrace()
SPA traces stop at API boundary
tracePropagationTargets missing
Add API domain regex to browser SDK init
React Native traces unreadable
Missing source maps / dSYMs
Run sentry-cli sourcemaps upload and sentry-cli upload-dif in CI
Multi-tenant data leakage
setTag() at global scope
Use withScope() per request — global tags persist across requests
Worker events silently dropped
No periodic flush
Add setInterval(() => Sentry.flush(2000), 30_000)
High cardinality alert
Dynamic values in span names
Use parameterized names: kafka.consume.orders not kafka.consume.order-12345
Example 1 — Monolith with 5 teams:
Request: "Set up Sentry for a monolith with auth, billing, inventory, shipping, and analytics modules."
Result: Single Sentry project with module and team tags. Each team filters issues via tags.module:billing. Ownership rules route alerts to the correct Slack channel.
Example 2 — Microservices with Kafka:
Request: "Configure Sentry for 12 microservices communicating via REST and Kafka."
Result: 12 Sentry projects with shared initServiceSentry(). HTTP traces auto-propagate. Kafka producers inject sentry-trace/baggage into headers. Consumers call continueTrace(). Trace view: api-gateway -> order-service -> [kafka] -> fulfillment-worker.
Example 3 — Serverless API on Lambda:
Request: "Add Sentry to 8 AWS Lambda functions behind API Gateway."
Result: One Sentry project. Each handler wrapped with Sentry.wrapHandler(). Cold starts tagged. No manual flush() calls.
Example 4 — React SPA + Node API:
Request: "Full-stack Sentry for a React frontend calling a Node.js Express API."
Result: Two projects (frontend + backend). React uses @sentry/react with browserTracingIntegration() and replayIntegration(). tracePropagationTargets connects frontend to backend traces.
