Universal SDK Interface

Every DebugBundle SDK implements this universal interface contract. Language-specific naming conventions differ (camelCase for JavaScript/PHP/Java/Kotlin/Swift, PascalCase methods for Go, snake_case for Python/Ruby), but the semantics, behavior guarantees, and volume control rules are identical.

Core Methods

Every SDK exposes these methods:

Language Naming Conventions

Configuration Fields

All SDKs accept these common configuration fields:

Browser-Specific Fields

Transport Modes

Transport is automatically selected based on your .debugbundle/local/connection.json mode:

• Local-only → file transport (server SDKs), app-private offline queue (mobile SDKs), relay or http (browser)
• Connected → http transport with SDK-specific buffering or offline retry

Event Envelope

Every captured event is wrapped in a standard envelope:

{
  "event_id": "evt_01HXYZ...",
  "event_type": "backend_exception",
  "timestamp": "2026-03-24T10:30:00.000Z",
  "service": { "name": "api-server", "environment": "production" },
  "sdk": { "name": "@debugbundle/sdk-node", "version": "1.0.0" },
  "context": { "user_id": "usr_123" },
  "payload": { /* event-type-specific data */ }
}

Backend Runtime Facts

Backend exception events include a payload.runtime object. Every backend SDK reports the runtime version; SDKs should also include safe process facts when the language exposes them without reading environment variables or secrets.

Current shipped scope: the Node.js SDK captures the full safe process-fact set. Python and PHP emit runtime version today and can receive the same fuller enrichment in their SDK-specific releases.

Event Types

Volume Control

All SDKs implement mandatory volume control to prevent event storms:

Duplicate Suppression

When the SDK captures the same error repeatedly:

1. First 3 occurrences in a 30-second window → sent normally
2. Subsequent duplicates → aggregated into a single error_suppressed event with occurrence count
3. Window resets after 30 seconds of silence

"Same error" is determined by fingerprinting: error class + message + top stack frame.

Loop Protection

Prevents runaway error loops from flooding the ingestion API:

1. Trigger: More than 10 identical errors in 2 seconds
2. Action: Force suppression — all events for that fingerprint held in buffer
3. Checkpoint: Every 30 seconds, one event released to check if the loop has stopped
4. Reset: After 60 seconds with no new occurrences, normal capture resumes

Buffer Retention

• Events are never dropped on transport failure
• SDK respects Retry-After headers from the ingestion API
• Buffer has a hard size limit (configurable per SDK) to prevent memory exhaustion
• On buffer overflow, oldest non-exception events are evicted first

Probes

Probes are diagnostic ring buffers that capture application state over time:

// Node.js
debugbundle.probe('db_pool', () => ({
  active: pool.activeCount,
  idle: pool.idleCount,
  waiting: pool.waitingCount,
}));

Probe Types

Ring Buffer

Probe data is stored in a fixed-size ring buffer (default 10 entries). When the buffer is full, the oldest entry is overwritten. This keeps memory usage constant regardless of probe frequency.

Safety Guarantees

Every SDK enforces these guarantees:

1. Never throw — SDK methods never throw uncaught exceptions into user code
2. Never block — SDK methods never block the request/response cycle
3. Never crash — SDK failures are caught internally and swallowed silently
4. Graceful degradation — If the ingestion API is unreachable, events are buffered and retried
5. Memory bounded — Buffers have hard limits to prevent memory exhaustion

Redaction

All SDKs apply automatic redaction before events leave the process:

Default Redacted Fields

password, secret, token, authorization, cookie, set-cookie, x-api-key, credit_card, card_number, cvv, ssn, social_security

Custom Redaction

debugbundle.init({
  projectToken: process.env.DEBUGBUNDLE_PROJECT_TOKEN,
  redactFields: ['x-custom-secret', 'internal_id'],
});

Custom fields are merged with defaults — you cannot disable default redaction.

SDK Support Snapshot

For the public V1 parity matrix, including 5xx request-failure behavior and relay support, see SDKs.

Next Steps

• Node.js SDK — Full Node.js setup and framework integrations
• Browser SDK — Full Browser SDK setup with breadcrumbs and relay
• Python SDK — Full Python setup and framework integrations
• PHP SDK — Full PHP setup and framework integrations
• Java SDK — Full Java setup across Spring Boot, servlet, JAX-RS, and app servers
• .NET SDK — Full .NET setup across ASP.NET Core, Worker Service, gRPC, Hangfire, Azure Functions, and logging adapters
• Go SDK — Full Go setup with HTTP frameworks, logger integrations, and relay support
• Ruby SDK — Full Ruby setup with Rails, Rack, Sidekiq, logger integrations, and relay support
• Android SDK — Full Android setup with crash replay, ANR capture, offline queueing, native HTTP instrumentation, and probes
• iOS SDK — Full iOS and iPadOS setup with SwiftUI, UIKit, URLSession, Alamofire, SwiftLog, offline queueing, crash replay helpers, and probes
• React Native SDK — Full React Native setup with TypeScript APIs, React helpers, navigation, network capture, Expo development builds, and native queues
• Browser Relay Setup — Relay architecture and backend setup