sentry-architecture-variants

Sentry Architecture Variants

Overview

Choose the right Sentry SDK, project layout, and tracing strategy for eachapplication 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 isone coherent trace from the user's device through every backend hop, regardlessof how many runtimes or deployment targets sit in between.

Deep-dive references for each pattern:Monolith |Microservices |Serverless |Event-driven |Frontend SPA |Mobile |Hybrid |Errors

Prerequisites

• Node.js 18+ (or target platform runtime)
• Sentry organization with at least one project created at sentry.io
• SENTRY_DSN available as an environment variable (one per Sentry project)
• Application architecture documented — service inventory, deployment targets, team ownership mapped
• For distributed tracing: all inter-service transports identified (HTTP, gRPC, Kafka, SQS)

Instructions

Step 1 — Identify Your Architecture and Select SDK Packages

Map every runtime in your system to the correct Sentry SDK package and project layout.

Install the SDK for your architecture:

# Monolith / Microservices / Event-drivennpm install @sentry/node @sentry/profiling-node# Serverless — AWS Lambdanpm install @sentry/aws-serverless# Serverless — Google Cloud Functionsnpm install @sentry/google-cloud-serverless# Frontend SPA (React)npm install @sentry/react# Mobile — React Nativenpx @sentry/wizard@latest -i reactNative

Step 2 — Initialize Sentry for Each Architecture Pattern

Monolith — Single Project, Module Tags

One DSN, one project. Separate concerns with module tags and team ownership rules.

// instrument.mjs — load via: node --import ./instrument.mjs app.jsimport * as Sentry from '@sentry/node';Sentry.init({  dsn: process.env.SENTRY_DSN,  environment: process.env.NODE_ENV,  release: process.env.APP_VERSION,  tracesSampleRate: 0.1,  initialScope: { tags: { app: 'monolith' } },});// Tag errors by module so each team sees only their issuesfunction captureModuleError(module: string, error: Error) {  Sentry.withScope((scope) => {    scope.setTag('module', module);    scope.setTag('team', getTeamForModule(module));    Sentry.captureException(error);  });}// Module-based breadcrumbs for traceabilitySentry.addBreadcrumb({ category: 'auth', message: 'Login attempt', level: 'info' });captureModuleError('auth', new Error('Token expired'));// Dashboard ownership: tags.module:auth → #platform-team

Microservices — Project-per-Service, Distributed Tracing

Each service gets its own Sentry project. A shared config package keeps init consistent.

// packages/sentry-config/index.ts — shared across all servicesimport * as Sentry from '@sentry/node';export function initServiceSentry(serviceName: string) {  Sentry.init({    dsn: process.env.SENTRY_DSN,    environment: process.env.NODE_ENV,    release: `${serviceName}@${process.env.APP_VERSION}`,    serverName: serviceName,    tracesSampleRate: 0.1,    sendDefaultPii: false,    initialScope: {      tags: {        service: serviceName,        cluster: process.env.K8S_CLUSTER || 'default',        namespace: process.env.K8S_NAMESPACE || 'default',      },    },  });}// Usage: initServiceSentry('api-gateway');

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.

// AWS Lambda — handler.tsimport * as Sentry from '@sentry/aws-serverless';Sentry.init({  dsn: process.env.SENTRY_DSN,  environment: process.env.STAGE,  tracesSampleRate: 0.1,});export const handler = Sentry.wrapHandler(async (event, context) => {  Sentry.setTag('function', context.functionName);  Sentry.setTag('region', process.env.AWS_REGION);  // Track cold starts  const isColdStart = !global.__sentryWarm;  global.__sentryWarm = true;  Sentry.setTag('cold_start', String(isColdStart));  const result = await processRequest(event);  return { statusCode: 200, body: JSON.stringify(result) };});// wrapHandler auto-calls flush() — do NOT call it yourself (double-flush causes timeout)

// Google Cloud Functions — index.tsimport * as Sentry from '@sentry/google-cloud-serverless';Sentry.init({ dsn: process.env.SENTRY_DSN, tracesSampleRate: 0.1 });export const httpHandler = Sentry.wrapHttpFunction(async (req, res) => {  res.json(await processRequest(req.body));});export const eventHandler = Sentry.wrapCloudEventFunction(async (event) => {  await processEvent(event.data);});

Event-Driven — Kafka, SQS, and Message Queues

Propagate trace context through message headers so consumer spans connect to producer traces.

import * as Sentry from '@sentry/node';// Producer: embed trace context in message headersasync function publishToKafka(topic: string, payload: object) {  const activeSpan = Sentry.getActiveSpan();  const headers: Record<string, string> = {};  if (activeSpan) {    headers['sentry-trace'] = Sentry.spanToTraceHeader(activeSpan);    headers['baggage'] = Sentry.spanToBaggageHeader(activeSpan) || '';  }  await Sentry.startSpan(    { name: `kafka.produce.${topic}`, op: 'queue.publish' },    () => kafka.send({ topic, messages: [{ value: JSON.stringify(payload), headers }] })  );}// Consumer: continue the producer's traceasync function consumeFromKafka(message: KafkaMessage) {  const headers = message.headers || {};  Sentry.continueTrace(    {      sentryTrace: headers['sentry-trace']?.toString(), // Buffer → string      baggage: headers['baggage']?.toString(),    },    () => {      Sentry.startSpan(        { name: `kafka.consume.${message.topic}`, op: 'queue.process' },        async (span) => {          try {            await processMessage(message);            span.setStatus({ code: 1 });          } catch (error) {            span.setStatus({ code: 2, message: 'consumer_error' });            Sentry.captureException(error);            throw error;          }        }      );    }  );}

For SQS consumers on Lambda, see event-driven deep-dive.

Frontend SPA — Browser and React

import * as Sentry from '@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 break  tracePropagationTargets: ['localhost', /^https:\/\/api\.yourapp\.com/],});

Route-based transactions, error boundaries, and session replay configuration: see frontend SPA deep-dive.

Mobile — React Native

import * as Sentry from '@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,});export default Sentry.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:

1. @sentry/react creates a transaction on user click
2. Browser SDK adds sentry-trace + baggage headers to fetch()
3. API gateway (@sentry/node) auto-continues the trace
4. API gateway calls payment-service — headers propagate via HTTP
5. payment-service publishes to Kafka — headers injected manually (see event-driven pattern)
6. 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:

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

See also: Full error reference

Examples

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.

See also: Full examples

Resources

• Node.js SDK Guide
• AWS Lambda Guide
• Google Cloud Functions Guide
• React SDK Guide
• React Native SDK Guide
• Distributed Tracing
• Session Replay
• Performance Monitoring

Next Steps

• Run the sentry-performance-tuning skill to optimize tracesSampleRate and tracesSampler for production traffic volumes
• Use sentry-cost-tuning to set rate limits and event budgets per project
• Configure sentry-deploy-integration to tie releases to deploys for regression detection
• Set up sentry-multi-env-setup to manage DSN routing across staging/production
• Apply sentry-reliability-patterns for retry logic and circuit breakers around Sentry calls