| name | sentry-reliability-patterns |
| description | Build reliable Sentry integrations with graceful degradation, circuit breakers, and offline queuing.
Use when implementing fault-tolerant error tracking, handling SDK initialization failures,
building retry logic for Sentry transports, or ensuring apps survive Sentry outages.
Trigger with "sentry reliability", "sentry circuit breaker", "sentry offline queue",
"sentry graceful degradation", "sentry failover", or "resilient sentry setup".
|
| allowed-tools | Read, Write, Edit, Grep, Bash(node:*), Bash(pip:*), Bash(python*:*) |
| version | 1.51.0 |
| license | MIT |
| author | Jeremy Longshore <jeremy@intentsolutions.io> |
| tags | ["saas","sentry","reliability","resilience","circuit-breaker","offline-queue","graceful-degradation"] |
| compatibility | Designed for Claude Code, also compatible with Codex and OpenClaw |
Sentry Reliability Patterns
Overview
Build Sentry integrations that never take your application down via three pillars: safe initialization with graceful degradation, a circuit breaker that stops hammering Sentry when unreachable, and an offline event queue that buffers errors during outages. Every pattern prioritizes application uptime over telemetry completeness.
Prerequisites
@sentry/node v8+ (TypeScript) or sentry-sdk v2+ (Python)- A valid Sentry DSN from project settings at
sentry.io
- A fallback logging destination decided (console, file, or external logger)
- Understanding of your application shutdown lifecycle (signal handlers, container orchestration)
Instructions
Step 1 — Safe Initialization with Graceful Degradation
Wrap Sentry.init() in try/catch so an invalid DSN, network error, or SDK bug never crashes the app. Track initialization state with a boolean flag. Protect beforeSend callbacks with their own error boundary.
Create lib/sentry-safe.ts with initSentrySafe() and captureError(). See graceful-degradation.md for full implementation.
Key rules:
- Never let
Sentry.init() crash the process — wrap in try/catch, set sentryAvailable = false on failure
- Verify client creation with
Sentry.getClient() — invalid DSNs silently produce no client
- Always log errors locally as baseline before attempting Sentry capture
- Wrap user-supplied
beforeSend hooks in nested try/catch — return raw event on hook failure
Step 2 — Circuit Breaker for Sentry Outages
When Sentry is unreachable, continued attempts waste resources and add latency. Track consecutive failures and trip open after a threshold. After cooldown, enter half-open state and send a single probe.
Implement SentryCircuitBreaker class with closed/open/half-open states. See circuit-breaker-pattern.md for full implementation. Expose state via health-checks.md endpoint.
Key rules:
- Default: 5 failures to trip open, 60-second cooldown before half-open probe
- In open state, skip Sentry calls entirely and log to fallback
- On half-open success, reset to closed with zero failure count
