Ingesta
Cómo recibe el motor eventos, fragmentos de grabación, capturas de página, source maps y trazas OTLP, qué revisa, cómo convierte lotes en objetos, cómo maneja duplicados y por qué no consulta la base de datos para hacerlo.
En esta página
- La superficie HTTP
- Las puertas
- (1) La llave
- (2) El origen
- (3) El límite de velocidad
- (4) Decodificar
- (5) y (6) La forma, y luego cada evento
- (7) La cuota
- El manejador
- De lotes a objetos
- Lo mismo en AWS
- Duplicados e idempotencia
- Source maps y fragmentos de grabación
- Entrada de OTLP
- Por qué la ingesta no consulta Postgres
- Logs
- Qué cambió frente al sistema del que sale
- Sigue
La ingesta es la puerta del motor. Recibe lo que envían los SDK, lo revisa y lo escribe en el Bucket. No analiza nada. Eso la mantiene rápida, barata y difícil de romper.
Esta página es el diseño detrás de la API de ingesta. La página de la API dice qué enviar; esta dice qué pasa con eso.
La superficie HTTP
| Endpoint | Cuerpo | Límite | Va a |
|---|---|---|---|
POST /v1/ingest/events | Un lote: hasta 200 eventos y un batch_id | 2 MiB después de descomprimir | El búfer, luego un segmento bajo events/ |
POST /v1/ingest/replay | Un fragmento de grabación | 4.000.000 bytes después de descomprimir; 720 fragmentos por sesión | Un objeto bajo replays/, escrito antes de responder |
POST /v1/ingest/snapshot | Una captura de página | 4.000.000 bytes después de descomprimir | Un objeto bajo snapshots/ |
GET /v1/ingest/config | — | — | Se responde desde la caché: reglas de grabación y slow_down |
POST /v1/otlp/v1/traces | Un ExportTraceServiceRequest de OTLP, en protobuf o JSON | 4.000.000 bytes; 2.000 spans | Se convierte en eventos y va al mismo búfer |
Los cinco reciben una llave de ingesta, spk_…, en Authorization: Bearer o, para navigator.sendBeacon, en el parámetro key de la URL. Un token de API enviado aquí se rechaza con 403 wrong_credential, así un secreto que termine por error en un navegador no funciona calladamente.
Los source maps no pasan por la ingesta. Tu CI le pide a la API enlaces de subida con un token de API, y sube cada archivo directo al Bucket. Mira la sección de source maps más abajo.
Las puertas
Un lote pasa siete puertas, en este orden. Cada una que falla responde de inmediato con un código de error, y las revisiones más baratas van primero.
(1) La llave
La llave se busca en una caché en memoria, no en Postgres. Una llave desconocida o revocada recibe 401 unauthorized.
Fíjate en las tres edades de la búsqueda de abajo. Un acierto se usa tal cual durante 60 segundos. Un fallo le pregunta a Postgres una vez y recuerda «esa llave no existe» por 60 segundos, así una llave equivocada no sirve para martillar la base de datos. Y cuando Postgres no responde, una entrada de hasta una hora sigue sirviendo.
impl ProjectCache {
/// El proyecto detrás de una llave de ingesta. Una lectura de mapa hash en el camino caliente.
pub async fn lookup(&self, key: &IngestKey) -> Result<Arc<ProjectEntry>, IngestError> {
let now = self.clock.now();
if let Some(slot) = self.entries.get(key) {
match slot.value() {
Slot::Known(entry) if entry.loaded_at + FRESH > now => return Ok(entry.clone()),
Slot::Unknown { since } if *since + NEGATIVE > now => return Err(IngestError::Unauthorized),
_ => {} // vencido: se refresca abajo
}
}
match self.db.project_for_key(key).await {
Ok(Some(entry)) => {
let entry = Arc::new(entry);
self.entries.insert(key.clone(), Slot::Known(entry.clone()));
Ok(entry)
}
Ok(None) => {
self.entries.insert(key.clone(), Slot::Unknown { since: now });
Err(IngestError::Unauthorized)
}
// Postgres está caído: seguimos con lo que sabíamos, máximo una hora.
Err(_) => match self.entries.get(key).as_deref() {
Some(Slot::Known(entry)) if entry.loaded_at + STALE_OK > now => Ok(entry.clone()),
_ => Err(IngestError::Unavailable),
},
}
}
}Un proceso largo además refresca todas las entradas en segundo plano cada 60 segundos, así que en la práctica la solicitud nunca espera a Postgres. Así una llave revocada se rechaza en menos de un minuto, como promete Proyectos, entornos, llaves y tokens.
(2) El origen
Si la solicitud trae el encabezado Origin y la llave tiene una lista de orígenes permitidos, el origen debe estar en la lista, o la respuesta es 403 origin_not_allowed. Una solicitud sin Origin, como la de un SDK de servidor, pasa: una llave usada desde un servidor la protege su límite de velocidad, no un encabezado que controla quien envía.
Una sola capa es dueña de CORS, y es el motor. El sistema del que sale esto aprendió por qué: su URL de función y su manejador agregaban encabezados CORS a la vez, el navegador rechazó la respuesta después de guardar los datos, el SDK reintentó y los lotes llegaron dos veces. En la plantilla de AWS, la dirección que va delante de las funciones no agrega encabezados CORS propios.
(3) El límite de velocidad
Cada llave tiene un número de solicitudes por minuto desde una dirección (600 por defecto, rate_limit.ingest_per_minute). El contador es un balde de fichas en la memoria del proceso. La dirección se lee de la conexión, o del encabezado de reenvío cuando trusted_proxy_hops dice que hay un proxy delante. Se usa para este conteo y para nada más: no se escribe en un evento, en una línea de log ni en una fila.
Como el contador es por proceso, varios procesos o funciones cuentan cada uno por su lado, y el límite real es más alto que el ajuste. La alternativa es un contador compartido en Postgres o en otro servicio, en el camino de cada solicitud. Un límite de velocidad protege contra un ciclo desbocado, no es una factura; con uno aproximado basta.
(4) Decodificar
El cuerpo puede venir con gzip. La ingesta lo detecta por los dos primeros bytes, 1f 8b, diga lo que diga el Content-Type, porque sendBeacon no puede poner Content-Encoding. Descomprime en flujo y se detiene en el límite, así un cuerpo pequeño que se expande a gigabytes cuesta 2 MiB de memoria y un 413, no el proceso.
(5) y (6) La forma, y luego cada evento
events debe ser una lista de máximo 200. Después, cada evento se juzga por separado. Un evento malo nunca le cuesta el resto al lote.
| Lo que encuentra la ingesta | Lo que hace |
|---|---|
| Un campo que el contrato no lista | Lo conserva, tal como llegó |
Un type que el contrato no lista | Conserva el evento. Solo lo leerán las partes que conozcan ese tipo |
| Un texto más largo que su límite | Lo corta al límite |
| Un campo listado con el tipo equivocado o un valor fuera de su lista | Quita el campo, conserva el evento |
Falta un campo obligatorio o no sirve: sin type, ts no positivo, un evento del navegador sin sid | Descarta el evento: invalid |
| Una métrica vital fuera de su rango posible (un LCP de más de 120 s, un INP de más de 60 s, un CLS de más de 10) | Descarta el evento: invalid |
ts con más de 7 días de antigüedad | Descarta el evento: too_old |
| Un evento de una ruta bloqueada del proyecto | Descarta el evento: blocked_route |
Un atributo de span cuyo nombre contiene authorization, cookie, password, secret o token | Quita el atributo |
prj, rcv o bid enviados por la app | Los reemplaza por los del motor |
Los topes de valores posibles existen dos veces a propósito, en el SDK y aquí. Medido en el sistema del que sale esto: dos navegadores reportaron una vez valores de INP de 5 a 7 días y arrastraron un p75 al tope de la escala.
(7) La cuota
La entrada de la caché trae el slow_down del proyecto, que se decide en otra parte (mira Flujo de datos). Cuando dice send: failures, la ingesta conserva errores y solicitudes fallidas y cuenta el resto como limit_reached. La respuesta lleva el mismo slow_down, así el SDK deja de enviar lo que se descartaría.
El manejador
Esta es toda la solicitud, en orden. Fíjate en dos cosas: nada espera a Postgres, y el último await regresa solo cuando el segmento que lleva estos eventos está en el Bucket.
pub async fn ingest_events(
State(ingest): State<Arc<Ingest>>,
key: IngestKeyAuth, // encabezado Bearer o ?key=; un token sps_ es 403 wrong_credential
origin: Option<TypedHeader<Origin>>,
ClientAddr(addr): ClientAddr,
body: Bytes,
) -> Result<Json<IngestResult>, IngestError> {
let project = ingest.projects.lookup(&key.0).await?; // (1) 401
project.check_origin(origin.as_deref())?; // (2) 403
ingest.limiter.check(&project.key_id, addr)?; // (3) 429
let batch: RawBatch = decode(&body, MAX_BATCH_BYTES)?; // (4) 400, 413
if batch.events.len() > MAX_EVENTS_PER_BATCH {
return Err(IngestError::TooManyEvents); // (5) 400
}
let now = ingest.clock.now();
// ¿Sin batch_id? Se usa el hash del cuerpo, así un reintento idéntico igual se detecta.
let batch_id = batch.batch_id.unwrap_or_else(|| BatchId::from_content(&body));
let mut lines = Lines::new(&project.id, &batch_id, now);
let mut dropped = Dropped::default();
for raw in batch.events {
match validate(raw, &project, now) { // (6) cortar, limpiar, sellar
Ok(event) if project.slow_down.allows(&event) => lines.push(&event),
Ok(_) => dropped.add(Reason::LimitReached), // (7)
Err(reason) => dropped.add(reason),
}
}
let accepted = lines.len();
if accepted > 0 {
// Regresa cuando existe el segmento con estas líneas. 503 si no se pudo escribir.
ingest.intake.append(lines).await?;
}
Ok(Json(IngestResult {
accepted,
dropped: dropped.total(),
dropped_reasons: dropped.into_map(),
slow_down: project.slow_down.clone(),
}))
}De lotes a objetos
Un objeto por lote sería el diseño más simple y el más caro. Medido en el sistema del que sale esto: escribir objetos cuesta más que guardarlos. Por eso los lotes se agrupan.
El búfer (1) es un segmento abierto por proyecto y entorno. Se cierra cuando ocurre lo primero de dos cosas:
| Disparador | Valor | Por qué este valor |
|---|---|---|
| Tiempo desde su primera línea | 2 segundos | Poco frente al presupuesto de 120 segundos, y máximo 30 objetos por minuto por proyecto |
| Tamaño antes de comprimir | 4 MiB | Un worker lee un segmento completo en memoria para revisarlo; así esa lectura es pequeña |
Un tercer límite protege al proceso: si hay más de 32 MiB de líneas esperando escritura, entre todos los proyectos, los lotes nuevos reciben 503 unavailable con Retry-After: 2 hasta que el Bucket se ponga al día.
Cuando un segmento se cierra, se escribe con un solo PUT (2), y cada solicitud que le puso líneas recibe respuesta (3). Después, fuera del camino de la solicitud, entra una fila al registro segments (4). Si esa inserción falla, se guarda y se intenta de nuevo; un worker que arranca también lista las dos últimas horas de cada proyecto en el Bucket y agrega cualquier segmento que el registro no conozca.
Fíjate en el extracto en que el candado nunca se sostiene a través de un await, y en que todos los que esperan reciben el resultado de la misma escritura: o se guardan todos los lotes de un segmento, o ninguno, y cada SDK reintenta el suyo.
#[async_trait]
impl Intake for Buffer {
async fn append(&self, lines: Lines) -> Result<(), IntakeError> {
let (done, wait) = oneshot::channel();
let scope = lines.scope();
let full = {
let mut open = self.open.lock(); // parking_lot: corto, nunca se sostiene a través de un await
if self.waiting_bytes.load(Ordering::Relaxed) + lines.bytes() > MAX_WAITING_BYTES {
return Err(IntakeError::Full); // 503 con Retry-After
}
let segment = open
.entry(scope.clone())
.or_insert_with(|| OpenSegment::new(self.clock.now()));
segment.push(lines, done);
segment.bytes() >= MAX_SEGMENT_BYTES
};
if full {
self.flush(&scope).await; // el disparador por tamaño; una tarea con temporizador cubre los 2 segundos
}
wait.await.map_err(|_| IntakeError::Closed)?
}
}
impl Buffer {
async fn flush(&self, scope: &Scope) {
let Some(segment) = self.open.lock().remove(scope) else { return };
let key = Keys::new(&self.prefix, scope).segment(self.clock.now(), self.writer);
let (body, summary, waiters) = segment.finish(); // gzip, conteos, ids de lote
let result = self.store.put(&key, body, PutOptions::ndjson_gzip()).await;
if result.is_ok() {
self.ledger.register(SegmentRow::new(scope, &key, summary)); // en cola, con reintentos, aquí nunca se espera
}
for waiter in waiters {
let _ = waiter.send(result.clone().map_err(IntakeError::from));
}
}
}Lo mismo en AWS
Una función no puede guardar un segmento abierto entre dos solicitudes, y corren muchas copias a la vez. Por eso Intake tiene allá una segunda implementación: una cola.
Un proceso (serve) | Funciones de AWS | |
|---|---|---|
Intake::append | Agrega al búfer en memoria, espera el PUT | Envía las líneas validadas como un mensaje de la cola, espera la confirmación de la cola |
| Quién escribe el segmento | El mismo proceso, 2 segundos después | La función worker, despertada por la cola con hasta 10 segundos de mensajes |
| La respuesta significa | Los eventos están en el Bucket | Los eventos están en la cola, que los guarda 4 días |
| Nombre y contenido del segmento | Idénticos | Idénticos |
Un lote de más de 192 KiB después de comprimir no va en un mensaje: la ingesta lo escribe como su propio segmento y envía un mensaje que solo lo nombra. La alternativa para AWS era un flujo de entrega administrado, como en el sistema del que sale esto. Se dejó fuera porque no puede nombrar objetos por proyecto sin una función adicional que retiene al menos 60 segundos, la mitad del presupuesto de 2 minutos.
Duplicados e idempotencia
Las redes reintentan. Un navegador puede enviar un lote, perder la respuesta y enviarlo otra vez. Cada tipo de subida tiene una regla que vuelve inofensiva la segunda llegada.
| Subida | Qué la hace idempotente |
|---|---|
| Un lote de eventos | batch_id. Cada línea guardada lo lleva como bid. El primer worker que revisa un segmento anota sus ids de lote; un id ya visto, en cualquier segmento de las últimas 48 horas, lo salta todo lector. Las líneas se quedan en el objeto; no se cuentan. |
Un lote sin batch_id | La ingesta usa el SHA-256 del cuerpo como id. Un reintento de los mismos bytes se detecta; los mismos eventos reenviados en otro cuerpo, no. |
| Un fragmento de grabación | La llave es replays/<sid>/<seq>. El mismo seq otra vez reemplaza el objeto. |
| Una captura de página | La llave termina en el ts de la propia captura. La misma captura otra vez reemplaza el objeto. |
| Una solicitud OTLP | El SHA-256 del cuerpo. Los exportadores de OTLP reintentan con los mismos bytes. |
Los duplicados se resuelven al leer los segmentos, no al recibir los lotes, por una razón: recibir no debe depender de Postgres. El precio es que un lote duplicado ocupa espacio en el Bucket. Eso es barato; un conteo doble no.
Source maps y fragmentos de grabación
Los fragmentos de grabación pasan por la ingesta, una solicitud por fragmento, porque la ingesta debe revisar tres cosas antes de guardar uno: que la ruta no esté entre las rutas bloqueadas del proyecto (403 not_recordable), que la sesión tenga menos de 720 fragmentos (422 session_full) y que el proyecto esté dentro de su límite de grabaciones (429 limit_reached). El fragmento se escribe antes de responder, con Content-Type: application/json y Content-Encoding: gzip. La ingesta no mira adentro.
El límite de 4.000.000 de bytes no es arbitrario. En AWS una función recibe máximo 6 MB en una solicitud; los fragmentos de 200 KB del SDK y este tope dejan buen margen.
Los source maps nunca pasan por la ingesta. Un despliegue de una app grande son cientos de archivos y, medido en el sistema del que sale esto, unos 109 MB. Por eso la subida va en tres pasos, todos con un token de API con alcance admin:
- Tu CI llama a
POST /v1/releases/{version}/sourcemapscon la lista de archivos. - La API responde con un enlace de subida firmado por archivo, válido 15 minutos (
storage.presign_ttl_seconds). - Tu CI sube cada archivo directo al Bucket, bajo
sourcemaps/<release>/, y elindex.jsonque relaciona cada archivo compilado con su mapa.
sypnia sourcemaps upload hace los tres pasos por ti.
Entrada de OTLP
POST /v1/otlp/v1/traces acepta lo que envía cualquier exportador de OpenTelemetry y lo convierte en los mismos eventos que habría enviado un SDK de servidor de Sypnia. Después de esta conversión, nada más adelante nota la diferencia.
| En la solicitud OTLP | Se vuelve |
|---|---|
service.name del recurso | service |
service.version del recurso | ver, la versión |
deployment.environment.name del recurso (o el anterior deployment.environment) | env; production si falta |
Un span de tipo SERVER | Un server_request: tid, span, parent, method, route desde http.route, status, dur |
| Los spans de la misma traza y servicio debajo de él | Su spans[]: db si el span tiene db.system.name, http si tiene http.request.method, si no internal; se conservan máximo 200, el resto se cuenta en span_n |
Estado ERROR en un span hijo | status: error en ese span, con code desde http.response.status_code o db.response.status_code |
Un evento de span exception | Un server_error: name desde exception.type, msg desde exception.message, stack desde exception.stacktrace. El motor calcula fp, porque ningún SDK lo hizo |
Atributo de span session.id (32 caracteres hex) | sid: la solicitud entra a la línea de tiempo de esa sesión |
| Otros eventos de span, enlaces, métricas, logs | Se descartan. Los spans rechazados se cuentan en partialSuccess.rejectedSpans |
Los spans de una traza pueden llegar en solicitudes distintas. La ingesta no los espera: cada solicitud se convierte por separado, y un span SERVER que llega sin sus hijos se guarda como está. La consolidación une lo que comparte tid cuando arma el índice traces.
Por qué la ingesta no consulta Postgres
Tres razones, en orden de peso.
- Disponibilidad. Si recibir necesitara la base de datos, cada problema de la base de datos sería pérdida de datos. Con este diseño, una caída de Postgres cuesta frescura y nada más.
- Conexiones. El sistema del que sale esto agotó una vez su agrupador de conexiones: cada copia de una función que atendía solicitudes abría su propio grupo. La ingesta es la parte más copiada del motor; mantenerla lejos de la base de datos quita la mayor fuente de conexiones.
- Latencia. Leer un mapa hash toma menos de un microsegundo. Una consulta toma un viaje de ida y vuelta por la red, en cada lote de cada navegador.
Lo que la ingesta lee a cambio es pequeño, y todo sale de la entrada de caché de la llave:
| En caché por llave de ingesta | Se usa para | Qué tan fresco |
|---|---|---|
Id del proyecto, id de la llave, revoked_at | Puerta 1 | 60 s |
allowed_origins | Puerta 2 | 60 s |
rate_limit_per_minute | Puerta 3 | 60 s |
| Rutas bloqueadas, reglas de grabación, tasas de muestreo | Puerta 6, /v1/ingest/config | 60 s |
slow_down | Puerta 7 y la respuesta | 60 s |
has_server | Nada en la ingesta; viaja para el worker | 60 s |
La única escritura que la ingesta hace en Postgres es la fila del registro: una fila por segmento escrito, no una por solicitud ni una por evento. Ocurre después de responder, con una conexión por proceso, y tiene permitido fallar. Una solicitud nunca espera a Postgres.
Si Postgres está caído cuando se escribe un segmento, el segmento igual se escribe en el Bucket y los SDK igual reciben respuesta. La fila del registro se guarda en memoria y se reintenta; si el proceso muere antes de lograrlo, un worker la recupera listando el Bucket y agregando cada segmento que el registro no conozca. Hasta entonces los eventos están a salvo y todavía no se cuentan.
Logs
La ingesta escribe una línea JSON por solicitud: estado, eventos aceptados y descartados, bytes, milisegundos. Nunca la llave, la dirección ni el cuerpo. Las solicitudes que salen bien sin descartar nada se muestrean al 1 %. Medido en el sistema del que sale esto: registrar cada éxito costaba unos 18 MB de logs al día para una sola app.
Qué cambió frente al sistema del que sale
| Allá | Aquí | Por qué |
|---|---|---|
| El token de un usuario con sesión, verificado contra el servicio de autenticación de la app | Una llave de ingesta pública, orígenes permitidos y un límite de velocidad | Brief §10.2: la llave de ingesta es la única credencial para enviar al lanzar |
| Sin control de duplicados: un lote reintentado se guardaba y contaba dos veces | batch_id en cada línea | El incidente de CORS del 2026-09-30 |
| Sin límite de velocidad ni cuota | Los dos | Una llave pública los necesita |
Sin límite a la antigüedad de ts | 7 días | Un reloj viejo o una cola atascada no deben reescribir el mes pasado |
| Los registros del servidor se saltaban la ingesta y escribían directo al flujo | Todo pasa por la ingesta | Un solo lugar sella el proyecto; un servidor solo necesita una llave y una URL |
| Los campos desconocidos se quitaban con una lista de permitidos | Los campos desconocidos se conservan | Brief §10.4: esquema al leer |
Sigue
- Dónde caen los objetos y cómo se llaman.
- Qué lee los segmentos después.
- Cada campo, límite y error, para quien escriba un cliente.