Observed by pointing real Sentry SDKs at tools/envelope-dumper. Captured with:
@sentry/node11.11.0 (Express app)@sentry/browser11.11.0 (CDN bundlebundle.tracing.logs.metrics.min.js)
Sanitized samples are in testdata/envelopes/. Each sample is a <name>.envelope body plus a <name>.request.json file with the method, path, query and relevant headers.
Not yet verified: Python and other SDKs, gzip-compressed bodies, the legacy /store/ endpoint, and attachments.
{scheme}://{public_key}@{host}[:port]/{project_id}
The SDK derives the ingest URL from the DSN:
POST {scheme}://{host}[:port]/api/{project_id}/envelope/
| Aspect | Node SDK | Browser SDK |
|---|---|---|
| Method | POST |
POST |
| Auth | query: sentry_key, sentry_version=7, sentry_client |
same, in query |
X-Sentry-Auth header |
not sent | not sent |
Content-Type |
not sent | text/plain;charset=UTF-8 (avoids CORS preflight) |
Content-Encoding |
none observed (bodies up to 30 KB) | none |
| CORS | n/a | yes. The server must answer OPTIONS and send Access-Control-Allow-Origin. |
Server requirements:
- Accept the key from the query string or from the
X-Sentry-Auth: Sentry sentry_key=...header, because other SDKs use the header. - Ignore
Content-Type. - Support
Content-Encoding: gzip(and ideallydeflate/br). - Respond
200with{"id": "<event_id>"}. Use429+Retry-After/X-Sentry-Rate-Limitsfor rate limiting.
Newline-delimited:
<envelope header JSON>\n
<item header JSON>\n
<item payload>\n
<item header JSON>\n
<item payload>\n
...
- If the item header has
length, the payload is exactly that many bytes, which can be binary. Otherwise the payload runs to the next\n. - Envelope header:
event_id(events only),sent_at,sdk {name, version}, andtrace.traceis the dynamic sampling context:trace_id,public_key,environment,transaction,sampled,sample_rate. Aclient_reportenvelope has an empty header{}.
type |
Item header | Payload | Action |
|---|---|---|---|
event |
{"type":"event"} |
one event JSON | store and group |
log |
item_count, content_type: application/vnd.sentry.items.log+json |
{"items":[...]} batch |
store |
span |
item_count, content_type: application/vnd.sentry.items.span.v2+json |
{"items":[...]} batch |
accept and drop (tracing is out of scope) |
client_report |
{"type":"client_report"} |
{timestamp, discarded_events:[{reason, category, quantity}]} |
accept and drop (maybe count) |
transaction, session, sessions, attachment, profile, replay_*, check_in, ... |
accept and drop |
SDK 11 sends tracing as span (v2) items, not transaction events.
Top-level keys seen: event_id, timestamp, level, platform, environment, server_name, transaction, exception, message, fingerprint, tags, user, request, contexts, breadcrumbs, modules, sdk.
exception.values[]:{type, value, mechanism {type, handled}, stacktrace {frames[]}}.- Frames are ordered oldest first (the crashing frame is last).
- Frame fields seen (Node):
filename,module,function,lineno,colno,in_app,pre_context,context_line,post_context,vars. Browser frames have onlyfilename,function,lineno,colno,in_app.
- Error
causechain: several entries inexception.values, innermost cause first. The outer error is last, withmechanism.type: "chained"on inner ones. captureMessage: hasmessage(string) and also anexceptionvalue withouttype, with a synthetic stack trace.fingerprint: an array of strings, present only when set by the app. It overrides default grouping.mechanism:handled: falsefor crashes (auto.http.express,auto.browser.global_handlers.onerror/onunhandledrejection);genericwithhandled: trueforcaptureException.
contexts:trace {trace_id, span_id, parent_span_id},runtime,os,device,app,culture,cloud_resource, plus custom contexts (setContext).breadcrumbs: a plain array[{timestamp, category, level, message, data}]. It includes console output captured before the error.user:{id, email, username, ip_address}.request:{method, url, headers, cookies}.
Browser events have no server_name/modules. Their frames point at the page/bundle URL (minified in production, so they need source maps).
The SDK drops some events itself. For example, dedupeIntegration drops an identical error sent twice in a row, and the SDK reports this in a client_report (reason: event_processor). To test server grouping, send identical errors non-consecutively.
{
"timestamp": 1794328021.0768,
"level": "warn",
"body": "pino warn: slow query",
"trace_id": "bd916706b6ca4a468b9ab42bb321b9c9",
"severity_number": 13,
"attributes": {
"orderId": { "value": 1001, "type": "integer" },
"sentry.origin": { "value": "auto.log.pino", "type": "string" },
"sentry.environment": { "value": "development", "type": "string" },
"server.address": { "value": "test-host", "type": "string" }
}
}- Attributes are typed (
string,integer,double,boolean). sentry.origintells the source:auto.log.pino,auto.log.console, or absent forSentry.logger.- Logs are batched and flushed about every 5 s.
trace_idlinks a log to events with the samecontexts.trace.trace_id.- Bodies can contain ANSI color codes (pino/AdminForth), so strip or render them in the UI.
- Frameworks may log the same error that is also sent as an event. For example, AdminForth logs every 500 via pino. Link these by
trace_idrather than treating them as separate problems.
Production browser frames need source maps. sentry-cli / the bundler plugins:
- inject a
debugIdinto each bundle and its map; - upload them through the Sentry API with a bearer auth token. This is a chunked upload: get upload options, POST chunks, then call an "assemble" endpoint for an artifact bundle and poll its status.
Events then reference bundles via debug_meta.images[] with debug_id. The exact endpoints and formats still need to be checked against sentry-cli source before implementation. No debug_meta was observed in our samples, because the test page used inline scripts.