Docs

Actualizaciones, respaldos y retención

Cómo actualizar un motor con alojamiento propio sin perder datos, qué respaldar y cómo restaurarlo, y cómo elegir cuánto tiempo se guarda cada tipo de dato.

Aplica a Motor Al lanzar

Ver como Markdown
En esta página
  1. Actualizaciones
  2. Qué puede cambiar una actualización
  3. Actualizar
  4. Lee qué cambió
  5. Respalda la base de datos
  6. Trae la imagen nueva y reinicia el motor
  7. Comprueba
  8. Volver atrás
  9. Respaldos
  10. Qué necesita uno
  11. Respaldar Postgres
  12. Restaurar
  13. Detén el motor
  14. Restaura el volcado
  15. Arranca el motor y comprueba
  16. Procesa otra vez lo que llegó después del respaldo
  17. Si se pierde el bucket
  18. Retención
  19. Cambiarla
  20. Cómo elegir
  21. Lo que la retención no cubre
  22. Relacionado

Motor Esta página es para quien mantiene corriendo un motor con alojamiento propio después del primer día. En Sypnia Cloud los tres trabajos son nuestros: nosotros actualizamos, nosotros respaldamos, y tu plan define la retención.

Actualizaciones

Qué puede cambiar una actualización

El motor está hecho para que una actualización dentro de la versión 1 sea aburrida. Estas reglas son parte de su contrato:

ReglaQué significa para ti
Las migraciones de la base de datos solo agregan.Un motor más viejo sigue funcionando contra un esquema más nuevo. Puedes migrar primero, reemplazar el motor después, y volver atrás sin tocar la base de datos.
La API dentro de /v1 solo agrega.Los scripts, la CLI, el servidor MCP y tu agente de código siguen funcionando.
Los eventos crudos conservan los campos que el motor no conoce.Un SDK más nuevo nunca rompe un motor más viejo. Actualiza el motor y tus apps en cualquier orden.
Una variable SYPNIA_… desconocida es una advertencia en sypnia doctor, no un error.Un ajuste que cambió de nombre o se quitó no detiene una actualización. El registro de cambios lo nombra.
El procesamiento se puede repetir sin riesgo.Un worker que muere a mitad de una actualización no pierde nada ni cuenta nada dos veces.

Un cambio que rompa alguna de estas sería la versión 2, anunciada en el registro de cambios, nunca una sorpresa dentro de la versión 1.

Qué versión corres: sypnia version, o el encabezado Sypnia-Version de cualquier respuesta de la API. La etiqueta de imagen ghcr.io/sypnia/sypnia:1 sigue la última publicación de la versión 1. Para decidir tú cuándo ocurre cada actualización, usa una etiqueta exacta como ghcr.io/sypnia/sypnia:1.0.0 y cámbiala a mano.

Actualizar

Al final tendrás: la versión nueva corriendo, los mismos datos, y un respaldo tomado justo antes.

AWS

Sigue Actualizar el motor en la página de AWS: lee el registro de cambios, actualiza el comando y la plantilla, corre sypnia migrate, despliega. Antes, toma una instantánea de la base de datos:

Terminal
aws rds create-db-snapshot \
  --db-instance-identifier <DatabaseIdentifier> \
  --db-snapshot-identifier sypnia-before-upgrade-$(date +%F)

La ingesta no se detiene: las funciones viejas responden hasta que las nuevas están listas.

Volver atrás

Arranca otra vez la versión anterior: la etiqueta de imagen anterior, o la plantilla anterior. Deja la base de datos como está. El motor más viejo funciona contra el esquema más nuevo, y lo que llegó entre tanto se conserva.

No restaures un respaldo de la base de datos para deshacer una actualización. Una restauración es para una base de datos perdida o dañada, y descarta todo lo que las personas hicieron desde el respaldo.

Respaldos

Qué necesita uno

DatosDónde¿Se puede reconstruir?¿Respaldarlo?
Proyectos, llaves de ingesta, tokens de API, configuración de proyectos, reglas de alerta, webhooks, comprobaciones de disponibilidadPostgresNoSí
Lo que hicieron las personas: problemas resueltos o ignorados, notas, alertas reconocidasPostgresNoSí
Los análisis del agentePostgresSolo corriendo el agente otra vez, lo que cuesta llamadas al modeloSí
Los conteos de los problemas, el índice de sesiones, los números de rendimiento, el índice de trazasPostgresSí, desde events/ en el bucket, mientras los eventos se conservenViene con el mismo respaldo
Eventos crudos, archivos por sesión, grabaciones, capturas de páginaBucketNo. Son la fuenteTú decides, ver abajo
Source mapsBucketSí: tu CI los vuelve a subir en la próxima compilaciónNo
La configuración del motor y el token raízTu archivo .env, o los parámetros del stackNoSí, en un gestor de contraseñas o un almacén de secretos

Así que la regla es corta: respalda Postgres todos los días, y guarda la configuración en un lugar seguro. Un respaldo de la base de datos es pequeño, porque los eventos crudos nunca están ahí.

