DebugBundle
SDKs

Rust SDK

Install the released Rust SDK for DebugBundle capture, tracing, Axum and Actix Web integration.

The Rust SDK is available on crates.io.

The SDK provides explicit error snapshots, logs, request capture, operation context, probes, recovery observations and bounded HTTP/local delivery. Its first framework integrations are Tower, Axum and Actix Web. Optional features keep the framework crates out of the core build.

Installation

cargo add debugbundle

Or add the dependency to Cargo.toml:

[dependencies]
debugbundle = "1.0.2"

Requires Rust 1.89 or newer. Enable framework and logging features only when using those integrations.

Initialize

Run this in application startup and retain client for the application lifetime. Set DEBUGBUNDLE_PROJECT_TOKEN in the server environment. The example sets environment and service explicitly; ..Config::default() supplies the remaining options. Initialization starts the client; panic observation and framework capture are explicit integrations. Flush only when verifying an event or during controlled shutdown.

use debugbundle::Config;

let client = debugbundle::init(Config {
    project_token: std::env::var("DEBUGBUNDLE_PROJECT_TOKEN").unwrap_or_default(),
    environment: "production".into(),
    service: "api".into(),
    ..Config::default()
});

Integrations

Tokio, Tower, Axum and Actix Web, composable tracing/log integrations and browser relays are supported.

Feature selection

For Axum and tracing, enable the optional features:

[dependencies]
debugbundle = { version = "1.0.2", features = ["axum", "tracing"] }

Select actix-web instead of axum for Actix applications. The framework features enable HTTP and private local relay storage. Other features are tower, local, log and the bounded testkit recording transport. The declared compiler floor is Rust 1.89; current/previous stable CI lanes use 1.100.0/1.99.1. Axum 0.8, Actix Web 4, Tower 0.5 and Tokio are qualified through independent consumer applications. Warp, Rocket, Tonic and WebAssembly are outside the first-release scope.

Native logging

Compose client.tracing_layer() with the application's existing tracing_subscriber registry. Use primitive structured fields for SDK evidence; the SDK does not evaluate custom formatting. With log, client.logger() can explicitly tee an existing sink. Its fallible try_install() preserves an already installed logger. Select one SDK sink when bridging log and tracing.

Logging a plain multiline message remains a log. A real typed native error or an explicit safe snapshot can produce exception evidence. Exact occurrence tokens pair a successfully admitted error log with middleware reporting in the same operation; nearby timestamps or matching messages never imply identity.

Axum and Actix Web

For Axum, apply debugbundle::axum::DebugBundleLayer::new(client.clone()) to the router. The generic Tower integration is debugbundle::tower::DebugBundleLayer. For Actix, wrap the app with debugbundle::actix_web::DebugBundleMiddleware::new(client.clone()).

Middleware records selected failed request outcomes, preserves native response and error behaviour, and exposes a request-owned Context. Axum uses Extension<Context>; Actix uses HttpRequest::extensions() with HttpMessage. Actix application state/futures can remain non-Send. Bodies are not automatically read; an application can explicitly insert an already-parsed, protected RequestBodySnapshot up to 8 KiB.

Request ownership ends on completion, cancellation or body drop. Use an operation handle's explicit future wrapper to propagate context into spawned work. X-DebugBundle-Trace-Id is separate from the operation ID. Outbound trace injection requires configured exact first-party origins and a trace_header_for decision.

Browser relay

Construct relay::Relay::new(client.clone(), relay::RelayOptions::default()). Merge debugbundle::axum::browser_relay(relay) into the Axum router, or register debugbundle::actix_web::browser_relay(relay) as an Actix service. Both mount POST and OPTIONS /debugbundle/browser.

The relay validates origin, content type and bounded streamed bodies, protects canonical browser debug/optional analytics events, and attaches the server token only to upstream HTTP. Connected mode durably retains an admitted batch before returning local acceptance. This differs from downstream ingestion acceptance; all downstream chunks need canonical acknowledgements before a delivered marker. Known acknowledgements keep their bounded record and file lease until persistence succeeds; callback pressure does not turn them into another send. A stalled write pauses that client's replay while flush and shutdown keep finite deadlines. Stable event IDs support retry deduplication, with no distributed exactly-once promise across a crash or shutdown at the acknowledgement/persistence boundary.

Use verified native socket facts for peers/TLS. Forwarded headers are trusted only from explicitly configured exact proxy peers. Configure allowed frontend origins and the optional shared limiter for multiple replicas. The relay is exempt from application member-token authentication/CSRF middleware at this exact path; its boundary is origin validation, rate limiting and canonical browser validation.

Private files and durable relays have native Linux, macOS and Windows implementations. Other file platforms fail closed. Both extracted relay adapters are exercised with the published Browser SDK, including debug, optional analytics, mixed batches, beacon and keepalive fallback.

Relay bodies are limited to 256 KiB and 100 events, with a five-second streamed-body deadline. Each client shares eight ingress slots and 4,096 IP buckets; the default rate is 60 requests/minute/IP. A spool is bounded to 1,000 physical files and 100 MiB. relay.status() reports readiness/pending records/storage failures; relay.flush_async(timeout) attempts a bounded drain before client shutdown. Missing credentials or disabled delivery return unavailable status, never a false successful receipt.

