# Agregación

> Cómo la consolidación convierte una hora de eventos crudos en números sin un motor SQL, con sus agrupaciones, histogramas, armado de sesiones, el registro que hace que los contadores sumen exactamente una vez, sus límites de memoria y el archivo Parquet diario.

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

La consolidación es la parte del motor que cuenta. Cada 5 minutos lee los eventos crudos de la hora abierta y escribe velocidad de páginas, velocidad de la API, clics, el índice de sesiones, el índice de trazas y el uso. No toca los problemas: esos son de la vía rápida, descrita en [Agrupación de problemas](https://docs.sypnia.com/es/architecture/problem-grouping).

El sistema del que sale este motor hacía este trabajo con un motor SQL embebido, una vez por hora. Su propia auditoría contó qué era ese SQL: unas 20 sentencias y 270 líneas, todas agrupaciones de una sola pasada sobre una hora de filas, ninguna cruzando horas. Eso es un ciclo y unos mapas hash. El motor de Sypnia lo escribe exactamente así.

> **Nota: Sobre el código y los números**
>
> El Rust y el SQL de aquí son extractos de diseño; el repositorio se abre al lanzar. Las cifras de memoria son presupuestos con su aritmética. Los límites de los histogramas y las reglas de upsert son los que corren en producción en el sistema del que sale esto, sin cambios.

## Una corrida, para un proyecto y una hora

**Figura (diagrama aún sin dibujar)**: Una corrida de la consolidación. Se lee cada segmento de la hora; qué se hace con cada línea depende de si su segmento ya se sumó.

Mostrará: El mismo diagrama de flujo de una corrida que la figura 1 de la página en inglés (architecture/aggregation), con las mismas llamadas (1) a (4), carriles (A), (B), (C) y el mismo elemento encendido (la caja de la transacción). Rótulos traducidos: encabezado «proyecto prj_5k2m9x4q7w1z · production · hora 09»; 1 «Registro: ¿qué segmentos tiene la hora 09, cuáles son nuevos?»; 2 «Leer cada segmento del Bucket en flujo» («gunzip → líneas → Event; un segmento en memoria a la vez»); carril A «HourFold» («todos los segmentos de la hora»; fichas «páginas × dispositivo», «rutas de la API», «índice de trazas»); carril B «DeltaFold» («solo los segmentos aún no sumados»; fichas «sesiones», «clics diarios», «uso»); carril C «Archivo temporal en disco local» («cada línea, más un índice sid → posiciones»); 3 «Archivos por sesión» («8 subidas a la vez, misma llave = sobrescribir»); 4 «Una transacción»: «REEMPLAZAR las filas de la hora (de HourFold)», «SUMAR a los contadores (de DeltaFold)», «marcar los segmentos nuevos como consolidados»; nota «las tres, o ninguna».

Los pasos, con las llamadas de la figura:

1. **(1) Preguntar al registro.** La tabla `segments` lista los segmentos de la hora y dice cuáles tienen `rolled_at` vacío. Si ninguno es nuevo y los números de la hora están al día, la corrida termina aquí.
2. **(2) Leer en flujo.** Cada segmento se trae, se descomprime y se lee línea por línea. Una línea que no se puede leer se cuenta y se salta. Una línea cuyo lote está en la lista `skipped` del segmento, un duplicado, la saltan todos los carriles.
3. **(A) (B) (C) Agrupar.** Cada evento va hasta a tres lugares, descritos abajo.
4. **(3) Escribir los archivos por sesión** en el Bucket. Son sobrescrituras, así que pueden ocurrir antes de la transacción y repetirse sin problema.
5. **(4) Confirmar.** Una transacción reemplaza las filas de la hora, suma a los contadores y marca los segmentos. Si algo falla, no se escribe nada y la siguiente pasada hace toda la corrida de nuevo.

### Qué horas se consolidan

En cada pasada a la que le toca, para cada proyecto y entorno:

| Hora                             | Se consolida cuando                                                                                                                                     |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| La hora actual                   | Tiene un segmento con `rolled_at` vacío                                                                                                                 |
| La hora anterior                 | Hasta 10 minutos después de que terminó, y una vez más para cerrarla                                                                                    |
| Cualquier hora de las últimas 48 | Su fila en `hours` está en `failed`, o en `running` hace más de 20 minutos, o el registro tiene un segmento suyo sin consolidar; primero las más viejas |
| Más viejas                       | Solo a mano: `sypnia aggregate --from … --to …`                                                                                                         |

La ventana de 48 horas y la regla de 20 minutos para una corrida atascada se conservan del sistema del que sale esto, donde recuperaron cada hora que falló.

## Leer objetos en flujo

Un segmento mide máximo 4 MiB antes de comprimir, así que se lee completo y luego se recorre línea por línea. Los eventos nunca se juntan en una lista: cada uno se agrupa y se olvida. Lo que queda en memoria crece con el número de **cosas distintas** en la hora (rutas, sesiones, elementos), no con el número de eventos.

Fíjate en los tres destinos de una línea: un evento con tipo, un evento de tipo desconocido que se conserva para los archivos pero que las agrupaciones saltan, y basura que se cuenta.

`crates/sypnia-pipeline/src/rollup.rs`

```rust
async fn fold_segment(
    engine: &Engine,
    segment: &SegmentRow,
    hour: &mut HourFold,
    delta: Option<&mut DeltaFold>, // None cuando este segmento ya se sumó a los contadores
    spill: &mut Spill,
) -> Result<SegmentStats, RollupError> {
    let mut stats = SegmentStats::default();
    let mut delta = delta;
    let mut lines = engine.store.read_lines(&segment.key).await?;

    while let Some(line) = lines.try_next().await? {
        let record: Record = match serde_json::from_slice(&line) {
            Ok(record) => record,
            Err(_) => { stats.unreadable += 1; continue; }
        };
        if segment.skipped.contains(&record.bid) {
            stats.duplicates += 1; // el mismo lote llegó antes, en otro segmento
            continue;
        }
        hour.push(&record.event);                 // (A) números de la hora
        if let Some(delta) = delta.as_deref_mut() {
            delta.push(&record.event);            // (B) contadores que solo suman
        }
        if let Some(sid) = record.event.session_id() {
            spill.append(sid, record.event.ts(), &line)?; // (C) la línea cruda, para el archivo de la sesión
        }
        stats.events += 1;
    }
    Ok(stats)
}
```

## Las agrupaciones

Cada tabla de números es un mapa hash: la llave es la llave primaria de la tabla sin el proyecto ni la hora, y el valor es una estructura pequeña de contadores.

| Grupo | Llave del mapa                           | Valor                                                                                                                                                                                                              | Tabla                  | Escritura            |
| ----- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- | -------------------- |
| Hora  | `(route, device)`                        | vistas, conjunto de sesiones, errores, clics de rabia y muertos, cuatro histogramas                                                                                                                                | `perf_pages_hourly`    | Reemplazar           |
| Hora  | `(method, route)`                        | mitad del navegador: solicitudes, correctas, rechazadas, fallidas, histograma de duración; mitad del servidor: solicitudes, fallidas, tiempos agotados, llamadas y tiempo de base de datos, histograma de duración | `perf_api_hourly`      | Reemplazar           |
| Hora  | `trace id`                               | el resumen de la solicitud y dónde están sus spans                                                                                                                                                                 | `traces`               | Reemplazar por llave |
| Delta | `sid`                                    | primer y último `ts`, persona, cuenta, dispositivo, contadores, rutas en orden                                                                                                                                     | `sessions`             | Sumar                |
| Delta | `(day, route, device, cell x, cell y)`   | clics                                                                                                                                                                                                              | `clicks_daily`         | Sumar                |
| Delta | `(day, route, device, selector)`         | clics, de rabia, muertos, el rol y la etiqueta más frecuentes                                                                                                                                                      | `click_elements_daily` | Sumar                |
| Delta | `(day, route, device, metric, selector)` | muestras, malas, por mejorar, histograma                                                                                                                                                                           | `vital_elements_daily` | Sumar                |
| Delta | `(day, name)`                            | conteo, personas                                                                                                                                                                                                   | `custom_events_daily`  | Sumar                |
| Delta | `(day, route, field)`                    | conteo, sesiones                                                                                                                                                                                                   | `form_failures_daily`  | Sumar                |
| Delta | `day`                                    | eventos contados, todos los eventos, sesiones con grabación                                                                                                                                                        | `usage_daily`          | Sumar                |

Las tablas de **reemplazar** se calculan con todos los segmentos de la hora, en cada corrida. Por eso un conteo de sesiones distintas en una hora puede ser exacto: el conjunto se arma completo cada vez. Las tablas de **sumar** se calculan solo con los segmentos nuevos, y se suman a lo guardado.

Esta es la agrupación de páginas. Fíjate en que una sesión se cuenta con un conjunto, así diez vistas de página de una persona son una sesión, y en que una métrica vital entra a un histograma en vez de guardarse.

`crates/sypnia-pipeline/src/fold/pages.rs`

```rust
#[derive(Default)]
pub struct PageCell {
    pub views: u32,
    pub sessions: HashSet<u64>, // hash de 64 bits del sid: 8 bytes por sesión, no 32
    pub errors: u32,
    pub rage_clicks: u32,
    pub dead_clicks: u32,
    pub lcp: Histogram<15>,
    pub inp: Histogram<15>,
    pub ttfb: Histogram<15>,
    pub cls: Histogram<10>,
}

#[derive(Default)]
pub struct PageFold {
    cells: HashMap<(Route, Device), PageCell>,
}

impl PageFold {
    pub fn push(&mut self, event: &Event) {
        match event {
            Event::PageView(e) => {
                let cell = self.cell(e);
                cell.views += 1;
                cell.sessions.insert(e.sid.hash64());
            }
            Event::Vital(e) => {
                let cell = self.cell(e);
                match e.body.name {
                    VitalName::Lcp => cell.lcp.record(e.body.value),
                    VitalName::Inp => cell.inp.record(e.body.value),
                    VitalName::Ttfb => cell.ttfb.record(e.body.value),
                    VitalName::Cls => cell.cls.record(e.body.value),
                    VitalName::Fcp => {} // se recolecta y se muestra en la sesión, no se agrega
                }
            }
            Event::Error(e) => self.cell(e).errors += 1,
            Event::RageClick(e) => self.cell(e).rage_clicks += 1,
            Event::DeadClick(e) => self.cell(e).dead_clicks += 1,
            _ => {}
        }
    }

    fn cell<T>(&mut self, e: &Browser<T>) -> &mut PageCell {
        let route = e.route.clone().unwrap_or_else(Route::unknown);
        let device = e.dev.unwrap_or(Device::Desktop);
        self.cells.entry((route, device)).or_default()
    }
}
```

Dos cosas que el motor SQL hacía por accidente ahora son reglas. Allá `arg_max` y `mode` desempataban al azar; aquí un empate va al `ts` más temprano y luego al texto menor. Y la etiqueta de un elemento con clics se conserva solo cuando una forma de texto cubre más de la mitad de sus clics y el elemento no es una fila de tabla ni un enlace con un id, la regla que mantiene los nombres de personas fuera de los mapas de clics.

## Histogramas y percentiles

El motor nunca guarda una duración para calcular un percentil después. Guarda cuántos valores cayeron en cada celda de un conjunto fijo.

**Figura (diagrama aún sin dibujar)**: Un histograma son 15 enteros. Dos se unen sumando, y un percentil se lee del arreglo cuando lo pides.

Mostrará: El mismo diagrama de histograma de LCP que la figura 2 de la página en inglés (architecture/aggregation): 15 celdas, los mismos límites (50 … 20000), los mismos conteos (0, 0, 1, 3, 9, 14, 18, 22, 12, 8, 6, 4, 2, 1, 0), llamadas (1) a (3) y el mismo elemento encendido (la celda entre 1500 y 2000, con el marcador a 62 % de su ancho). Rótulos traducidos: título «lcp_hist de /checkout · desktop · una hora = 15 enteros»; última celda «desborde»; llamada «p75 = 1.813 ms: el valor 75 de 100 cae en esta celda»; fila inferior «hora 09: \[0,0,1,3,9,…]» más «hora 10: \[0,1,0,4,7,…]» igual a «día: \[0,1,1,7,16,…]», con la etiqueta «unir es sumar».

| Límites (1)                                                                        | Celdas | Se usa para                                            |
| ---------------------------------------------------------------------------------- | ------ | ------------------------------------------------------ |
| `50, 100, 200, 300, 500, 750, 1000, 1500, 2000, 3000, 5000, 8000, 12000, 20000` ms | 15     | LCP, INP, TTFB, duración de solicitudes y del servidor |
| `0.01, 0.025, 0.05, 0.1, 0.15, 0.25, 0.4, 0.6, 1`                                  | 10     | CLS                                                    |

Estos límites son un contrato. Son los mismos del sistema del que sale esto, y cambiarlos volvería ilegibles los arreglos guardados. Un valor va a la celda cuyo índice es el número de límites estrictamente menores que él, así que un valor igual a un límite cae en la celda de ese límite. La última celda es el desborde.

Fíjate en el extracto en que `percentile` devuelve `None` para un histograma vacío, nunca 0, y en que interpola dentro de la celda (2) en vez de responder con un límite.

`crates/sypnia-core/src/histogram.rs`

```rust
pub const LATENCY_MS: &[f64] =
    &[50.0, 100.0, 200.0, 300.0, 500.0, 750.0, 1000.0, 1500.0, 2000.0, 3000.0, 5000.0, 8000.0, 12000.0, 20000.0];

#[derive(Debug, Clone, PartialEq)]
pub struct Histogram<const N: usize> {
    bounds: &'static [f64], // N - 1 límites
    cells: [u32; N],
}

impl<const N: usize> Histogram<N> {
    pub fn record(&mut self, value: f64) {
        // Cuántos límites quedan estrictamente por debajo del valor. NaN y negativos se descartan en la ingesta.
        let cell = self.bounds.partition_point(|bound| *bound < value);
        self.cells[cell] = self.cells[cell].saturating_add(1);
    }

    /// Unir dos horas, o una fila guardada y una nueva: posición por posición.
    pub fn merge(&mut self, other: &Self) {
        for (mine, theirs) in self.cells.iter_mut().zip(other.cells) {
            *mine = mine.saturating_add(theirs);
        }
    }

    /// `p` en 0..=1. Lineal dentro de la celda donde cae el objetivo; la celda de desborde responde su límite inferior.
    pub fn percentile(&self, p: f64) -> Option<f64> {
        let total: u64 = self.cells.iter().map(|c| u64::from(*c)).sum();
        if total == 0 {
            return None;
        }
        let target = ((total as f64 * p).ceil() as u64).max(1);
        let mut before = 0u64;
        for (i, count) in self.cells.iter().map(|c| u64::from(*c)).enumerate() {
            if before + count >= target {
                let lower = if i == 0 { 0.0 } else { self.bounds[i - 1] };
                let Some(upper) = self.bounds.get(i) else { return Some(lower) };
                let inside = ((target - before) as f64 - 0.5) / count as f64;
                return Some(lower + (upper - lower) * inside.clamp(0.0, 1.0));
            }
            before += count;
        }
        None
    }
}
```

En la figura hacen falta 75 de 100 valores. Las celdas hasta 1.500 ms tienen 67. La siguiente tiene 12, así que el objetivo es su valor número 8: 1.500 + 500 × (8 − 0,5) ÷ 12 = 1.813 ms. La misma función lee un p75 de una hora o de 30 días: primero se suman los arreglos (3) y luego se leen una sola vez.

## Armado de sesiones

Una sesión se arma con eventos que llegan en muchos lotes, del navegador y del servidor, durante minutos u horas. La consolidación hace tres cosas con ellos.

**1. Completa quién era la sesión.** La primera vista de página de una visita suele enviarse antes de que la app sepa quién es la persona. Dentro de una sesión, un evento sin persona toma la del siguiente evento identificado, o si no la del anterior. En SQL eran dos funciones de ventana. Aquí son los eventos de un `sid` ordenados por `ts`, una pasada hacia adelante y una hacia atrás.

**2. Escribe el archivo de la sesión.** El carril (C) de la primera figura. Cada línea con `sid` se agrega a un archivo temporal en disco local, y un índice recuerda dónde están las líneas de cada sesión. Al final, para cada sesión que tocó un segmento nuevo, sus líneas se leen de vuelta, se ordenan por `ts` y se escriben como `sessions/<sid>/hr=<día>-<hora>.ndjson.gz`, ocho subidas a la vez.

El archivo temporal existe por un incidente del sistema del que sale esto: escribir los archivos por sesión directo al bucket mantenía abierto un búfer de subida de unos 76 MiB por sesión, y una hora con 92 sesiones dejó la tarea sin memoria. La regla aprendida fue «escribir a disco local, subir después». El índice cuesta 32 bytes por evento; las líneas están en disco.

**3. Actualiza la fila del índice.** Una fila por sesión en `sessions`, que cada corrida ensancha. Esta es la mitad de «sumar»: los contadores suman, la primera y la última hora se ensanchan, la identidad se completa cuando aparece, y una grabación, una vez vista, se queda.

`crates/sypnia-db/sql/session_upsert.sql`

```sql
INSERT INTO sessions AS s
       (project_id, sid, environment, started_at, ended_at, person_id, account_id, device_id,
        release, device, browser, os, locale, entry_route, routes,
        page_views, clicks, rage_clicks, dead_clicks, errors, requests, failed_requests, has_replay)
SELECT $1, * FROM UNNEST($2::text[], $3::text[], $4::timestamptz[], $5::timestamptz[], $6::text[], $7::text[],
        $8::text[], $9::text[], $10::text[], $11::text[], $12::text[], $13::text[], $14::text[], $15::jsonb[],
        $16::int[], $17::int[], $18::int[], $19::int[], $20::int[], $21::int[], $22::int[], $23::bool[])
       AS t(sid, environment, started_at, ended_at, person_id, account_id, device_id, release, device, browser,
            os, locale, entry_route, routes, page_views, clicks, rage_clicks, dead_clicks, errors, requests,
            failed_requests, has_replay)
ON CONFLICT (project_id, sid) DO UPDATE SET
    started_at  = LEAST(s.started_at, EXCLUDED.started_at),
    ended_at    = GREATEST(s.ended_at, EXCLUDED.ended_at),
    person_id   = COALESCE(EXCLUDED.person_id, s.person_id),   -- gana un valor nuevo no nulo
    account_id  = COALESCE(EXCLUDED.account_id, s.account_id),
    device      = COALESCE(s.device, EXCLUDED.device),         -- se queda el primero que se vio
    browser     = COALESCE(s.browser, EXCLUDED.browser),
    release     = COALESCE(EXCLUDED.release, s.release),       -- el más nuevo
    routes      = merge_routes(s.routes, EXCLUDED.routes, 50), -- en orden de primera vista, máximo 50
    page_views  = s.page_views + EXCLUDED.page_views,
    clicks      = s.clicks + EXCLUDED.clicks,
    rage_clicks = s.rage_clicks + EXCLUDED.rage_clicks,
    dead_clicks = s.dead_clicks + EXCLUDED.dead_clicks,
    errors      = s.errors + EXCLUDED.errors,
    requests    = s.requests + EXCLUDED.requests,
    failed_requests = s.failed_requests + EXCLUDED.failed_requests,
    has_replay  = s.has_replay OR EXCLUDED.has_replay;         -- una vez true, se queda
```

Las filas viajan como arreglos por `UNNEST`, 2.000 filas por sentencia, como en el sistema del que sale esto. Una sesión que solo vio el servidor actualiza una fila existente y nunca crea una: un proyecto que solo envía datos del servidor tiene trazas y no tiene sesiones.

Al agrupar se aplican dos reglas más de emparejamiento, las dos conservadas:

- Un registro **parcial** del servidor, escrito mientras una solicitud seguía corriendo, se descarta cuando el registro completo de la misma traza está en la hora. Si el completo nunca llega, el parcial cuenta como tiempo agotado.
- Un `request` del navegador y el `server_request` con el mismo id de traza son una sola fila en `traces`, con las dos duraciones.

## Exactamente una vez: el registro

Los contadores que suman son peligrosos. Suma el mismo segmento dos veces y una sesión tiene 40 clics en vez de 20. Las funciones se reintentan, las corridas se cruzan, los procesos mueren a la mitad. El sistema del que sale esto tuvo el incidente: una corrida falló después de escribir unas tablas, y el reintento las duplicó.

La respuesta tiene dos partes, y las dos van en una sola transacción.

**Figura (diagrama aún sin dibujar)**: El registro a las 09:20. Las filas 3 y 4 son nuevas para la consolidación; marcarlas y sumar sus contadores ocurre en la misma transacción.

Mostrará: El mismo diagrama de dos paneles que la figura 3 de la página en inglés (architecture/aggregation), con la misma tabla de cuatro filas, los mismos valores, llamadas (1) a (3) y el mismo elemento encendido (el paso 1 y su rama). Los nombres de columnas y el SQL no se traducen. Rótulos traducidos: panel izquierdo «El registro: una fila por segmento»; «(vacío)» en lugar de «(empty)»; notas «nuevo para la consolidación», «este lote ya llegó en la fila 2: no se cuenta», «nuevo para la vía rápida». Panel derecho «La corrida de las 09:20, una transacción»: paso 1 «… → debe devolver 2 filas»; paso 2 «DELETE + INSERT de las filas de la hora 09 (de los cuatro segmentos)»; paso 3 «INSERT … ON CONFLICT DO UPDATE: sumar los contadores solo de las filas 3 y 4»; paso 4 «COMMIT»; rama «¿devolvió menos? otra corrida llegó primero → ROLLBACK, no se escribe nada».

**El registro dice qué se sumó.** Cada segmento tiene una fila en `segments`. `rolled_at` (1) se llena en la misma transacción que suma los contadores del segmento. Si la transacción se confirma, pasaron las dos cosas. Si no, ninguna.

**La reserva detecta una carrera.** La primera sentencia de la transacción (3) marca los segmentos que va a sumar y revisa cuántas filas marcó. Si otra corrida marcó alguno primero, el conteo queda corto, y esta corrida se revierte sin escribir nada. Fíjate en que no hay un candado que olvidar ni un tiempo de espera que ajustar: la fila misma es el candado.

`crates/sypnia-db/src/rollup_commit.rs`

```rust
pub async fn commit_hour(
    pool: &PgPool,
    scope: &Scope,
    hour: DateTime<Utc>,
    hourly: &HourlyRows,     // de todos los segmentos de la hora: reemplaza
    delta: &DeltaRows,       // solo de los segmentos nuevos: suma
    new_segments: &[String],
) -> Result<CommitOutcome, DbError> {
    let mut tx = pool.begin().await?;

    // La reserva. Marcar y sumar comparten esta transacción, así que no se pueden separar.
    let claimed: Vec<String> = sqlx::query_scalar(
        "UPDATE segments SET rolled_at = now()
          WHERE project_id = $1 AND key = ANY($2) AND rolled_at IS NULL
      RETURNING key",
    )
    .bind(scope.project.as_str())
    .bind(new_segments)
    .fetch_all(&mut *tx)
    .await?;

    if claimed.len() != new_segments.len() {
        return Ok(CommitOutcome::LostRace); // al soltar `tx` se revierte; queda el trabajo de la otra corrida
    }

    replace_pages(&mut tx, scope, hour, &hourly.pages).await?;   // DELETE de la hora, INSERT … UNNEST
    replace_api(&mut tx, scope, hour, &hourly.api).await?;
    upsert_traces(&mut tx, scope, &hourly.traces).await?;

    upsert_sessions(&mut tx, scope, &delta.sessions).await?;     // los contadores suman, las fechas se ensanchan
    add_daily(&mut tx, scope, &delta.daily).await?;
    add_usage(&mut tx, scope, &delta.usage).await?;

    mark_hour(&mut tx, scope, hour, HourStatus::Open, hourly.events).await?;
    tx.commit().await?;
    Ok(CommitOutcome::Committed)
}
```

Los lotes duplicados son el tercer caso, y el registro también lo cubre (2). Cuando la vía rápida revisa un segmento, inserta sus ids de lote en `ingest_batches` con `ON CONFLICT DO NOTHING`. Los ids que **no** se insertaron ya son de un segmento anterior; se escriben en la columna `skipped` de este segmento. Desde entonces todo lector, la vía rápida, la consolidación y el escritor de Parquet, salta esas líneas. La vía rápida siempre revisa un segmento antes de que la consolidación lo sume: una corrida que encuentra un segmento sin revisar lo revisa primero.

| Qué puede salir mal                                                        | Por qué nada se cuenta dos veces                                                                                                        |
| -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| La corrida muere antes de confirmar                                        | No se escribió nada. La siguiente pasada la repite.                                                                                     |
| La corrida muere después de confirmar                                      | `rolled_at` está lleno. La siguiente pasada no ve nada nuevo.                                                                           |
| Dos workers consolidan la misma hora a la vez                              | Sus filas por hora son iguales, así que reemplazar dos veces no hace daño; para los contadores, una reserva gana y la otra se revierte. |
| El SDK envió un lote dos veces                                             | Su segunda copia está en una lista `skipped`.                                                                                           |
| La cola entregó un mensaje dos veces (AWS)                                 | Dos segmentos traen el mismo id de lote; el segundo se salta.                                                                           |
| Alguien corre `sypnia aggregate --from … --to …` sobre un día ya procesado | Las tablas por hora se reemplazan con los mismos valores. Los contadores no se tocan, porque todo segmento tiene `rolled_at`.           |

## Eventos tardíos y desordenados

Hay tres relojes: el `ts` del evento, de un dispositivo que puede estar mal; `rcv`, cuando lo recibió la ingesta; y la hora del segmento, cuando se escribió.

| Pregunta                                                                   | Respuesta                                                                                                                                                                                                                                                  |
| -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ¿En los números de qué hora cuenta un evento?                              | En la hora en que se escribió su segmento. Una vista de página enviada a las 09:59:58 y escrita a las 10:00:01 cuenta en la hora 10. Es la regla del sistema del que sale esto, y es lo que permite cerrar una hora: nada puede llegar al pasado.          |
| ¿En los contadores de qué día?                                             | El día UTC de esa misma hora.                                                                                                                                                                                                                              |
| ¿Dónde aparece en la línea de tiempo de una sesión?                        | En su `ts`. Un archivo de sesión va ordenado por `ts`, sin importar en qué orden llegaron los lotes.                                                                                                                                                       |
| ¿Un evento que llega un día tarde, de un teléfono que estuvo sin conexión? | Se acepta hasta con 7 días. Cuenta en la hora en que llega, ensancha las horas de su sesión y se escribe en el archivo de esa sesión para la hora de llegada. La línea de tiempo sigue en orden, porque quien lee une los archivos de una sesión por `ts`. |
| ¿Un dispositivo con el reloj mal?                                          | El lote trae `sent_at`. Cuando difiere de `rcv` en más de 2 minutos, la consolidación corre los `ts` del lote por esa diferencia antes de usarlos para ordenar y para las horas de la sesión. La línea guardada conserva el `ts` original.                 |
| ¿Eventos de un lote en desorden?                                           | El orden dentro de un lote no importa. Nada en la consolidación depende de él.                                                                                                                                                                             |

El costo de contar por llegada hay que decirlo: la gráfica de una hora puede estar corrida unos segundos en sus bordes, y una ráfaga que llega tarde se muestra cuando llegó. Para números por hora y por día, es el cambio correcto frente a no poder cerrar nunca una hora.

## Límites de memoria

Un proyecto se consolida dentro de un presupuesto de 256 MB. Se consolidan `processing.concurrency` proyectos a la vez (2 por defecto), así que un worker necesita unos 512 MB para la consolidación, sin importar cuántos proyectos haya.

| Qué ocupa memoria                          | Crece con                            | Aritmética para una hora movida: 60.000 eventos, 1.000 sesiones, 200 rutas |
| ------------------------------------------ | ------------------------------------ | -------------------------------------------------------------------------- |
| Un segmento mientras se lee                | El tamaño del segmento, con tope     | Máximo 4 MiB de entrada comprimida; unos 32 MB mientras se lee             |
| Celdas de páginas y de la API              | Rutas × dispositivos                 | 600 celdas × unos 400 bytes = 0,24 MB                                      |
| Conjuntos de sesiones dentro de las celdas | Sesiones × rutas que visitó cada una | 1.000 × 10 × 8 bytes = 0,08 MB                                             |
| Filas de sesión del delta                  | Sesiones en segmentos nuevos         | 1.000 × cerca de 1 KB = 1 MB                                               |
| Celdas de clics y elementos                | Elementos distintos con clics        | 5.000 × unos 300 bytes = 1,5 MB                                            |
| El índice del archivo temporal             | Eventos con sesión                   | 60.000 × 32 bytes = 1,9 MB                                                 |
| Filas esperando la transacción             | La suma de lo anterior               | unos 3 MB                                                                  |
| **Total**                                  |                                      | **unos 40 MB**, casi todo el segmento que se está leyendo                  |

Esa hora movida es diez veces la hora pico anotada para el sistema del que sale esto, donde al motor SQL se le dio un techo de 1.200 MB para el mismo trabajo. A cien veces, 600.000 eventos y 10.000 sesiones, la misma aritmética da unos 110 MB. El archivo temporal en disco son las líneas de la hora sin comprimir: unos 60 MB para la hora movida.

Nada aquí crece con el número de eventos, salvo el índice del archivo temporal y el archivo en disco. Si un proyecto sí pasa su presupuesto, la corrida se detiene, la hora se marca `failed` con la razón, y a los 30 minutos la alerta `engine.failing` dice qué proyecto. La agrupación nunca le quita memoria a la corrida de otro proyecto.

## Paralelismo

- **Entre proyectos:** hasta `processing.concurrency` corridas a la vez, cada una con su propia conexión. Los proyectos son independientes: ninguna corrida lee filas u objetos de otro proyecto.
- **Dentro de una corrida:** los segmentos se traen de a cuatro y se agrupan en orden de llave, así los resultados no dependen del tiempo. Los archivos por sesión se suben de a ocho.
- **Entre workers:** seguro por construcción. Dos workers que toman la misma hora producen las mismas filas por hora, y solo gana una reserva. Para no desperdiciar trabajo, una corrida primero pone la fila de `hours` en `running`; otro worker salta una hora que lleva menos de 20 minutos en `running`.
- **La base de datos:** un worker mantiene una conexión por corrida y una para la vía rápida. Regla conservada del sistema del que sale esto, que una vez agotó su agrupador: los trabajos largos usan pocas conexiones de sesión; el código que atiende solicitudes usa un grupo pequeño y acotado, y responde `503` con `Retry-After` en vez de hacer fila.

## Compactación a Parquet

Una vez al día, a las 02:30 UTC, el día anterior de cada proyecto se vuelve un archivo Parquet por entorno: `parquet/<environment>/dt=<día>/events.parquet`, comprimido con ZSTD.

| Paso        | Regla                                                                                                                                                                                                                                                                                                               |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Leer        | Los segmentos del día, en orden de llave, en flujo como la consolidación. Los lotes duplicados se saltan, así que el archivo Parquet es el día sin duplicados.                                                                                                                                                      |
| Esquema     | Lo fija la versión del motor: una columna con tipo por cada campo del contrato de eventos, listas anidadas para `spans`, y `extra`, un texto JSON con todo campo desconocido. El sistema del que sale esto dejaba que el esquema se adivinara de los datos de cada día, así que cambiaba de un día a otro; aquí no. |
| Escribir    | A un archivo local en grupos de 50.000 filas, y luego una sola subida. Nunca una subida en flujo: la misma lección de los archivos por sesión.                                                                                                                                                                      |
| Idempotente | El objeto se sobrescribe. Correr el día de nuevo da el mismo archivo.                                                                                                                                                                                                                                               |
| Después     | Los segmentos se quedan hasta que termine su propia retención. Parquet es un agregado, no un reemplazo: el motor solo lee segmentos.                                                                                                                                                                                |

El archivo es tuyo. Cualquier herramienta que lea Parquet desde un bucket puede consultarlo, y el motor nunca lo necesita para responder una solicitud.

## Qué cambió frente al sistema del que sale

| Allá (motor SQL embebido, cada hora)                                  | Aquí (Rust simple, cada 5 minutos)                                              |
| --------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| Esquema adivinado del JSON de la hora, `union_by_name`                | `Event` con tipos y `extra` para campos desconocidos; una línea dañada se salta |
| Completar identidad con dos funciones de ventana                      | Ordenar por (`sid`, `ts`), una pasada adelante y una atrás                      |
| `count(DISTINCT sid)`                                                 | Un conjunto de hashes de 64 bits por celda                                      |
| `arg_max`, `mode` con empates al azar                                 | Las mismas agrupaciones con un desempate definido                               |
| `COPY` particionado a disco local, luego subir                        | Un archivo temporal y un índice, luego subir                                    |
| Reemplazar por hora; sumar protegido por una fila de corrida por hora | Reemplazar por hora; sumar protegido por una fila del registro por segmento     |
| Techo de 1.200 MB, un binario nativo de 68 MB, solo x86_64            | Presupuesto de 256 MB, sin dependencia nativa, cualquier arquitectura           |
| El SQL a mano sobre eventos crudos venía gratis                       | Ya no. Usa los archivos Parquet con tu propia herramienta                       |

La última fila es el costo honesto del cambio. Un motor SQL embebido dejaba que una persona consultara eventos crudos en el momento. El motor renuncia a eso para seguir siendo un solo binario pequeño, y a cambio te da Parquet.

## Sigue