El bucket es otra decisión. Un almacenamiento alojado, como Amazon S3 o Cloudflare R2, ya guarda varias copias de cada objeto; la mayoría se queda ahí. Un MinIO en un solo disco, como en el archivo de Compose, es un solo disco: si muere, los eventos crudos y las grabaciones se pierden, y Sypnia conserva solo lo que tiene Postgres. Si eso te importa, copia el bucket a otro lugar con una programación, o usa un almacenamiento alojado.

Respaldar Postgres

AWS

AWS respalda todos los días la base de datos que crea la plantilla, y cada respaldo se guarda 7 días. También puedes volver a cualquier minuto de esos 7 días. No hay nada que configurar. Para comprobarlo:

Terminal
aws rds describe-db-instances --db-instance-identifier <DatabaseIdentifier> \
  --query "DBInstances[0].[BackupRetentionPeriod,LatestRestorableTime]"
Deberías ver
7 y una hora de hace pocos minutos.

Si trajiste tu propio Postgres, sus respaldos son de tu proveedor o tuyos.

Restaurar

Al final tendrás: la base de datos como estaba en el respaldo, más todo lo que se puede reconstruir a partir de los eventos que llegaron desde entonces.

  1. Detén el motor

    Terminal
    docker compose stop sypnia

    Los SDK siguen reintentando un rato corto; lo que no pueden retener se pierde. Una restauración no es una operación de rutina.

  2. Restaura el volcado

    Terminal
    docker compose exec -T db pg_restore -U sypnia -d sypnia --clean --if-exists < backups/sypnia-2026-03-12.dump
    Deberías ver
    Sin errores. En AWS, restaura la instantánea o el punto en el tiempo a una instancia nueva, y dale su dirección al stack como DatabaseUrl.
  3. Arranca el motor y comprueba

    Terminal
    docker compose start sypnia
    docker compose exec sypnia sypnia doctor --skip ai
    Deberías ver
    all checks passed. Si el respaldo es más viejo que el motor, el motor lo migra al arrancar.
  4. Procesa otra vez lo que llegó después del respaldo

    El bucket todavía tiene todos los eventos. Dile al worker que los lea otra vez desde la hora del respaldo:

    Terminal
    docker compose exec sypnia sypnia aggregate --from 2026-03-12T03:00:00Z
    Deberías ver
    Text
    shop  events 48211 -> 361 sessions, 4 problems (1 new), 22 routes   9.4 s
    done in 11.0 s, data through 2026-03-12T16:20:05Z

    Lista el bucket para ese rango, así que también encuentra eventos de los que la base de datos restaurada nunca supo. Correrlo dos veces no hace daño.

Lo que una restauración no puede traer de vuelta es lo que las personas escribieron después del respaldo:

  • Un problema resuelto o ignorado desde entonces vuelve a estar abierto.
  • Las llaves de ingesta y los tokens de API creados desde entonces ya no existen. Las apps que los usan son rechazadas: créalos otra vez y despliega.
  • Un problema visto por primera vez desde entonces es nuevo otra vez, así que vuelve a alertar, y tu webhook lo recibe una segunda vez.
  • Los análisis escritos desde entonces se corren otra vez cuando su problema crece, o cuando lo pides.

Prueba una restauración una vez, sobre una copia, antes del día en que la necesites.

Si se pierde el bucket

Postgres todavía tiene cada problema, su frase y sus conteos, y todos los números. Las sesiones siguen en la lista y responden 410 expired al abrirlas, porque sus archivos ya no están. Apunta el motor a un bucket nuevo y vacío, corre sypnia doctor, y los datos nuevos fluyen. Los source maps vuelven con tu próxima compilación.

Retención

El motor borra por su cuenta los datos viejos, una vez al día. Tú eliges el número de días para cada tipo; el bucket no necesita ninguna regla para eso.

DatosPor defectoAjuste
Eventos crudos, sesiones con sus líneas de tiempo, trazas, los archivos Parquet diarios90 díasSYPNIA_RETENTION_EVENTS_DAYS (1 a 3650)
Grabaciones30 díasSYPNIA_RETENTION_REPLAYS_DAYS (no más que los eventos)
Capturas de página90 díasSYPNIA_RETENTION_SNAPSHOTS_DAYS
Números por hora y por día: rendimiento, mapas de clics, uso, disponibilidad400 díasSYPNIA_RETENTION_NUMBERS_DAYS
Source maps90 días desde la última vez que se vio la versiónSYPNIA_RETENTION_SOURCEMAPS_DAYS
Problemas: la frase, el análisis, el estado, los conteos diarios y un ejemploMientras exista el proyectoNinguno
Proyectos, llaves, tokens, configuraciónHasta que los eliminesNinguno