Keep the guard returned by client.install_panic_observer() alive if you opt into panic observation. Process aborts do not guarantee delivery.

First-event verification

Use an explicit setup event in a development or staging application, then confirm the matching service and environment in a received event or incident. Initialization, a healthy status and an empty queue are not delivery receipts. Keep the application running long enough for delivery; use bounded flushing only in tests or controlled teardown, never in a request handler.

Select default-features = false, features = ["local"] on the dependency:

use debugbundle::{Client, Config, Context, ExceptionSnapshot};
use std::time::Duration;

let client = Client::new(Config::local("checkout-api", ".debugbundle/local/events"));
client.capture_exception(
    &ExceptionSnapshot::new("SetupCheck", "Synthetic local Rust event"),
    &Context::default(),
);
let outcome = client.flush(Duration::from_secs(2));

Check client.status() and outcome.accepted_events, then run debugbundle process and debugbundle inspect from the application's repository. Capture may decline under contention or overload; if no event was accepted, check status and retry the explicit verification event. drained alone can also mean records were dropped or rejected.

Connected Rust always uses HTTP, including in development. Local files require Config::local; no automatic network fallback occurs. Keep browser and backend services distinct, for example checkout-web and checkout-api, within the same system project.

For connected delivery, confirm the event in DebugBundle and inspect its incident with the CLI. For local-file delivery, run debugbundle process followed by debugbundle inspect <incident-id>. A local file or mock endpoint receipt proves only that destination; it does not prove cloud acceptance.

Configuration

The complete configuration reference lists defaults, constraints and the four environment variables. Rust uses snake_case methods: capture_exception, capture_error, capture_log, capture_message, capture_request, set_context, probe and bounded flush/flush_async. Client::new and init initialise a client.

set_context(&Context) replaces protected persistent application metadata. Request context and explicit per-capture context overlay it. start_operation owns request/command/job execution context; completion/drop revokes derived handles. capture_recovery requires local opt-in, valid reader proof and permitted server policy. Eager probe retains protected values; probe_lazy defers producers, and heavy probes remain dormant without activation.

See runtime and API boundaries and compiled examples for vanilla, Tokio, Tower, Axum, Actix, logging and safe anyhow/thiserror integration. Hooks run on a bounded worker, valid replacements are protected again, and remote capture policy cannot be overridden locally.

Config::from_env() reads DEBUGBUNDLE_PROJECT_TOKEN, DEBUGBUNDLE_SERVICE, DEBUGBUNDLE_ENVIRONMENT and optional DEBUGBUNDLE_ENDPOINT. Connected mode always uses HTTP; Config::local selects local files explicitly. See the configuration reference.

Capture explicit snapshots

use debugbundle::{Client, Config, Context, ExceptionSnapshot};
use std::time::Duration;

let client = Client::new(Config::from_env());
client.capture_exception(
    &ExceptionSnapshot::new("CheckoutFailure", "payment operation failed"),
    &Context::default(),
);
let outcome = client.shutdown(Duration::from_secs(2));

Construct the client once during application bootstrap. Setup is synchronous; rejected custom configuration values are disposed with separate panic-unwind boundaries. Application destructors that block or abort cannot be sandboxed, so keep initialization out of request paths. Capture and admitted-client cleanup use the SDK's bounded worker design.

Set DEBUGBUNDLE_PROJECT_TOKEN, DEBUGBUNDLE_SERVICE and DEBUGBUNDLE_ENVIRONMENT on the server. DEBUGBUNDLE_ENDPOINT optionally selects a self-hosted HTTPS ingestion endpoint. Keep the token out of browser code.

Borrowed Rust errors use ExceptionInput::borrowed(&error). The SDK does not invoke arbitrary Display, Debug or Error::source methods; opaque details remain unavailable. Supply owned ExceptionSnapshot causes, aggregate children, frames or stacks when the application can safely provide them. A supplied runtime stack remains distinct from a stack observed at capture time.

Safety and verification

Mandatory credential protection applies before SDK retention and after owner hooks. Queued plus in-flight events share finite count, byte and age allowances. SDK-owned HTTP uses finite response deadlines and strict indexed acknowledgements. Unknown or revoked reader proof strips optional evidence without erasing a valid primary error. Explicit recovery observations never independently create or resolve an incident.

Capture does not run owner hooks, arbitrary formatting or network I/O on the application caller. One bounded callback worker owns application callbacks; a stalled callback keeps its existing slot through shutdown. Explicit panic observation preserves the previous hook and native unwind/abort behaviour. Panic delivery under abort, OOM or signals is best effort and no crash persistence is advertised.

The core implementation record at spec/sdks/rust-sdk-progress.md distinguishes source tests, extracted-crate consumers, Core integration and registry acceptance. SDK updates remain an explicit application dependency change.

Release qualification

Every release requires all eight qualification jobs for its exact source and crate on Linux x64/arm64, macOS arm64 and Windows x64. The release workflow matches the published archive to that qualified checksum and verifies real registry-installed standalone, Axum and Actix applications. Use the receipts for the version you install; an earlier release's passing run does not qualify a later patch.

On this page