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.
| Status | Means | What 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 deleted | Stops sending; logs it |
403 {"error": "origin not allowed"} | Sent from a domain the project blocked | Stops sending; logs it |
413 | Body over 1 MB after decompression | Drops the event |
422 {"errors": {...}} | The event doesn't follow this format | Drops the event; logs the errors |
425 | Sent as TLS early data | Retries after the handshake (browsers do it on their own) |
429 {"error": "rate limited"} + Retry-After | Over the project's limit | Doesn't resend this event; pauses all sending for Retry-After seconds |
5xx or no answer | Collector is having trouble | Resends 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"}
}
| Field | Required | Notes |
|---|---|---|
v | yes | 1 |
sdk.name, sdk.version | yes | Strings. The JS SDK sends @chrom-ar/collector. |
environment | no | No default, as for events. |
release | no | |
server | no | Host name. Servers only. |
runtime | no | A flat object of strings. |
Unknown fields are ignored; strings over 200 characters are cut; a body over 16 KB is refused.
| Status | Means | What the client does |
|---|---|---|
202 {} | Recorded | Nothing; ignores unknown fields |
401 / 403 | As for events | Stops sending heartbeats, silently |
404 | A Collector without heartbeats | Ignores it until the next one |
413 / 422 | Bad heartbeat | Drops it, silently |
429 + Retry-After | Over its own limit, separate from the events' | Drops it; doesn't pause events. The next scheduled heartbeat is the retry |
5xx or no answer | Collector is having trouble | Servers 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}]
}]
}
| Field | Required | Notes |
|---|---|---|
v, sdk | yes | As for heartbeats |
environment, release | no | As for events |
session | yes | Random, per tab, in sessionStorage. Sent with the tab's events too, so an error links to its visit |
sample_rate | yes | The tab's sample rate, 0 < r ≤ 1. Counts are estimated from it |
pageviews[].id | yes | Random. A page view sent again with the same id replaces the earlier one |
pageviews[].at | yes | ISO 8601, when it started |
pageviews[].path | yes | The path only; a query or fragment is stripped anyway |
pageviews[].route | no | The route pattern (/products/:id). Without it, Collector groups by replacing id-like segments with :id |
pageviews[].navigation | yes | hard (a full load) or soft (an in-app navigation) |
pageviews[].vitals | no | In ms except cls. lcp, ttfb and fcp from full loads; nav from in-app ones; inp and cls from both |
pageviews[].requests | no | fetch/XHR calls: method, url, status (0 for a network failure), start and duration. Up to 50 are kept |
pageviews[].waterfall | no | Resource 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.
| Status | Means | What the client does |
|---|---|---|
202 {} | Recorded | Nothing |
401 / 403 | As for events | Stops measuring on this page |
404 | A Collector without speed measuring | Stops measuring on this page |
400 / 413 / 422 | Bad batch (broken gzip, too large, no pageviews list) | Drops it |
429 + Retry-After | Over its own limit; the dropped page views are counted and shown | Drops the batch; sends nothing more before Retry-After |
5xx or no answer | Collector is having trouble | Drops 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…"}
]
}
| Field | Required | Notes |
|---|---|---|
v, sdk | yes | As for heartbeats |
environment, release, server | no | As for events |
dropped | no | Records the SDK dropped since its last accepted batch, per type. Counted and shown |
records[].type | yes | log, request or sign_in |
records[].id | yes | A UUID the SDK makes. A record sent again with the same id is stored once |
records[].at | yes | ISO 8601 with milliseconds. Records more than 7 days back or an hour ahead are rejected |
records[].request_id, records[].user | no | The request it belongs to, and the app's user id (never an email) |
log: level | yes | debug, info, notice, warning, error, critical, alert or emergency |
log: message | yes | Up to 8 KB; longer is cut |
log: logger, metadata | no | metadata: string keys, up to 50 keys and 16 KB |
request: method, path, status | yes | The path without query string |
request: route, duration_ms, ip, user_agent, bytes | no | route is the router's pattern |
sign_in: outcome, account | yes | succeeded or failed; what was typed to sign in, trimmed and lowercased |
sign_in: user, method, reason, ip | no | method: password, magic_link, passkey, token or other. reason: unknown_account, bad_password, locked, expired_token or other |
How each source's levels map:
| Source | debug | info | notice | warning | error | critical | alert, emergency |
|---|---|---|---|---|---|---|---|
| Elixir / Erlang | debug | info | notice | warning | error | critical | alert, emergency |
| pino | trace, debug | info | warn | error | fatal | ||
| winston | silly, debug, verbose | http, info | warn | error | |||
console | debug, trace | log, info | warn | error |
At most 1,000 records and 5 MB (after decompression) per batch.
| Status | Means | What 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-After | Forgets the stored and rejected records. Keeps the listed types' records and sends none of those types before Retry-After; the others keep flowing |
400 / 413 | Broken gzip or JSON, no records list, over 1,000 records or 5 MB | Drops the batch; on 413, splits it |
401 | Not 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 |
403 | The request has an Origin: a server key never belongs in a page | As for 401 |
404 | A Collector without logs | Stops sending logs, silently |
503, other 5xx, or no answer | Nothing was stored | Keeps 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.
| Status | Means |
|---|---|
200 | Stored; 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-After | Over the project's log budget; nothing stored; exporters retry |
503 + Retry-After | Collector can't take them now; exporters retry |
400 / 413 / 415 | Not a valid request, too large, or not protobuf or JSON; not retried |
401 / 403 | Not a working server key; or from a web page |
404 | A 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 | |
|---|---|
release | Text, required. Exactly the release the SDK sends with this build's events |
manifest | Text, 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 map | Named 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.
| Answer | Means |
|---|---|
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.