sentry-reliability-patterns

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 <[e-mail]>
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