SDKs
SDKs
Capture production errors, logs, and context from any runtime. DebugBundle SDKs share a universal interface across all languages.
DebugBundle SDKs are lightweight, zero-config libraries that capture exceptions, logs, HTTP context, and diagnostic probes at runtime and ship them to DebugBundle for processing into debug bundles.
Universal Interface
Every SDK implements the same public API, regardless of language:
| Method | Purpose |
|---|---|
init(config) | Initialize the SDK with project token, environment, and options |
captureException(error) | Capture an exception with full stack trace and context |
captureError(error) | Required convenience alias for captureException |
captureLog(message, level) | Capture a structured log entry |
captureMessage(message) | Capture a message (delegates to captureLog with "info" level) |
captureRequest(req, res) | Capture an HTTP request/response pair |
setContext(key, value) | Set persistent context that attaches to all future events |
probe(label, data) | Buffer diagnostic data in an always-on ring buffer |
flush() | Force-send all buffered events |
Safety Guarantees
All SDKs follow the same safety contract:
- Never throw uncaught exceptions into your code
- Never block the request/response cycle
- Never crash the host process
- No side effects on import — only
init()activates the SDK - Graceful degradation — if the buffer fills, events are dropped silently
- Redaction before transmission — sensitive fields are scrubbed before any data leaves the process
V1 Parity Matrix
| Capability | Node.js | Browser | Python | PHP | WordPress | Java | .NET | Go | Ruby | Android | iOS | React Native |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Status | Shipped | Shipped | Shipped | Shipped | Shipped via GitHub Releases | Shipped | Released v1.1.1 | Shipped | Shipped | Released v1.1.0 | Released v0.1.1 | Released v1.1.0 |
| Package | @debugbundle/sdk-node | @debugbundle/sdk-browser | debugbundle-python | debugbundle/sdk-php | debugbundle-wordpress | Maven com.debugbundle modules | NuGet DebugBundle.Sdk plus DebugBundle.* integrations | github.com/debugbundle/debugbundle-go | debugbundle | Maven com.debugbundle Android modules | https://github.com/debugbundle/debugbundle-swift / CocoaPods DebugBundle | @debugbundle/sdk-react-native |
| Unhandled exceptions | Yes | Yes | Yes | Yes | Yes, through PHP SDK | Yes | Yes | Yes | Yes | Yes, next-launch crash replay | Bounded next-launch crash replay helpers | Yes, global JS hooks plus native crash handoff |
| Handled exception capture | Yes | Yes | Yes | Yes | Yes, through PHP SDK | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| Request 5xx incident capture | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes, OkHttp/Ktor | Yes, URLSession/Alamofire | Yes, fetch/XHR |
| Browser first-party 5xx promotion | N/A | Yes | N/A | N/A | Yes, through browser SDK | N/A | N/A | N/A | N/A | N/A | N/A | N/A |
| Breadcrumbs | No | Yes | No | No | Yes, through browser SDK | No | No | No | No | Yes, screen/app/network | Yes, screen/app/network | Yes, React Navigation/app/network/action |
| Relay support | Full relay handler + adapters | Relay client path | Full relay handler | Full relay handler | WordPress REST relay | Spring Boot and servlet relay routes | ASP.NET Core endpoint mapping | Full relay handler | Rack middleware + Rails route | N/A, direct mobile client | N/A, direct mobile client | N/A, direct mobile client |
| Remote config and capture policy | Yes | Yes | Yes | Yes | Yes, backend SDK path | Yes | Yes | Yes | Yes | Yes | Yes | Yes, through native foundations |
| Local capture-rule enforcement | Drop + sampled-out sample | Demote, sample, drop | Server backstop | Server backstop | Browser SDK path + server backstop | Server backstop | Capture policy locally, ingestion backstop | Server backstop | Server backstop | Server backstop | Server backstop | Native SDK enforcement plus ingestion backstop |
| Probes | Yes | Yes | Yes | Yes | Yes, through bundled SDKs | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| Redaction defaults | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes, with Rails filters | Yes | Yes | Yes |
| Framework integrations | Express, Fastify, Next.js | Browser-native; works with React, Next.js client-side, Vue, Angular, Svelte, and vanilla apps | Django, Flask, FastAPI | Laravel, Symfony | WordPress plugin wrapper | Spring Boot, servlet, JAX-RS/RESTEasy, WildFly/JBoss | ASP.NET Core, gRPC, Worker Service, Hangfire, Azure Functions isolated worker, Microsoft.Extensions.Logging, Serilog, NLog, log4net | net/http, Gin, Echo | Rails, Rack, Sidekiq | Android runtime, OkHttp, Ktor, Navigation, Compose, Timber | iOS runtime, URLSession, Alamofire, UIKit, SwiftUI, SwiftLog | React error boundary, React Navigation, Expo development builds |
| Local file transport | Yes | No | Yes | Yes | Relay spool for browser events | Yes | Yes | Yes | Yes | Offline queue | Offline queue | Offline queue |
Across all shipped SDKs, request failures with 5xx responses remain incident signals. On the Browser SDK, first-party 5xx fetch and XMLHttpRequest responses also stay in the breadcrumb trail while emitting standalone request_event signals for incident creation.
Transport Modes
SDKs automatically select the right transport based on your configuration:
| Mode | Destination | When |
|---|---|---|
| File | .debugbundle/local/events/ | Server-side local-only mode, or development/local environment in connected mode |
| Offline queue | App-private mobile storage | Android, iOS, and React Native offline, background, local, and deferred-flush paths |
| HTTP | POST /v1/events | Connected mode in staging/production |
| Relay | Same-origin POST /debugbundle/browser | Browser SDK (always relays through your backend) |
File transport uses atomic temp-file + rename to prevent partial writes. Android, iOS, and React Native use bounded app-private queues instead of writing directly to .debugbundle/local/events/.
Volume Control
All SDKs enforce automatic storm suppression to prevent runaway capture:
| Control | Behavior |
|---|---|
| Duplicate window | Within 30 seconds, only 3 identical events pass; the rest are suppressed |
| Loop detection | More than 10 events in 2 seconds triggers suppression mode |
| Suppression checkpoints | During suppression, one aggregate checkpoint event every 30 seconds |
| Auto-recovery | 60 seconds of silence resets suppression |
Combined with server-side capture policy (configurable presets: minimal, balanced, investigative) and project capture rules (demote, sample, drop), you can control what gets captured, what remains context-only, and what is discarded after known noisy patterns are identified.
Next Steps
- Node.js SDK — Full setup guide with Express, Fastify, Next.js, and logger integrations
- Browser SDK — Breadcrumbs, network capture, session controls, relay setup
- Python SDK — Django, Flask, FastAPI, and browser relay helpers
- PHP SDK — Laravel, Symfony, Monolog, and browser relay setup
- Java SDK — Spring Boot, servlet/JAX-RS, WildFly/JBoss, Javaagent, logging, and browser relay setup
- .NET SDK — ASP.NET Core, Microsoft.Extensions.Logging, gRPC, Worker Service, Hangfire, Azure Functions, logging adapters, and browser relay setup
- Go SDK — net/http, Gin, Echo, slog, zap, zerolog, and browser relay setup
- Ruby SDK — Rails, Rack, Sidekiq, Logger, Semantic Logger, and browser relay setup
- Android SDK — Crash replay, ANR/process-exit capture, offline queueing, OkHttp, Ktor, Navigation, Compose, Timber, and probes
- iOS SDK — SwiftUI, UIKit, URLSession, Alamofire, SwiftLog, crash replay, offline queueing, and probes
- React Native SDK — TypeScript API, React helpers, React Navigation, fetch/XHR trace propagation, Expo development builds, and native queues
- WordPress Plugin — Installable plugin with backend capture, frontend capture, and a built-in browser relay
- Universal Interface — Complete interface contract across all languages
- Browser Relay Setup — How browser events reach DebugBundle through your backend