Skip to main content

Ingestion protocol

How any application, in any language, sends Collector its errors, signals, page views and logs. The SDKs implement it for you; this page is for writing your own client or understanding what they do. The Elixir package is the reference client.

The DSN​

An application is configured with one value, the project's DSN:

https://clt_…@app.clt.chrom.ar

The user part is the project's key; the rest (scheme, host, optional port and path) is where Collector lives. Events go to that URL plus /api/events, so https://clt_x@example.com/collector sends to https://example.com/collector/api/events. The key identifies the project, so neither the URL nor the body names one.

The key is public: it only sends events. The allowed domains and the limits keep it in line. Rotating it makes a new one; the old one keeps working for 24 hours.

Errors​

POST /api/events​

From a server:

POST https://app.clt.chrom.ar/api/events
Authorization: Bearer clt_…
Content-Type: application/json
Content-Encoding: gzip (optional)
curl https://app.clt.chrom.ar/api/events \
-H "Authorization: Bearer clt_…" \
-H "Content-Type: application/json" \
-d '{"v":1,"uuid":"'"$(uuidgen)"'","message":"Hello from curl"}'

From a web page, the key goes in the URL and the type is text/plain, so the browser sends the request straight away, with no CORS preflight:

POST https://app.clt.chrom.ar/api/events?key=clt_…
Content-Type: text/plain;charset=UTF-8

The body is the same JSON event, with "platform": "javascript". Send with fetch(url, {method: "POST", body, keepalive: true}), so events still go out while the page is closing. Every answer to a request with an Origin carries Access-Control-Allow-Origin for it and exposes Retry-After, errors included.

One event per request. The fields are in The event.

StatusMeansWhat the client does
202 {"id": "<uuid>"}Accepted (also for an event already received)Nothing
401 {"error": "invalid key"}Missing, unknown or expired key, or the project was deletedStops sending; logs it
403 {"error": "origin not allowed"}Sent from a domain the project blockedStops sending; logs it
413Body over 1 MB after decompressionDrops the event
422 {"errors": {...}}The event doesn't follow this formatDrops the event; logs the errors
425Sent as TLS early dataRetries after the handshake (browsers do it on their own)
429 {"error": "rate limited"} + Retry-AfterOver the project's limitDoesn't resend this event; pauses all sending for Retry-After seconds
5xx or no answerCollector is having troubleResends later with the same uuid, backing off

A 429 doesn't mean the event was lost: it was counted against its issue, only its details weren't kept. That's why it mustn't be resent. Resending with the same uuid is always safe: Collector recognizes it and counts it once.

Signals​

POST /api/heartbeats​

An SDK can say it's alive without an error: one heartbeat when it starts and one every hour from servers; from browsers, at most one a day per release and environment. Same transport as events (from a page, ?key= and text/plain; navigator.sendBeacon is accepted too).

{
"v": 1,
"sdk": {"name": "collector", "version": "0.5.4"},
"environment": "production",
"release": "1.4.2",
"server": "web-7f9c",
"runtime": {"name": "elixir", "version": "1.19.1", "otp": "28"}
}
FieldRequiredNotes
vyes1
sdk.name, sdk.versionyesStrings. The JS SDK sends @chrom-ar/collector.
environmentnoNo default, as for events.
releaseno
servernoHost name. Servers only.
runtimenoA flat object of strings.

Unknown fields are ignored; strings over 200 characters are cut; a body over 16 KB is refused.

StatusMeansWhat the client does
202 {}RecordedNothing; ignores unknown fields
401 / 403As for eventsStops sending heartbeats, silently
404A Collector without heartbeatsIgnores it until the next one
413 / 422Bad heartbeatDrops it, silently
429 + Retry-AfterOver its own limit, separate from the events'Drops it; doesn't pause events. The next scheduled heartbeat is the retry
5xx or no answerCollector is having troubleServers retry with the events' backoff, keeping at most one pending; browsers wait for the next one

Page views​

POST /api/pageviews​

Browsers only, like browser events. Measuring is opt-in and sampled: the decision is made once per tab, and a measured tab sends all its page views, in batches, when it's hidden or closed.

