Developer guide

Monitoring

Configure errors, release health, performance and feedback alongside replayable capsules on all four platforms.

Monitoring versus capsules

A capsule holds the recording used for replay. Monitoring sends smaller envelopes: errors grouped into issues, sessions for release health, transactions/spans for performance, and feedback. It is enabled by default once the SDK is connected (an SDK token, or an explicit backend), independently of production capsule sampling. Replay sessions do not send monitoring telemetry.

An error event can exist without a capsule. A captured failure links the event and capsule through capsuleId and manifest.monitoring. A native crash event does not imply a replayable crash capsule: Android ANRs/NDK crashes and iOS signals/Swift traps have different capture boundaries.

Configure your platform

These are configuration fragments to merge into the initialization shown on each SDK page. Do not initialize the SDK twice. Replace release names and API hosts with your app's values.

Flutter

monitoring: MonitoringOptions(
  tracesSampleRate: 0.2,
  tracePropagationTargets: ['api.example.com'],
  beforeSend: (event, hint) => event, // return null to drop
),

Pass this to BugCapsuleConfig. Use MonitoringOptions.disabled to disable monitoring. BugCapsule.setUser(const MonitoringUser(id: 'qa-user')) sets context; BugCapsule.captureException(error, stackTrace: stack) sends a handled error. Use the feedback form or showBugCapsuleFeedback for user reports. Native plugin crashes/ANRs require native SDK instrumentation.

Android

// Add to the BugCapsuleConfig.builder() chain:
.tracesSampleRate(0.2)
.tracePropagationTargets("api.example.com")
.errorSampleRate(1.0)
// .monitoring(false) disables monitoring

BugCapsule.captureException(error) sends an event; BugCapsule.reportError(error) can also capture a failure. Monitoring types such as User live in dev.bugcapsule.android.monitoring. BugCapsule.addBreadcrumb("coupon applied", "cart") adds context. Optional bugcapsule-ndk handles native crash events and bugcapsule-sqlite adds SQLite/Room spans; SQL spans are not database checkpoint/replay support.

iOS

config.monitoring = BugCapsuleMonitoringOptions(
    tracesSampleRate: 0.2,
    tracePropagationTargets: ["api.example.com"])
// Or: config.monitoring = .disabled

Set this before BugCapsule.start. Use BugCapsule.captureException(error), BugCapsule.setUser and BugCapsule.addBreadcrumb for explicit context. Signals and Mach exceptions are persisted by the native crash writer and sent on the next launch; they do not produce replayable capsules. Keep URLSession instrumentation enabled for HTTP spans.

Web and React

// Add to the existing await BugCapsule.init({...}) options:
release: 'shop-web@1.4.0+52',
environment: 'qa',
tracesSampleRate: 0.2,
tracePropagationTargets: ['api.example.com'],
// monitoring: false disables all monitoring envelopes

BugCapsule.setUser({ id: 'qa-user' });
BugCapsule.addBreadcrumb({ category: 'cart', message: 'coupon applied' });
BugCapsule.captureMessage('checkout diagnostic', 'info');
// At logout:
BugCapsule.setUser(null);

captureException sends an event; reportError can create a linked failure capsule. showFeedbackWidget or React's BugCapsuleFeedbackWidget provides feedback UI. Monitoring includes fetch/XHR breadcrumbs, browser error handlers and release-health sessions. Performance entries vary by browser; async spans share page-wide scope, so concurrent work can affect parent attribution.

Privacy and sampling

Use capsule sampling for recording cost, errorSampleRate for error traffic and tracesSampleRate for performance traffic. Trace sampling defaults to zero; remote settings can override the local trace rate. Fatal or capsule-linked errors can bypass ordinary error sampling. Session tracking has its own switch. Review effective project settings rather than assuming every rate is an app-side ceiling.

Redaction runs before envelope persistence, but names, email addresses, feedback text and business identifiers are not automatically private. Supply only needed user fields, clear context on logout, and review beforeSend and breadcrumb hooks. A feedback form can collect contact details; make that choice explicit in your product. Application consent handling must cover both capsules and monitoring.

tracePropagationTargets controls which destinations receive traceparent and baggage. Web defaults to same-origin; native examples require explicit destinations. Cross-origin APIs must permit those headers. The BugCapsule ingestion origin must permit envelope requests including Content-Encoding. Trace headers are not replay inputs.

Delivery and remote controls

Monitoring uses a separate bounded envelope outbox, normally 30 envelopes / 5 MiB / 7 days, with retries and remote-config gating. Offline events may arrive after a later launch. monitoringEnabled: false stops monitoring and purges queued envelopes; it does not turn off capsules. The project kill switch stops both. Do not treat a flush attempt during browser unload as guaranteed delivery.

Check the integration

1. Send a distinctive handled QA error. Find its issue/event in the dashboard and confirm release, environment and context.
2. Trigger a known failure and check its capsule link. Confirm a monitoring-only error is not presented as replay evidence.
3. Enable tracing for a controlled QA session, exercise a screen and HTTP request, and inspect spans. Check the intended destination receives trace headers.
4. Submit synthetic feedback and verify the linked event. Check logout clears user context.
5. Upload matching debug files and trigger an error from that exact build. Confirm readable frames.

Troubleshooting monitoring