Saltar al contenido principal

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.

EstadoSignificaQué 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
413Cuerpo de más de 1 MB descomprimidoDescarta el evento
422 {"errors": {...}}El evento no sigue este formatoDescarta el evento; registra los errores
425Mandado como TLS early dataReintenta después del handshake (los navegadores lo hacen solos)
429 {"error": "rate limited"} + Retry-AfterPasó el límite del proyectoNo reenvía este evento; pausa todo envío por Retry-After segundos
5xx o sin respuestaCollector tiene problemasReenví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"}
}
CampoObligatorioNotas
vsí1
sdk.name, sdk.versionsíTextos. El SDK de JS manda @chrom-ar/collector.
environmentnoSin valor por defecto, como en los eventos.
releaseno
servernoNombre del host. Solo servidores.
runtimenoUn 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.

EstadoSignificaQué hace el cliente
202 {}RegistradoNada; ignora campos desconocidos
401 / 403Como en los eventosDeja de mandar latidos, en silencio
404Un Collector sin latidosLo ignora hasta el próximo
413 / 422Latido inválidoLo descarta, en silencio
429 + Retry-AfterPasó su propio límite, separado del de los eventosLo descarta; no pausa los eventos. El próximo latido programado es el reintento
5xx o sin respuestaCollector tiene problemasLos 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}]
}]
}
CampoObligatorioNotas
v, sdksíComo en los latidos
environment, releasenoComo en los eventos
sessionsí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_ratesíEl muestreo de la pestaña, 0 < r ≤ 1. Los conteos se estiman a partir de él
pageviews[].idsíAl azar. Una visita mandada de nuevo con el mismo id reemplaza a la anterior
pageviews[].atsíISO 8601, cuándo empezó
pageviews[].pathsíSolo la ruta; query y fragmento se quitan igual
pageviews[].routenoEl patrón de ruta (/products/:id). Sin él, Collector agrupa reemplazando los segmentos que parecen identificadores por :id
pageviews[].navigationsíhard (carga completa) o soft (navegación dentro de la aplicación)
pageviews[].vitalsnoEn ms salvo cls. lcp, ttfb y fcp de las cargas completas; nav de las navegaciones internas; inp y cls de ambas
pageviews[].requestsnoLlamadas fetch/XHR: method, url, status (0 para un fallo de red), start y duration. Se guardan hasta 50
pageviews[].waterfallnoTiempos 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.

EstadoSignificaQué hace el cliente
202 {}RegistradoNada
401 / 403Como en los eventosDeja de medir en esta página
404Un Collector sin medición de velocidadDeja de medir en esta página
400 / 413 / 422Lote inválido (gzip roto, muy grande, sin lista pageviews)Lo descarta
429 + Retry-AfterPasó su propio límite; las visitas descartadas se cuentan y se muestranDescarta el lote; no manda más antes de Retry-After
5xx o sin respuestaCollector tiene problemasDescarta 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…"}
]
}
CampoObligatorioNotas
v, sdksíComo en los latidos
environment, release, servernoComo en los eventos
droppednoRegistros que el SDK descartó desde su último lote aceptado, por tipo. Se cuentan y se muestran
records[].typesílog, request o sign_in
records[].idsíUn UUID del SDK. Un registro mandado de nuevo con el mismo id se guarda una vez
records[].atsíISO 8601 con milisegundos. Los de más de 7 días atrás o una hora adelante se rechazan
records[].request_id, records[].usernoLa solicitud a la que pertenece, y el identificador del usuario de la aplicación (nunca un correo)
log: levelsídebug, info, notice, warning, error, critical, alert o emergency
log: messagesíHasta 8 KB; más se corta
log: logger, metadatanometadata: claves de texto, hasta 50 claves y 16 KB
request: method, path, statussíLa ruta sin query
request: route, duration_ms, ip, user_agent, bytesnoroute es el patrón del router
sign_in: outcome, accountsísucceeded o failed; lo que se escribió para entrar, recortado y en minúsculas
sign_in: user, method, reason, ipnomethod: 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:

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

Hasta 1.000 registros y 5 MB (descomprimido) por lote.

EstadoSignificaQué 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-AfterOlvida 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 / 413Gzip o JSON roto, sin lista records, más de 1.000 registros o 5 MBDescarta el lote; con 413, lo parte
401No 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
403El pedido trae Origin: una clave de servidor nunca va en una páginaComo 401
404Un Collector sin registrosDeja de mandar registros, en silencio
503, otro 5xx o sin respuestaNada 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.

EstadoSignifica
200Guardado; 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-AfterPasó el presupuesto de registros del proyecto; nada se guardó; los exportadores reintentan
503 + Retry-AfterCollector no puede recibirlos ahora; los exportadores reintentan
400 / 413 / 415No es un pedido válido, es muy grande, o no es protobuf ni JSON; no se reintenta
401 / 403No es una clave de servidor válida; o viene de una página web
404Un 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
releaseTexto, obligatorio. Exactamente el release que manda el SDK con los eventos de este build
manifestTexto, 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 mapaCon 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.

RespuestaSignifica
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.