Privacy and delivery

Only publicKey is required:

const problems = createProblems({
  publicKey: "YOUR_PUBLIC_KEY",
  beforeSend(error) {
    // Remove all error detail while still counting the failed call.
    return null;
  },
});

beforeSend receives only the error message and optional stack. It must return that shape or null, synchronously. A throwing, asynchronous, or invalid hook causes that event to be discarded. Common secret patterns are redacted after the hook and again in the backend processor. Redaction is not a complete privacy filter: error text and operation names may contain user data. Use stable operation names and a hook appropriate to your data.

Set enabled: false, PROBLEMS_REPORTING=off, or DO_NOT_TRACK=1 to disable telemetry and explicit status checks. No arguments or successful outputs are collected. The SDK installs no process handlers and sends nothing merely because it was imported.

Delivery

Events are held in memory and batched every two seconds, up to 50 events or 64 KiB. At most 1,000 events are pending. New events beyond that bound are dropped. Network/server failures are retried up to three attempts with stable event IDs; 429 responses honor Retry-After, capped at one minute. Other 4xx responses are permanent failures. A process exit can lose buffered events.

await problems.flush() returns { pending, dropped }, with cumulative dropped count and current undelivered count. Acknowledged batches have entered a durable queue. Grouping, redaction, and chart storage happen afterward; duplicate queue deliveries are idempotent. The chart shows processed calls, not all calls that may have happened while instrumentation was disabled or delivery was unavailable.

The overview refreshes every second for short ranges and every five seconds for long ranges. Hidden tabs pause; returning fetches a fresh snapshot. Delivery and processing delays can make activity appear later. The five-second freshness objective is a target, not a guarantee.

Telemetry is retained for 30 days. Future timestamps are clamped to receipt time and marked adjusted. Late events inside retention update their original buckets.

Optional status checks

checkStatus({ surface, operation, error }) looks for an already published match on the project’s agent status page. It returns matched, no_match, or unavailable without recording another event or waiting for telemetry processing. Network reads time out after 500 ms with no retries. Matches and misses are cached for at most 15 seconds; matches expire sooner at their publication deadline. Unavailable results are cached for one second. Identical concurrent checks share one request. Nothing polls in the background.

The same beforeSend hook runs separately for recording and checking. Keep it deterministic so both use the same error text. Returning null withholds details from both paths; invalid hooks also prevent a lookup. Only the sanitized error message, operation, and source are sent to the matching endpoint, with no stack. Status responses contain only public titles, operation names, counts, timestamps, and the page URL. A successful lookup with no match does not establish health.

endpoint and fetch overrides exist for local development and tests. A custom endpoint also directs status checks to /v1/status/check on the same origin. Public keys identify projects for telemetry and public status matching. They never authorize private reads. Owners and admins can rotate a key in settings; old-key requests then fail. Already cached public context may remain visible for up to 15 seconds after publication is disabled.

Your agent status page address

In Settings → Public status page, enable publication and choose an address at your-name.problems.dev. You can also connect a custom address such as status.example.com under Custom domain. An organization owner or admin can:

1. Add a subdomain whose DNS they control.
2. Add the TXT ownership record shown in settings and a CNAME pointing the subdomain to domains.problems.dev. Keep both records in place and disable DNS proxying. Use a subdomain rather than a zone apex or wildcard.
3. Select Verify DNS records and wait for HTTPS to become ready. Settings checks automatically; DNS propagation and certificate issuance can take several minutes.

Connecting a domain does not enable publication. Once publication is enabled, both addresses serve the same page and /status.json feed. Disabling publication hides both. The SDK continues to use your public key and the Problems API; matching results link to the active custom address without any SDK configuration change.

Disconnecting stops the custom address immediately and returns SDK links to the Problems address. A previously cached SDK result can retain its old URL for up to 15 seconds. Certificate cleanup finishes in the background before the hostname can be used again. You can then remove its DNS records.