[sentry-junior]

Refs #1956

Stacked on #1960 (base junior/1956-telemetry-request-deadline); merge it after #1960.

With ingest stalled, #1960 gets a command out in about 6.6 s, and the telemetry it tried to send is dropped. This PR keeps that telemetry on disk and retries it later. It also stops hitting the network after the first failure, so a command's exit waits for one request deadline instead of two.

Design

• Store (telemetry/offline-store.ts, new telemetry_envelope_queue table, schema v21).
  • Envelopes are written with serializeEnvelope as BLOBs, since attachments can be binary, and read back with parseEnvelope. A row that no longer parses is dropped.
  • is_error marks envelopes that contain an event item. Each row's max age depends on it.
  • Each write drops expired rows and the rows over the caps, in one window query. Envelopes without an error go first, oldest first; errors are dropped only after those.
  • Reads claim rows with DELETE ... WHERE id IN (SELECT ... LIMIT n) RETURNING, so two CLI processes never get the same envelope.
  • A claimed envelope that fails again goes back with its original age, so a retry never extends it.
  • Store errors are logged at debug level and never reach the command. The table is a cache table: repair may drop it.
• Transport (telemetry/offline-transport.ts). makeOfflineTransport from @sentry/core wraps the zstd transport, which keeps fix(cli): Let the CLI exit on its own instead of forcing it on macOS #1960's 3 s request deadline. Redaction still runs first, so stored envelopes are already redacted.
• Metrics aren't stored. shouldStore returns false for trace_metric envelopes. They're sent as usual and dropped on failure, or skipped while the breaker is open. A long-running command emits runtime metrics every 5 s, and old ones are worth little. When they were stored, they filled the store during an outage and pushed sessions and transactions out of the caps. A metrics envelope can still be the probe that closes the breaker.
• Breaker, per transport:
  • The first network error or timeout opens it. While it's open, shouldSend returns false and envelopes go straight to disk.
  • After BREAKER_COOLDOWN_MS (5 minutes), the next envelope goes out as a probe. Envelopes sent while the probe is in flight go to disk.
  • Any HTTP response to the probe closes the breaker and sends the next 10 stored envelopes. A failure re-opens it for another 5 minutes.
  • Why 5 minutes: short commands never live that long, so they keep one deadline and then disk. A long-running process pays one deadline-bound request every 5 minutes while ingest is down, and starts delivering what it stored within 5 minutes of recovery, far inside the 4-day age limit.
• Drain. Early in withTelemetry(), the CLI claims up to 10 stored envelopes and sends them without awaiting. The close(3000) on exit waits for them. Each resend gets a fresh sent_at: Relay shifts item timestamps by the gap between sent_at and receipt, so a stale sent_at would move them forward.
• sentry mcp uses the store only when it reports to the CLI's project, that is with no --sentry-dsn or SENTRY_DSN (useCliDsn). Then it wraps fix(cli): Let the CLI exit on its own instead of forcing it on macOS #1960's makeNodeTransportWithDeadline, sends up to 10 stored envelopes at startup, and recovers through the breaker. close(5000) on disconnect is unchanged. With an override, it keeps the plain transport. The gate is small on purpose: removing the override is happening in a separate PR on main.
• Opt-out. When telemetry is off, withTelemetry() and sentry mcp delete the stored envelopes. They check for rows first, so an opted-out run against a read-only database prints no warning.
• Library mode never touches the store. It keeps the plain zstd transport, with no drain and no clearing.

SDK behavior this relies on (@sentry/core 11.6.0, transports/offline.js and base.js):

