@debugbundle/sdk-node

@debugbundle/sdk-node

Node.js SDK for DebugBundle.

Use this package to capture backend exceptions, request metadata, structured logs, runtime context, and probe data from Node.js services. It also ships browser relay handlers for full-stack apps that use @debugbundle/sdk-browser.

Requires Node.js 22 or newer.

Installation

npm install @debugbundle/sdk-node

Keep @debugbundle/sdk-node, @debugbundle/sdk-browser, @debugbundle/shared-types, and @debugbundle/redaction on matching versions when you pin them explicitly. Public examples must not mix JS SDK family versions.

Quick Start

import { debugbundle } from "@debugbundle/sdk-node";

debugbundle.init({
  projectToken: process.env.DEBUGBUNDLE_PROJECT_TOKEN,
  service: "checkout-api",
  environment: "production"
});

debugbundle.captureExceptions();
debugbundle.captureRejections();

Handled errors, logs, messages, and probes can be captured explicitly:

debugbundle.captureException(error);
debugbundle.captureLog("payment retry failed", "warning", { orderId });
debugbundle.captureMessage("checkout worker started");
debugbundle.probe("checkout.cart", { itemCount: cart.items.length });

await debugbundle.flush();

Configuration

Option	Default	Purpose
projectToken	none	Write-only DebugBundle project token. Required unless the SDK is disabled.
service	auto-detected or node-service	Service name shown on incidents and bundles.
environment	NODE_ENV or development	Runtime environment such as production, staging, or development.
projectMode	connected	Use local-only to write events to .debugbundle/local/events/.
endpoint	https://api.debugbundle.com/v1/events	Ingestion endpoint for connected mode or self-hosting.
enabled	true	Disable all capture without removing instrumentation.
redactFields	common sensitive fields	Additional field names to redact.
logLevel	warning	Minimum captured log severity.
sampleRate	1.0	Fraction of events to keep before transport.
batchSize	50	Events per batch before flushing.
flushInterval	2000	Flush interval in milliseconds.
maxBufferedEvents	1000	In-memory buffer cap before new events are dropped.
localEventsDir	.debugbundle/local/events	Local file transport directory.
requestTimeoutMs	5000	HTTP transport timeout in milliseconds.
maxProbeLabels	50	Maximum distinct probe labels buffered in memory.
maxProbeEntriesPerLabel	10	Maximum entries retained per probe label.
probeFlushOnError	true	Attach buffered probe data to captured exceptions.
captureConsole	false	Wrap console.error and console.warn.
autoDetectLoggers	true	Detect supported logger integrations when possible.
logger	none	Optional logger instance to attach during initialization.
transport	auto-selected	Custom transport function for tests or advanced routing.
fetchImpl	global fetch	Custom Fetch implementation.
beforeSend	none	Synchronous hook that receives a fully built event before buffering; return an event to keep it or null to drop it locally.
resolveModule	Node resolution	Custom module resolver for logger auto-detection.
onDiagnostic	none	Callback for SDK internal diagnostics.

Configuration source precedence

1. Explicit init(...) fields win.
2. Omitted environment and service values fall back to runtime detection or the package defaults.
3. Capture-policy fields and project capture rules are server-owned and arrive from GET /v1/sdk/config; they are not accepted from local SDK config.

Use process environment, framework config, or your own typed startup config to supply projectToken, service, and environment before calling init(...).

Local beforeSend hook

Use beforeSend for app-owned local policy such as final redaction or tenant-specific suppression before an event enters the SDK buffer. The hook runs after the SDK builds and redacts the event and before project capture rules, sampling, suppression, and transport.

debugbundle.init({
  projectToken: process.env.DEBUGBUNDLE_PROJECT_TOKEN,
  service: "checkout-api",
  environment: "production",
  beforeSend(event) {
    if (event.event_type === "log_event" && event.payload.message.includes("expected healthcheck")) {
      return null;
    }

    return event;
  }
});