POST https://app.clt.chrom.ar/api/pageviews?key=clt_…
Content-Type: text/plain;charset=UTF-8
{
"v": 1,
"sdk": {"name": "@chrom-ar/collector", "version": "0.4.0"},
"environment": "production",
"release": "6c5717a",
"session": "b3f1c9…",
"sample_rate": 0.1,
"pageviews": [{
"id": "e1…", "at": "2026-11-09T14:02:11.120Z",
"path": "/checkout", "route": "/checkout", "navigation": "hard",
"vitals": {"lcp": 3820, "inp": 310, "cls": 0.03, "ttfb": 910, "fcp": 1400},
"requests": [{"method": "POST", "url": "https://shop.example.com/api/cart/81/price", "status": 200, "start": 2890, "duration": 1910}],
"waterfall": [{"name": "https://shop.example.com/assets/app-3f9a.js", "type": "script", "start": 880, "duration": 1900, "size": 182000}]
}]
}
FieldRequiredNotes
v, sdkyesAs for heartbeats
environment, releasenoAs for events
sessionyesRandom, per tab, in sessionStorage. Sent with the tab's events too, so an error links to its visit
sample_rateyesThe tab's sample rate, 0 < r ≤ 1. Counts are estimated from it
pageviews[].idyesRandom. A page view sent again with the same id replaces the earlier one
pageviews[].atyesISO 8601, when it started
pageviews[].pathyesThe path only; a query or fragment is stripped anyway
pageviews[].routenoThe route pattern (/products/:id). Without it, Collector groups by replacing id-like segments with :id
pageviews[].navigationyeshard (a full load) or soft (an in-app navigation)
pageviews[].vitalsnoIn ms except cls. lcp, ttfb and fcp from full loads; nav from in-app ones; inp and cls from both
pageviews[].requestsnofetch/XHR calls: method, url, status (0 for a network failure), start and duration. Up to 50 are kept
pageviews[].waterfallnoResource timings (name, type, start, duration, size), only for page views with poor loading, responsiveness or navigation. Up to 30 are kept

A page view missing a required field, or with a value of the wrong type, is dropped on its own; the rest of the batch is stored. Collector derives the country, the browser, its version and the device type, and keeps only those, never the IP or the full user agent. A body over 64 KB after decompression is refused; it may be gzipped (Content-Encoding: gzip, which needs a CORS preflight). Page views older than 90 days, or more than an hour in the future, are dropped.

StatusMeansWhat the client does
202 {}RecordedNothing
401 / 403As for eventsStops measuring on this page
404A Collector without speed measuringStops measuring on this page
400 / 413 / 422Bad batch (broken gzip, too large, no pageviews list)Drops it
429 + Retry-AfterOver its own limit; the dropped page views are counted and shownDrops the batch; sends nothing more before Retry-After
5xx or no answerCollector is having troubleDrops the batch, no retry

Logs​

POST /api/logs​

From servers only, never from web pages, with a server key instead of the DSN: the DSN's key is public, and with it anyone could fake sign-ins or use up the budget during an attack. Setting COLLECTOR_SERVER_KEY is what turns logs on in the SDKs.

POST https://app.clt.chrom.ar/api/logs
Authorization: Bearer clts_…
Content-Type: application/json
Content-Encoding: gzip
{
"v": 1,
"sdk": {"name": "collector", "version": "0.5.4"},
"environment": "production", "release": "6c5717a", "server": "web-1",
"dropped": {"log": 0, "request": 0, "sign_in": 0},
"records": [
{"type": "log", "id": "5d0c…", "at": "2026-11-11T14:02:11.120Z",
"level": "warning", "message": "Payment declined", "logger": "Shop.Checkout",
"metadata": {"order_id": "81"}, "request_id": "F3x…", "user": "u_42"},
{"type": "request", "id": "8e1a…", "at": "2026-11-11T14:02:11.090Z",
"method": "POST", "path": "/checkout/81", "route": "/checkout/:id",
"status": 402, "duration_ms": 184, "ip": "203.0.113.9",
"user_agent": "Mozilla/5.0 …", "user": "u_42", "request_id": "F3x…", "bytes": 1832},
{"type": "sign_in", "id": "b7c2…", "at": "2026-11-11T14:01:58.002Z",
"outcome": "failed", "account": "ana@example.com", "method": "password",
"reason": "bad_password", "ip": "203.0.113.9", "request_id": "Qa1…"}
]
}
FieldRequiredNotes
v, sdkyesAs for heartbeats
environment, release, servernoAs for events
droppednoRecords the SDK dropped since its last accepted batch, per type. Counted and shown
records[].typeyeslog, request or sign_in
records[].idyesA UUID the SDK makes. A record sent again with the same id is stored once
records[].atyesISO 8601 with milliseconds. Records more than 7 days back or an hour ahead are rejected
records[].request_id, records[].usernoThe request it belongs to, and the app's user id (never an email)
log: levelyesdebug, info, notice, warning, error, critical, alert or emergency
log: messageyesUp to 8 KB; longer is cut
log: logger, metadatanometadata: string keys, up to 50 keys and 16 KB
request: method, path, statusyesThe path without query string
request: route, duration_ms, ip, user_agent, bytesnoroute is the router's pattern
sign_in: outcome, accountyessucceeded or failed; what was typed to sign in, trimmed and lowercased
sign_in: user, method, reason, ipnomethod: password, magic_link, passkey, token or other. reason: unknown_account, bad_password, locked, expired_token or other

