Protocolo de envío
Cómo cualquier aplicación, en cualquier lenguaje, le manda a Collector sus errores, señales, visitas a páginas y registros. Los SDK lo implementan por ti; esta página es para escribir un cliente propio o entender qué hacen. El paquete de Elixir es el cliente de referencia.
El DSN
Una aplicación se configura con un solo valor, el DSN del proyecto:
https://clt_…@app.clt.chrom.ar
La parte de usuario es la clave del proyecto; el resto (esquema, host, puerto y ruta opcionales) es dónde está Collector. Los eventos van a esa URL más /api/events, así que https://clt_x@ejemplo.com/collector manda a https://ejemplo.com/collector/api/events. La clave identifica al proyecto, así que ni la URL ni el cuerpo lo nombran.
La clave es pública: solo manda eventos. La protegen los dominios permitidos y los límites. Rotarla crea una nueva; la anterior sigue funcionando 24 horas.
Errores
POST /api/events
Desde un servidor:
POST https://app.clt.chrom.ar/api/events
Authorization: Bearer clt_…
Content-Type: application/json
Content-Encoding: gzip (opcional)
curl https://app.clt.chrom.ar/api/events \
-H "Authorization: Bearer clt_…" \
-H "Content-Type: application/json" \
-d '{"v":1,"uuid":"'"$(uuidgen)"'","message":"Hola desde curl"}'
Desde una página web, la clave va en la URL y el tipo es text/plain, así el navegador manda el pedido enseguida, sin preflight de CORS:
POST https://app.clt.chrom.ar/api/events?key=clt_…
Content-Type: text/plain;charset=UTF-8
El cuerpo es el mismo evento JSON, con "platform": "javascript". Manda con fetch(url, {method: "POST", body, keepalive: true}), para que los eventos salgan aunque la página se esté cerrando. Toda respuesta a un pedido con Origin lleva Access-Control-Allow-Origin para ese origen y expone Retry-After, errores incluidos.
Un evento por pedido. Los campos están en El evento.
| Estado | Significa | Qué hace el cliente |
|---|---|---|
202 {"id": "<uuid>"} | Aceptado (también para un evento ya recibido) | Nada |
401 {"error": "invalid key"} | Clave ausente, desconocida o vencida, o el proyecto se eliminó | Deja de mandar; lo registra |
403 {"error": "origin not allowed"} | Mandado desde un dominio que el proyecto bloqueó | Deja de mandar; lo registra |
413 | Cuerpo de más de 1 MB descomprimido | Descarta el evento |
422 {"errors": {...}} | El evento no sigue este formato | Descarta el evento; registra los errores |
425 | Mandado como TLS early data | Reintenta después del handshake (los navegadores lo hacen solos) |
429 {"error": "rate limited"} + Retry-After | Pasó el límite del proyecto | No reenvía este evento; pausa todo envío por Retry-After segundos |
5xx o sin respuesta | Collector tiene problemas | Reenvía después con el mismo uuid, espaciando los intentos |
Un 429 no significa que el evento se perdió: se contó en su problema, solo no se guardaron sus detalles. Por eso no hay que reenviarlo. Reenviar con el mismo uuid siempre es seguro: Collector lo reconoce y lo cuenta una vez.
Señales
POST /api/heartbeats
Un SDK puede decir que está vivo sin un error: un latido al arrancar y uno cada hora desde servidores; desde navegadores, a lo sumo uno por día por versión y entorno. Mismo transporte que los eventos (desde una página, ?key= y text/plain; también se acepta navigator.sendBeacon).
{
"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"}
}
| Campo | Obligatorio | Notas |
|---|---|---|
v | sí | 1 |
sdk.name, sdk.version | sí | Textos. El SDK de JS manda @chrom-ar/collector. |
environment | no | Sin valor por defecto, como en los eventos. |
release | no | |
server | no | Nombre del host. Solo servidores. |
runtime | no | Un objeto plano de textos. |
Los campos desconocidos se ignoran; los textos de más de 200 caracteres se cortan; un cuerpo de más de 16 KB se rechaza.
| Estado | Significa | Qué hace el cliente |
|---|---|---|
202 {} | Registrado | Nada; ignora campos desconocidos |
401 / 403 | Como en los eventos | Deja de mandar latidos, en silencio |
404 | Un Collector sin latidos | Lo ignora hasta el próximo |
413 / 422 | Latido inválido | Lo descarta, en silencio |
429 + Retry-After | Pasó su propio límite, separado del de los eventos | Lo descarta; no pausa los eventos. El próximo latido programado es el reintento |
5xx o sin respuesta | Collector tiene problemas | Los servidores reintentan con la espera de los eventos, con a lo sumo uno pendiente; los navegadores esperan al próximo |
Visitas a páginas
POST /api/pageviews
Solo navegadores, como los eventos de navegador. La medición es opcional y muestreada: la decisión se toma una vez por pestaña, y una pestaña medida manda todas sus visitas a páginas, en lotes, cuando se oculta o se cierra.
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://tienda.ejemplo.com/api/cart/81/price", "status": 200, "start": 2890, "duration": 1910}],
"waterfall": [{"name": "https://tienda.ejemplo.com/assets/app-3f9a.js", "type": "script", "start": 880, "duration": 1900, "size": 182000}]
}]
}
| Campo | Obligatorio | Notas |
|---|---|---|
v, sdk | sí | Como en los latidos |
environment, release | no | Como en los eventos |
session | sí | Al azar, por pestaña, en sessionStorage. Va también con los eventos de la pestaña, así un error enlaza a su visita |
sample_rate | sí | El muestreo de la pestaña, 0 < r ≤ 1. Los conteos se estiman a partir de él |
pageviews[].id | sí | Al azar. Una visita mandada de nuevo con el mismo id reemplaza a la anterior |
pageviews[].at | sí | ISO 8601, cuándo empezó |
pageviews[].path | sí | Solo la ruta; query y fragmento se quitan igual |
pageviews[].route | no | El patrón de ruta (/products/:id). Sin él, Collector agrupa reemplazando los segmentos que parecen identificadores por :id |
pageviews[].navigation | sí | hard (carga completa) o soft (navegación dentro de la aplicación) |
pageviews[].vitals | no | En ms salvo cls. lcp, ttfb y fcp de las cargas completas; nav de las navegaciones internas; inp y cls de ambas |
pageviews[].requests | no | Llamadas fetch/XHR: method, url, status (0 para un fallo de red), start y duration. Se guardan hasta 50 |
pageviews[].waterfall | no | Tiempos de recursos (name, type, start, duration, size), solo para visitas con mala carga, respuesta o navegación. Se guardan hasta 30 |
Una visita a la que le falta un campo obligatorio, o con un valor del tipo equivocado, se descarta sola; el resto del lote se guarda. Collector deduce el país, el navegador, su versión y el tipo de dispositivo, y guarda solo eso, nunca la IP ni el user agent completo. Un cuerpo de más de 64 KB descomprimido se rechaza; puede ir con gzip (Content-Encoding: gzip, que necesita preflight de CORS). Las visitas de hace más de 90 días, o de más de una hora en el futuro, se descartan.
| Estado | Significa | Qué hace el cliente |
|---|---|---|
202 {} | Registrado | Nada |
401 / 403 | Como en los eventos | Deja de medir en esta página |
404 | Un Collector sin medición de velocidad | Deja de medir en esta página |
400 / 413 / 422 | Lote inválido (gzip roto, muy grande, sin lista pageviews) | Lo descarta |
429 + Retry-After | Pasó su propio límite; las visitas descartadas se cuentan y se muestran | Descarta el lote; no manda más antes de Retry-After |
5xx o sin respuesta | Collector tiene problemas | Descarta el lote, sin reintentar |
Registros
POST /api/logs
Solo desde servidores, nunca desde páginas web, con una clave de servidor en lugar del DSN: la clave del DSN es pública, y con ella cualquiera podría falsear inicios de sesión o gastar el presupuesto durante un ataque. Definir COLLECTOR_SERVER_KEY es lo que enciende los registros en los SDK.
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@ejemplo.com", "method": "password",
"reason": "bad_password", "ip": "203.0.113.9", "request_id": "Qa1…"}
]
}
| Campo | Obligatorio | Notas |
|---|---|---|
v, sdk | sí | Como en los latidos |
environment, release, server | no | Como en los eventos |
dropped | no | Registros que el SDK descartó desde su último lote aceptado, por tipo. Se cuentan y se muestran |
records[].type | sí | log, request o sign_in |
records[].id | sí | Un UUID del SDK. Un registro mandado de nuevo con el mismo id se guarda una vez |
records[].at | sí | ISO 8601 con milisegundos. Los de más de 7 días atrás o una hora adelante se rechazan |
records[].request_id, records[].user | no | La solicitud a la que pertenece, y el identificador del usuario de la aplicación (nunca un correo) |
log: level | sí | debug, info, notice, warning, error, critical, alert o emergency |
log: message | sí | Hasta 8 KB; más se corta |
log: logger, metadata | no | metadata: claves de texto, hasta 50 claves y 16 KB |
request: method, path, status | sí | La ruta sin query |
request: route, duration_ms, ip, user_agent, bytes | no | route es el patrón del router |
sign_in: outcome, account | sí | succeeded o failed; lo que se escribió para entrar, recortado y en minúsculas |
sign_in: user, method, reason, ip | no | method: password, magic_link, passkey, token u other. reason: unknown_account, bad_password, locked, expired_token u other |
Cómo mapear los niveles de cada fuente:
| Fuente | 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 |
Hasta 1.000 registros y 5 MB (descomprimido) por lote.
| Estado | Significa | Qué hace el SDK |
|---|---|---|
202 {"accepted", "rejected", "over_budget", "rejected_sample"} | Guardado, salvo los rejected (mal formados, o at fuera de rango; hasta 5 ejemplos con el motivo) y los tipos de over_budget. Con algún over_budget, la respuesta trae Retry-After | Olvida lo guardado y lo rechazado. Guarda los registros de los tipos listados y no manda de esos tipos antes de Retry-After; los demás siguen |
400 / 413 | Gzip o JSON roto, sin lista records, más de 1.000 registros o 5 MB | Descarta el lote; con 413, lo parte |
401 | No es una clave de servidor válida (una clave de DSN también se rechaza) | Deja de mandar registros mientras viva el proceso; lo dice una vez. Los errores no se ven afectados |
403 | El pedido trae Origin: una clave de servidor nunca va en una página | Como 401 |
404 | Un Collector sin registros | Deja de mandar registros, en silencio |
503, otro 5xx o sin respuesta | Nada se guardó | Guarda el lote; reintenta espaciando (de 1 s a 60 s) |
OpenTelemetry
POST /otlp/v1/logs
Para aplicaciones que ya usan OpenTelemetry: OTLP/HTTP, solo logs. El cuerpo es un ExportLogsServiceRequest en protobuf o en el JSON de OTLP, con la misma clave de servidor y el mismo presupuesto de líneas de log que /api/logs. Cómo se traduce cada registro está en OpenTelemetry.
POST https://app.clt.chrom.ar/otlp/v1/logs
Authorization: Bearer clts_…
Content-Type: application/x-protobuf | application/json
Content-Encoding: gzip (opcional)
Hasta 10.000 registros y 10 MB descomprimidos.
| Estado | Significa |
|---|---|
200 | Guardado; un partialSuccess cuenta lo rechazado (más de 7 días atrás o una hora adelante) y por qué. La respuesta va en la codificación del pedido |
429 + Retry-After | Pasó el presupuesto de registros del proyecto; nada se guardó; los exportadores reintentan |
503 + Retry-After | Collector no puede recibirlos ahora; los exportadores reintentan |
400 / 413 / 415 | No es un pedido válido, es muy grande, o no es protobuf ni JSON; no se reintenta |
401 / 403 | No es una clave de servidor válida; o viene de una página web |
404 | Un Collector sin registros |
Mapas de código fuente
POST /api/sourcemaps
Para que los marcos minificados muestren el código original. La CLI lo hace por ti. Necesita una credencial de subida (cltu_…); la clave del DSN no sirve. También acepta una credencial de acceso.
POST <DSN sin la clave>/api/sourcemaps
Authorization: Bearer cltu_…
Content-Type: multipart/form-data
Accept: application/json
| Parte | |
|---|---|
release | Texto, obligatorio. Exactamente el release que manda el SDK con los eventos de este build |
manifest | Texto, JSON: [{"path": "/assets/index-a1b2c3d4.js", "map": "index-a1b2c3d4.js.map"}]. path es la ruta URL en la que se sirve el bundle; map, el nombre de la parte que lleva su mapa |
| una parte por mapa | Con el nombre del manifiesto, sin barras. Content-Type: application/gzip si va comprimido (recomendado), application/json o application/octet-stream si no |
Solo se suben los mapas, no los archivos minificados. El código alrededor de cada línea sale del sourcesContent del mapa, así que consérvalo. Los mapas índice (con sections) no se aceptan; la CLI los aplana. Subir de nuevo la misma versión y ruta reemplaza ese mapa.
| Respuesta | Significa |
|---|---|
201 {"release": "…", "files": [{"path": "…"}]} | Guardado |
400 {"error": "…"} | Un manifiesto inválido, una parte que falta o que no es un mapa, o una cuyo Content-Type y contenido no coinciden en gzip. El mensaje nombra la parte |
401 {"error": "invalid token"} | Credencial ausente, desconocida o revocada. No se leyó nada |
413 {"error": "…"} | Más de 100 mapas, un mapa de más de 20 MB descomprimido, o un pedido de más de 100 MB |
Cómo se aplican los mapas a los eventos está en Mapas de código fuente.