# Estructura del almacenamiento

> Dónde guarda cada tipo de dato un motor con alojamiento propio, cuánto espacio ocupa, cómo medirlo, y qué reglas ponerle al bucket y cuáles evitar.

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

Para agentes: La vista del operador sobre dónde guarda datos el motor de Sypnia con alojamiento propio: los seis prefijos del bucket bajo el id de cada proyecto con sus ajustes de retención, las tablas de Postgres que crecen, tamaños estimados por millón de eventos y para un proyecto pequeño y uno mediano, comandos para medir el uso real, y qué reglas de ciclo de vida, versionado y clases de almacenamiento son seguras en el bucket.

**\[Motor]** Esta página es para quien opera un motor con alojamiento propio y necesita responder tres preguntas: dónde está cada cosa, qué tan grande se va a poner, y qué reglas debe tener el bucket. El diseño que hay detrás, hasta los nombres de los objetos y las columnas de las tablas, está en [Almacenamiento](https://docs.sypnia.com/es/architecture/storage); esta página no lo repite. En Sypnia Cloud nada de esto queda a tu cargo.

El motor guarda datos en dos lugares y en ninguno más: un bucket y una base de datos Postgres. El disco del propio motor no guarda nada que necesites conservar.

## El bucket

Cada llave de objeto empieza por el id del proyecto. Debajo hay seis carpetas, una por tipo de dato.

```text
<storage.prefix>prj_5k2m9x4q7w1z/
├── events/      eventos crudos, como llegaron              los escribe la ingesta
├── sessions/    los mismos eventos, un archivo por sesión y hora   los escribe el worker
├── replays/     fragmentos de grabación                    los escribe la ingesta
├── snapshots/   capturas de página, para mapas de clics    las escribe la ingesta
├── sourcemaps/  una carpeta por versión (release)          los escribe tu CI
└── parquet/     un archivo por día, para tus herramientas  lo escribe el worker
```

| Carpeta       | Qué la hace crecer                      | Se guarda por defecto                             | Ajuste                             |
| ------------- | --------------------------------------- | ------------------------------------------------- | ---------------------------------- |
| `events/`     | Los eventos                             | 90 días                                           | `SYPNIA_RETENTION_EVENTS_DAYS`     |
| `sessions/`   | Los eventos que pertenecen a una sesión | 90 días                                           | El mismo                           |
| `parquet/`    | Los eventos                             | 90 días                                           | El mismo                           |
| `replays/`    | Las sesiones grabadas, y cuánto duran   | 30 días                                           | `SYPNIA_RETENTION_REPLAYS_DAYS`    |
| `snapshots/`  | Las rutas de tu app, no el tráfico      | 90 días                                           | `SYPNIA_RETENTION_SNAPSHOTS_DAYS`  |
| `sourcemaps/` | Los despliegues                         | 90 días desde la última vez que se vio la versión | `SYPNIA_RETENTION_SOURCEMAPS_DAYS` |

Tres cosas que conviene saber como operador:

- **`events/` es la fuente de verdad.** Todo lo que hay en Postgres y viene de eventos se puede volver a construir desde ahí con `sypnia aggregate --from … --to …`. Nunca edites, muevas ni renombres sus objetos.
- **`replays/` es donde se va el espacio.** Las grabaciones son cerca de tres cuartas partes de un bucket típico.
- **`parquet/` es para ti.** El motor lo escribe y nunca lo lee. Apunta cualquier herramienta que lea Parquet a un día de eventos.

Si configuras `SYPNIA_STORAGE_PREFIX`, todo lo anterior queda bajo ese prefijo, así el bucket se puede compartir con otra cosa.

### Dónde está el bucket

| Despliegue                                                                                     | Dónde                                                                 |
| ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| [Plantilla de AWS](https://docs.sypnia.com/es/self-hosting/deploy-aws)                         | Un bucket de S3. Su nombre es la salida `BucketName` del stack.       |
| [Docker Compose](https://docs.sypnia.com/es/self-hosting/deploy-docker), tal como está escrito | El bucket `sypnia` dentro de MinIO, en el volumen de Docker `bucket`. |
| Tu propia elección                                                                             | Lo que digan `SYPNIA_STORAGE_BUCKET` y `SYPNIA_STORAGE_ENDPOINT`.     |

## Postgres

Postgres guarda lo que lee una pantalla o una llamada de MCP: los problemas, el índice de sesiones, los números por hora y por día, y quién entra. Los eventos crudos y el contenido de las grabaciones nunca entran ahí.

| Qué                                                                                                    | Crece con                              | Se guarda por defecto                      |
| ------------------------------------------------------------------------------------------------------ | -------------------------------------- | ------------------------------------------ |
| Proyectos, llaves, tokens, configuración, reglas de alerta, webhooks, comprobaciones de disponibilidad | Lo que tú creas                        | Mientras exista el proyecto                |
| Problemas, con su frase, estado y conteos diarios                                                      | Las fallas distintas, no el tráfico    | Mientras exista el proyecto                |
| El índice de sesiones: una fila por sesión                                                             | Las sesiones                           | 90 días (`SYPNIA_RETENTION_EVENTS_DAYS`)   |
| Números por hora y por día: rendimiento, mapas de clics, uso, disponibilidad                           | Rutas de tu app × horas, no el tráfico | 400 días (`SYPNIA_RETENTION_NUMBERS_DAYS`) |
| El índice de trazas                                                                                    | Las peticiones                         | 90 días                                    |
| El control de duplicados                                                                               | Los lotes de las últimas 48 horas      | 48 horas                                   |

Las tablas que crecen con el tiempo están particionadas por mes. El motor crea las particiones siguientes y elimina las viejas por su cuenta, en SQL simple. No necesita ninguna extensión, así que sirve cualquier Postgres administrado. No tienes que programar un vacuum ni un trabajo de limpieza.

| Despliegue                                             | Dónde                                                                        |
| ------------------------------------------------------ | ---------------------------------------------------------------------------- |
| Plantilla de AWS, con la base de datos creada por ella | Una instancia de RDS. Su nombre es la salida `DatabaseIdentifier` del stack. |
| Docker Compose, tal como está escrito                  | La base de datos `sypnia` en el servicio `db`, en el volumen de Docker `db`. |
| Tu propia elección                                     | Lo que diga `SYPNIA_DATABASE_URL`.                                           |

## Qué tan grande se pone

Son estimaciones. La primera cifra, cerca de 123 bytes por evento guardado, se midió en el sistema del que sale este motor; las cifras de grabaciones también se midieron ahí. La aritmética de cada fila está en [Almacenamiento](https://docs.sypnia.com/es/architecture/storage).

| Por millón de eventos                                         | Tamaño                                      |
| ------------------------------------------------------------- | ------------------------------------------- |
| `events/`, `sessions/` y `parquet/`, cerca de 125 MB cada una | ≈ 375 MB                                    |
| `replays/`, con el muestreo por defecto                       | ≈ 870 MB                                    |
| `snapshots/`                                                  | Unos pocos MB, sea cual sea el tráfico      |
| **Bucket**                                                    | **≈ 1,2 GB**                                |
| **Postgres**, filas que crecen con el tráfico                 | **≈ 20 MB**, más ≈ 30 MB que viven 48 horas |

Los source maps van aparte, porque crecen con los despliegues: medido en el sistema del que sale esto, un despliegue de una app grande son 965 mapas y 109 MB.

Qué significa eso cuando la retención ya se llenó, con los valores por defecto:

|                                             | Pequeño: 130.000 eventos al día | Mediano: 1,3 millones de eventos al día |
| ------------------------------------------- | ------------------------------- | --------------------------------------- |
| Eventos al mes                              | 4 millones                      | 40 millones                             |
| `events/`, `sessions/`, `parquet/`, 90 días | 375 MB × 4 × 3 ≈ 4,5 GB         | ≈ 45 GB                                 |
| `replays/`, 30 días                         | 870 MB × 4 ≈ 3,5 GB             | ≈ 35 GB                                 |
| **Bucket, sin source maps**                 | **≈ 8 GB**                      | **≈ 80 GB**                             |
| Índice de sesiones, 90 días                 | 10 MB × 4 × 3 ≈ 120 MB          | ≈ 1,2 GB                                |
| Números por hora, 400 días, para 100 rutas  | 3 MB al día × 400 ≈ 1,2 GB      | Lo mismo: no crecen con el tráfico      |
| **Postgres**                                | **≈ 1,5 GB**                    | **≈ 2,5 GB**                            |

Dos cosas pueden romper estos números, y las dos tienen tope: una sesión puede grabar como máximo 720 fragmentos, cerca de 144 MB, y una sesión envía como máximo 5 capturas de página.

## Mide lo tuyo

Las estimaciones dejan de importar cuando tienes una semana de datos reales.

**El bucket, por proyecto y por carpeta:**

**AWS**

```bash
aws s3 ls s3://<BucketName>/prj_5k2m9x4q7w1z/replays/ --recursive --summarize | tail -2
```

```text
Total Objects: 31204
   Total Size: 1065353216
```

**Docker**

```bash
docker compose run --rm --entrypoint sh bucket -c \
  'mc alias set local http://minio:9000 sypnia "$MINIO_PASSWORD" >/dev/null && mc du --depth 2 local/sypnia'
```

```text
1.0GiB	31204 objects	sypnia/prj_5k2m9x4q7w1z/replays
412MiB	9870 objects	sypnia/prj_5k2m9x4q7w1z/events
```

**Postgres, completo y por tabla:**

```sql
SELECT pg_size_pretty(pg_database_size(current_database()));

SELECT relname AS table, pg_size_pretty(pg_total_relation_size(relid)) AS size
FROM pg_catalog.pg_statio_user_tables
ORDER BY pg_total_relation_size(relid) DESC
LIMIT 10;
```

**Lo que guardó un proyecto este mes**, sin tocar los almacenes: `GET /v1/usage` devuelve sus eventos, grabaciones y análisis. Ver la [referencia de la API](https://docs.sypnia.com/es/api/projects-keys-and-tokens).

## Reglas en el bucket

El motor borra por su cuenta los datos vencidos, una vez al día, listando y borrando. Funciona igual en Amazon S3, Cloudflare R2 y MinIO, y es la única retención que necesitas. El bucket no necesita reglas de ciclo de vida para mantenerse pequeño.

| Regla                                                      | ¿Agregarla?                                                    | Por qué                                                                                                                                                                                                                                                                                                   |
| ---------------------------------------------------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Quitar las subidas multiparte sin terminar a los 7 días    | **Sí.** La plantilla de AWS la agrega.                         | Una subida de source maps que se cortó deja partes que ningún listado muestra y que se cobran.                                                                                                                                                                                                            |
| Bloquear todo acceso público                               | **Sí.** La plantilla de AWS lo hace.                           | Nada del bucket se lee jamás sin un enlace firmado.                                                                                                                                                                                                                                                       |
| Vencer todo el bucket a los N días                         | **No.**                                                        | Los source maps de una versión que sigue viva desaparecerían, y los stacks se volverían ilegibles. La retención por tipo de dato es trabajo del motor.                                                                                                                                                    |
| Vencer una carpeta de un proyecto, como segunda protección | Solo si quieres una protección contra un worker que se detuvo. | Una regla de ciclo de vida filtra por el inicio de la llave, y cada llave empieza por el id del proyecto, así que es una regla por proyecto y carpeta: `prj_…/replays/`, por ejemplo. Dale más días que el ajuste del motor, para que el motor siempre borre primero.                                     |
| Pasar objetos a una clase de almacenamiento más fría       | **No.**                                                        | La mayoría de los objetos pesa unos pocos kilobytes, menos del mínimo que cobran las clases frías, y el worker lee las horas recientes más de una vez. Además, una grabación tiene que abrir al instante.                                                                                                 |
| Versionado                                                 | **Apagado**, a menos que lo necesites.                         | Los archivos por sesión se vuelven a escribir en cada pasada, así que las versiones se acumulan. Peor: una [persona eliminada](https://docs.sypnia.com/es/privacy/deleting-data) sobreviviría en las versiones viejas. Si lo enciendes, agrega una regla que quite las versiones viejas a los pocos días. |
| Replicación a otra región                                  | Tú decides.                                                    | Duplica el costo de almacenamiento y de escritura. Un respaldo de la base de datos protege lo que no se puede reconstruir; ver [Actualizaciones, respaldos y retención](https://docs.sypnia.com/es/self-hosting/upgrades-backups-retention).                                                              |

Para guardar los datos menos tiempo, cambia los ajustes de retención, no el bucket: [Actualizaciones, respaldos y retención](https://docs.sypnia.com/es/self-hosting/upgrades-backups-retention#retenci%C3%B3n).

## Qué no hacer a mano

- **No borres objetos para liberar espacio.** Baja un ajuste de retención: el motor entonces borra juntos los objetos y las filas que apuntan a ellos. Un objeto borrado a mano deja en la lista una sesión que responde `410 expired` al abrirla.
- **No borres filas para eliminar a una persona o una sesión.** Usa la API, que elimina las filas y los objetos: [Eliminar datos](https://docs.sypnia.com/es/privacy/deleting-data).
- **No apuntes dos motores con bases de datos distintas al mismo bucket y prefijo.** Cada uno borraría lo que el otro no conoce. Usa `SYPNIA_STORAGE_PREFIX` para compartir un bucket.

## Pasar a otro bucket

Detén el motor, copia cada objeto con su llave sin cambios, cambia los ajustes de almacenamiento, arranca el motor y corre `sypnia doctor`. Postgres no necesita ningún cambio: guarda llaves, no direcciones. Los SDK reintentan mientras el motor está detenido, así que una detención corta no pierde nada; ver [qué pasa cuando una pieza se cae](https://docs.sypnia.com/es/architecture/data-flow).

## Relacionado