How each source's levels map:

Sourcedebuginfonoticewarningerrorcriticalalert, emergency
Elixir / Erlangdebuginfonoticewarningerrorcriticalalert, emergency
pinotrace, debuginfowarnerrorfatal
winstonsilly, debug, verbosehttp, infowarnerror
consoledebug, tracelog, infowarnerror

At most 1,000 records and 5 MB (after decompression) per batch.

StatusMeansWhat the SDK does
202 {"accepted", "rejected", "over_budget", "rejected_sample"}Stored, except the rejected (malformed, or at out of range; up to 5 examples with why) and the types in over_budget. With any over_budget, the answer carries Retry-AfterForgets the stored and rejected records. Keeps the listed types' records and sends none of those types before Retry-After; the others keep flowing
400 / 413Broken gzip or JSON, no records list, over 1,000 records or 5 MBDrops the batch; on 413, splits it
401Not a working server key (a DSN key is refused too)Stops sending logs for the life of the process; says so once. Errors are unaffected
403The request has an Origin: a server key never belongs in a pageAs for 401
404A Collector without logsStops sending logs, silently
503, other 5xx, or no answerNothing was storedKeeps the batch; retries with backoff (1 s up to 60 s)

OpenTelemetry​

POST /otlp/v1/logs​

For applications already on OpenTelemetry: OTLP/HTTP, logs only. The body is an ExportLogsServiceRequest in protobuf or OTLP's JSON, with the same server key and the same log-line budget as /api/logs. How each record maps is in OpenTelemetry.

POST https://app.clt.chrom.ar/otlp/v1/logs
Authorization: Bearer clts_…
Content-Type: application/x-protobuf | application/json
Content-Encoding: gzip (optional)

Up to 10,000 records and 10 MB once inflated.

StatusMeans
200Stored; a partialSuccess counts what was rejected (more than 7 days back or an hour ahead) and why. The answer is in the request's encoding
429 + Retry-AfterOver the project's log budget; nothing stored; exporters retry
503 + Retry-AfterCollector can't take them now; exporters retry
400 / 413 / 415Not a valid request, too large, or not protobuf or JSON; not retried
401 / 403Not a working server key; or from a web page
404A Collector without logs

Source maps​

POST /api/sourcemaps​

So minified frames show the original code. The CLI does it for you. It needs an upload token (cltu_…); the DSN's key doesn't work. It also accepts an access token.

POST <DSN without the key>/api/sourcemaps
Authorization: Bearer cltu_…
Content-Type: multipart/form-data
Accept: application/json
Part
releaseText, required. Exactly the release the SDK sends with this build's events
manifestText, JSON: [{"path": "/assets/index-a1b2c3d4.js", "map": "index-a1b2c3d4.js.map"}]. path is the URL path the bundle is served at; map is the name of the part holding its map
one part per mapNamed as in the manifest, without slashes. Content-Type: application/gzip when gzipped (recommended), application/json or application/octet-stream when not

Only maps are uploaded, not the minified files. The code around each line comes from the map's sourcesContent, so keep it in. Index maps (with sections) aren't accepted; the CLI flattens them. Uploading the same release and path again replaces that map.

AnswerMeans
201 {"release": "…", "files": [{"path": "…"}]}Stored
400 {"error": "…"}A bad manifest, a missing part, a part that isn't a source map, or one whose Content-Type and bytes disagree on gzip. The message names the part
401 {"error": "invalid token"}Missing, unknown or revoked token. Nothing was read
413 {"error": "…"}Over 100 maps, a map over 20 MB uncompressed, or a request over 100 MB

How maps are applied to events is in Source maps.