If the hook throws or returns an invalid event, the SDK keeps the original event and emits an internal diagnostic. Use project capture rules first for operational noise because they are centralized and enforced by ingestion and worker backstops.

Remote capture rules

Active project capture rules arrive through GET /v1/sdk/config and are applied locally when the Node runtime can do so without changing application behavior:

• drop discards matching events before buffering and transport
• sample discards matching events only when the deterministic sampling decision resolves to sampled out
• demote still ships today and relies on ingestion/worker backstop enforcement, because the Node SDK does not have a browser-style breadcrumb/context downgrade channel yet

This keeps the project-wide rule contract consistent with the browser SDK while leaving room for richer backend-local demotion later.

Frameworks and Logging

The SDK supports vanilla Node.js plus Express, Fastify, and Next.js integration helpers. It can capture uncaught exceptions, unhandled rejections, request context, response status and duration, and supported logger output.

Logger capture is intentionally in-process. DebugBundle attaches to logger transports or handlers; it does not read application log files.

Browser Relay

Use a same-origin relay when pairing this package with @debugbundle/sdk-browser so browser JavaScript never receives the server-side project token.

Runtime	Import
Generic Node.js	@debugbundle/sdk-node/relay
Express	@debugbundle/sdk-node/relay/express
Fastify	@debugbundle/sdk-node/relay/fastify
Next.js API route	@debugbundle/sdk-node/relay/nextjs

See https://debugbundle.com/docs/sdks/browser-relay.

Relay behavior summary:

• same-origin is the default when allowedOrigins is omitted
• split frontend/backend hosts should set explicit allowed origins
• relay adapters answer allowed CORS OPTIONS preflight and add matching CORS headers to allowed POST responses
• requests must use Content-Type: application/json
• request bodies are capped at 256 KB
• per-IP rate limiting is enabled
• browser-supplied credentials and trust-sensitive fields are stripped
• local-only mode writes accepted batches to .debugbundle/local/events/
• connected mode can durably spool accepted batches before forwarding
• forwarding always uses the server-side project token
• disabling the relay or omitting a usable token leaves the host app running and the SDK status degraded or disconnected

Service naming guidance

Use separate service names for each deployable surface in one DebugBundle project. A common pattern is:

• browser frontend: checkout-web
• backend API: checkout-api
• worker: checkout-worker

When the browser sends through this relay, keep the browser service name browser-specific unless you intentionally override it for a shared edge/backend surface.

Safe startup behavior

• Connected mode without a usable projectToken must not crash the host process.
• status() reports disconnected or degraded when capture cannot ship successfully.
• Local-only mode stays valid without a remote token and writes event files instead.
• Failed or rejected transport responses never bubble uncaught exceptions into application code.

First-event verification

Minimal application check:

import { debugbundle } from "@debugbundle/sdk-node";

debugbundle.init({
  projectToken: process.env.DEBUGBUNDLE_PROJECT_TOKEN,
  service: "checkout-api",
  environment: "development",
  endpoint: "http://127.0.0.1:3004/v1/events"
});

debugbundle.captureMessage("debugbundle node smoke", "warning");
await debugbundle.flush();
console.log(debugbundle.status());

Repository-level verification uses the same clean-install smoke path as CI and release:

pnpm build
pnpm smoke:packed

Safety Guarantees

• SDK failures are caught internally.
• The SDK does not block the request/response cycle for ingestion.
• Sensitive fields are redacted before transport.
• Duplicate event storms are suppressed locally.
• Local-only mode writes event files atomically.

Documentation

• Node.js SDK docs: https://debugbundle.com/docs/sdks/node
• SDK overview: https://debugbundle.com/docs/sdks
• Browser relay: https://debugbundle.com/docs/sdks/browser-relay
• Repository: https://github.com/debugbundle/debugbundle-js

License

AGPL-3.0-only.