• A send that throws, including our abort, is stored and resolves {}. If shouldSend returns false, the SDK throws internally, so that envelope is stored too.
• Any HTTP response is returned as is, so a 4xx or 5xx is dropped and not stored. base.js records an outcome only for 413 (send_error) and for thrown errors (network_error). In the CLI project over the last 30 days, client reports show network_error on about 82k errors, 15k sessions, 13k transactions, and 106 logs, and send_error (413) on 88 transactions. The loss is network errors, which the store covers.
• If shouldStore returns false (our metrics rule), the SDK rethrows the error instead of storing. client.sendEnvelope catches it.
• Client reports are never stored. With the breaker open, they fail fast instead of waiting for the network.
• createTransport drops rate-limited items before the send, so they are never stored.
• The store's shift always returns nothing, which turns off the SDK's timer-driven retries. Those send one envelope 100 ms after each success, or on a backoff starting at 5 s. When one fires during the exit flush, its request keeps the process alive past the flush, and such requests can chain. sendStored replaces them.

Limits

• At most 100 envelopes and 4 MiB. A single envelope larger than 4 MiB is dropped instead of stored. Before, storing one emptied the store; Bugbot found it.
• Envelopes with an error event keep 30 days. Relay sets an event's max_secs_in_past to the project's retention (90 days by default, relay-server/src/processing/utils/event.rs), and past that it only replaces the timestamp with the received time.
• Everything else keeps 4 days, a day under Relay's 5-day limits:
  • Older sessions are dropped (max_session_secs_in_past).
  • Transactions must fall inside the metrics aggregator's max_secs_in_past.

Measured on the rebuilt npm bundle (dist/bin.cjs), Node 22, Linux:

• Ingest was an HTTPS CONNECT proxy, so the runs used the SDK's proxy transport path.
• In the stalled runs, the proxy accepted the tunnel and then stayed silent. In the healthy runs, it terminated TLS with a test CA (NODE_EXTRA_CA_CERTS) and answered 200.

Ingest	Command	#1960	This PR
stalled	help	6.19–6.34 s	3.22–3.43 s
stalled	cli defaults	6.31–6.40 s	3.32–3.41 s
healthy	help	0.23–0.36 s	0.23–0.37 s

• Short runs: 8 stalled runs stored 16 envelopes. The next healthy run sent 10 of them plus its own. The run after that sent the other 6 and emptied the store.
• sentry local serve, stopped before the cooldown:
  • The store started with 6 envelopes, and ingest was stalled.
  • The startup drain timed out and requeued them.
  • Ingest was switched to healthy at 10 s, and SIGINT came at 20 s.
  • The server exited in 0.02 s with nothing sent, because the breaker was still open, and stored its exit telemetry.
• sentry local serve, run past the cooldown (re-run after metrics stopped being stored):
  • Four stalled help runs (3.21–3.38 s each) left 8 envelopes in the store: 4 transactions and 4 sessions.
  • local serve started with ingest stalled, and ingest turned healthy at 20 s. The startup drain timed out and requeued its envelopes. With the breaker open, the store grew to only 9; the metrics emitted every 5 s were dropped.
  • At about 305 s, a metrics envelope went out as the probe and succeeded. All 9 stored envelopes followed at once, with a fresh sent_at: sessions, transactions and a log.
  • At 330 s, SIGINT exited in 0.13 s. The store ended empty, and ingest received 19 envelopes.
  • Before this change, the same scenario ended with 63 envelopes still stored, 60 of them trace_metric.
• Opt-out: a run with SENTRY_CLI_NO_TELEMETRY=1 after stalled runs left the store empty.
• sentry mcp: on this branch the bundle sends no telemetry, because of a separate bug on main: Sentry.init runs inside buildCommand's pre-init exec span, so the client is lost. fix(cli): Bind the sentry mcp telemetry client so it sends anything #1970 fixes it. Until fix(cli): Bind the sentry mcp telemetry client so it sends anything #1970 merges, this PR's MCP path is covered by unit tests only.

Not run locally: six unrelated permission tests (EACCES/EPERM) fail in this sandbox because it runs with full capabilities. They fail the same way on #1960.

Open questions:

• Completion timing metrics (completion_telemetry_queue) are also trace_metric, so an outage now drops them, as it did before this PR. OK to leave them out of the store?

via @BYK.

--

View Session in Sentry

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated
sentry-local	Skipped		Nov 5, 2026 12:03am UTC

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 39b47e7. Configure here.}