Universal SDK Interface

Every DebugBundle SDK implements this universal interface contract. Language-specific naming conventions differ (camelCase for JavaScript/PHP, snake_case for Python), 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), relay or http (browser)
• Connected → http transport

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 */ }
}

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 Comparison Matrix

Next Steps

• Node.js SDK — Full Node.js setup and framework integrations
• Browser SDK — Full Browser SDK setup with breadcrumbs and relay
• Python SDK — Python SDK (coming soon)
• PHP SDK — PHP SDK (coming soon)
• Browser Relay Setup — Relay architecture and backend setup