Cómo funciona:

  • La edad de una sesión se cuenta desde su último evento. Los datos se borran dentro de las 24 horas siguientes a pasar su edad.
  • Los ajustes son para todo el motor. Un motor con alojamiento propio no tiene retención por proyecto; GET /v1/usage devuelve la retención que aplica.
  • Un problema vive más que las sesiones que afectó. Eso es lo que le permite a Sypnia decir «volvió» meses después. Sus sesiones, grabaciones y trazas enlazadas vencen cada una a su tiempo.
  • Después de eso, pedir datos vencidos responde 410 expired, no un resultado vacío.

Cambiarla

Pon la variable y reinicia el motor. En AWS, agrega la línea a la plantilla como en Cambiar un ajuste.

Terminal
SYPNIA_RETENTION_EVENTS_DAYS=30
SYPNIA_RETENTION_REPLAYS_DAYS=14
  • Más corta: todo lo que sea más viejo que el número nuevo se borra en la siguiente limpieza diaria. No se puede deshacer, salvo desde un respaldo.
  • Más larga: los datos se guardan más tiempo de ahora en adelante. Lo que ya se borró no vuelve.

Para correr la limpieza ahora en vez de esperar la diaria:

Terminal
sypnia aggregate --task retention

Cómo elegir

  • Las grabaciones son lo que más espacio cuesta y lo que más rápido envejece: una grabación sirve mientras el problema está fresco. De 14 a 30 días le alcanza a la mayoría de los equipos. Ver Estructura del almacenamiento.
  • Los eventos son lo que te permite reconstruir la base de datos y abrir la línea de tiempo de una sesión vieja. Guárdalos al menos tanto como tu respaldo más viejo de la base de datos.
  • Los números son pequeños y no guardan nada sobre personas. Guardarlos un año te deja comparar este mes con el mismo mes del año pasado.
  • Datos personales. Las grabaciones, las sesiones y los nombres que tu app envió con identify() son datos personales. Guárdalos solo el tiempo que puedas justificar. Para eliminar antes a una persona o una sesión, ver Eliminar datos.

Lo que la retención no cubre

  • Tus respaldos. Un volcado de la base de datos conserva lo que se borró después, hasta que el volcado mismo se borra. No guardes respaldos por más tiempo del que deben vivir los datos que contienen.
  • Los logs. El motor escribe logs en la salida estándar y nunca registra cuerpos, llaves ni tokens. Cuánto se guardan depende de quien los recoja: Docker, CloudWatch (30 días en la plantilla de AWS), tu propio recolector. Los logs del proxy que está delante del motor guardan direcciones IP.
  • Las versiones del bucket. Si encendiste el versionado, las versiones viejas sobreviven a los borrados del motor hasta que una regla tuya las quite.

Relacionado

Secciones

Empieza aquíQué es Sypnia, cómo funciona, qué es código abierto y qué es la nube de pago, y las dos maneras de recibir tu primer problema en palabras claras.ConceptosLas diez ideas de las que está hecho Sypnia, cada una definida con precisión, desde un proyecto y sus llaves hasta los problemas, las trazas y las alertas.SDKCómo envía tu app los datos a Sypnia. Un SDK para el navegador, uno para Node, uno para Next.js, y la entrada de OpenTelemetry para cualquier otro backend.El agenteCómo analiza Sypnia un problema, qué escribe, qué le envía a un modelo y qué nunca hace.MCP y skillsConecta tu agente de código a Sypnia para que pregunte qué está fallando en producción, lea lo que necesita para arreglarlo y configure Sypnia por ti.Referencia de la APILa API HTTP de Sypnia: una sola API para el motor de código abierto y para Sypnia Cloud, con cada endpoint, parámetro, respuesta y error.Referencia de la CLIEl comando sypnia: cómo instalarlo, qué variables lee, qué significan sus códigos de salida y dónde está documentado cada comando.Alojamiento propioQué corres cuando alojas tú mismo el motor de Sypnia, qué necesitas, cuánto cuesta y qué no tienes frente a Sypnia Cloud.Cómo está construido el motorTodo el motor de Sypnia en una página, desde un clic en tu app hasta la frase que lee tu agente de código, con las reglas de diseño y el código que las sostiene.Sypnia CloudCómo funciona el servicio pago, desde las organizaciones y los roles hasta los planes, los límites, la facturación, dónde viven tus datos, la GitHub App y el soporte.Privacidad y seguridadQué recoge Sypnia de tu app y de sus usuarios, qué no recoge nunca, cómo funciona el enmascarado, cómo eliminar datos y cómo se protege el servicio.LicenciasQué licencia cubre cada parte de Sypnia, qué puedes hacer con ella, cómo se puede usar el nombre, y los términos de una contribución.GuíasRecetas paso a paso para las formas comunes de usar Sypnia, desde apps hechas con constructores de IA y Next.js en Vercel hasta Supabase, source maps en CI, correos de alerta desde tu propio motor, y venir desde Sentry.ReferenciaLas páginas donde se consulta, desde el esquema de eventos y el glosario hasta lo planeado, el registro de cambios y las preguntas frecuentes.
↑↓ para moverte↵ para abrirEsc para cerrar