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

Aplica a: el motor de Sypnia (código abierto, en tu propia infraestructura). Estado: al lanzar.  
Fuente: https://docs.sypnia.com/es/architecture/ingest/

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](https://docs.sypnia.com/es/api/ingest). La página de la API dice qué enviar; esta dice qué pasa con eso.

> **Nota: Sobre el código y los números**
>
> El Rust de aquí es un extracto de diseño; el repositorio se abre al lanzar. Los límites son los de los contratos de la API y de eventos. Los tiempos son presupuestos, no mediciones.

## 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](#source-maps-y-fragmentos-de-grabación).

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

**Figura**: Las siete puertas de un lote. Las puertas 1 a 5 pueden rechazar toda la solicitud; la 6 y la 7 descartan eventos sueltos y lo dicen en la respuesta.

1. **Llave.** El proyecto se busca en una caché. Desconocida o revocada: `401 unauthorized`. Una credencial del tipo equivocado: `403 wrong_credential`.
2. **Origen.** No está en la lista de la llave: `403 origin_not_allowed`.
3. **Límite de velocidad.** Se cuenta por llave y dirección, en memoria: `429 rate_limited`.
4. **Decodificar.** El gzip se detecta por sus primeros bytes y el tamaño tiene tope: `400 invalid_body` o `413 payload_too_large`.
5. **Forma.** `events` debe ser una lista de máximo 200: `400 too_many_events`.
6. **Cada evento.** Cortar, limpiar, descartar o sellar. Sin error: lo descartado se cuenta en `dropped`.
7. **Cuota.** `slow_down` se lee de la caché. Sin error: se cuenta en `dropped_reasons.limit_reached`.

Una línea desde Tu app (SDK), por siete puertas, hasta el Búfer y el Bucket. La solicitud es `POST /v1/ingest/events`. Ninguna de las siete puertas consulta la base de datos. Después de la puerta 7 las líneas esperan en el Búfer; un segmento llega al Bucket máximo 2 segundos después, y solo entonces la respuesta vuelve a tu app: `200` con `accepted`, `dropped` y `slow_down`. Si el Búfer no puede recibir el lote, la respuesta es `503 unavailable`.

### (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.

`crates/sypnia-ingest/src/project_cache.rs`

```rust
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](https://docs.sypnia.com/es/concepts/projects-keys-and-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](https://docs.sypnia.com/es/architecture/data-flow)). 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.

`crates/sypnia-ingest/src/events.rs`

```rust
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.

**Figura**: Confirmación en grupo. Los lotes que llegan dentro de los mismos 2 segundos salen en un objeto, y todos reciben respuesta cuando existe.

1. El búfer: un segmento abierto por proyecto y entorno. Los lotes del navegador A (0,2 s), de shop-api (0,6 s) y del navegador B (1,4 s) esperan en él. Cierra a los 2 s, o a los 4 MiB, lo que ocurra primero.
2. Un solo `PUT` escribe el búfer cerrado en el Bucket como un objeto: 19 eventos de 3 lotes.
3. Cada solicitud que puso líneas en el objeto recibe su `200`, todas en el mismo momento.
4. Después de responder, una fila del registro va a Postgres.

Tres fuentes a la izquierda: el navegador A, el navegador B y shop-api (un SDK de servidor). Cada una envía un lote al búfer de `prj_5k2m9x4q7w1z · production`, donde el tiempo corre de 0 s a 2 s: el lote `0b9f…` con 6 eventos llega a los 0,2 s, el lote `5d0c…` con 2 eventos a los 0,6 s, y el lote `71aa…` con 11 eventos a los 1,4 s. Cada uno espera hasta que el búfer cierra. El búfer se vuelve el archivo `20260312T091216Z-7f3a9c.ndjson.gz`, que llega al Bucket en un solo `PUT`; entonces las tres respuestas vuelven en abanico a las tres fuentes.

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.

`crates/sypnia-ingest/src/buffer.rs`

```rust
#[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`:

1. Tu CI llama a `POST /v1/releases/{version}/sourcemaps` con la lista de archivos.
2. La API responde con un enlace de subida firmado por archivo, válido 15 minutos (`storage.presign_ttl_seconds`).
3. Tu CI sube cada archivo directo al Bucket, bajo `sourcemaps/<release>/`, y el `index.json` que 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.

1. **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.
2. **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.
3. **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
