Este runbook cubre las tareas operativas recurrentes de la plataforma de
monitoreo. Cada tarea empareja el disparador funcional (“cuándo necesito esto”)
con los comandos exactos a ejecutar. Ninguna tarea aquí imprime ni almacena valores
de secretos.
Sincronizar variables de entorno
Las variables de entorno viven en 1Password Environments (una por entorno) y fluyen a dos destinos: archivos locales.env.<env> para el
desarrollo, y Vercel para las apps desplegadas.
1Password → archivos locales
Ejecuta
pnpm env:sync para reflejar cada 1Password Environment en el archivo
.env.<environment> de cada app. Sin argumentos sincroniza todas las apps y todos
los entornos; los entornos a los que tu token no puede acceder se omiten con una
advertencia en lugar de fallar.1Password → Vercel
Ejecuta el workflow Sync Env (
workflow_dispatch) para enviar un 1Password
Environment a Vercel, luego vuelve a desplegar horizon-api para que los nuevos valores
surtan efecto.Agregar o cambiar un monitor
El monitoreo es código — nunca click-ops en la UI de Better Stack.1
Edita la definición
Cambia el módulo bajo
infra/betterstack/modules/ o el manifiesto de estado deseado
adopted/<env>.json del entorno.2
Abre un PR
El carril de validación se ejecuta automáticamente (
fmt, validate, verificaciones JSON).
Consulta CI/CD para el monitoreo.3
Plan
Lanza el workflow con
action = plan para el entorno objetivo y
lee el diff. Localmente: pnpm tf:betterstack:plan.4
Apply
Lanza con
action = apply y escribe APPLY, o ejecuta
./scripts/status-monitoring/terraform-apply.sh apply <env> localmente. Confirma
que un plan de seguimiento no muestra cambios.Rotar HEALTH_MONITOR_TOKEN
El health token autentica a los monitores de Better Stack contra los endpoints de
componentes. Rótalo si pudiera haberse filtrado, o de forma programada. El orden
importa para evitar un hueco de monitoreo.
1
Genera un nuevo token
openssl rand -hex 32.2
Guárdalo en el vault
Actualiza
HEALTH_MONITOR_TOKEN en el 1Password Environment del entorno.3
Propaga al runtime
Ejecuta el workflow Sync Env, luego vuelve a desplegar
horizon-api para que los endpoints
acepten el nuevo token. Los endpoints fallan cerrados, así que el antiguo y el nuevo no deben
estar vivos a la vez por mucho tiempo.4
Actualiza los monitores
Ejecuta
terraform apply <env> para que Better Stack envíe el nuevo x-health-token
en cada monitor (el token alimenta TF_VAR_health_monitor_token).5
Verifica
Haz un smoke-test de los endpoints (abajo); todos deberían devolver
200.Regenerar los recursos de la página de estado tras un apply
BETTERSTACK_STATUS_PAGE_RESOURCES mapea cada scope de componente a su id de recurso
de la página de estado, que la sincronización de degradado usa para abrir/cerrar Status Reports. Después de un
apply que crea o cambia recursos, regenéralo:
BETTERSTACK_STATUS_PAGE_RESOURCES del entorno
en 1Password, luego ejecuta Sync Env y vuelve a desplegar. Terraform también expone
esto como el output status_page_resources_json.
Detectar y resolver drift
El drift es cualquier diferencia entre la config commiteada y el estado en vivo de Better Stack (usualmente por un cambio manual en la UI).1
Detecta
Ejecuta un
plan. Un resultado 0 to add, 0 to change, 0 to destroy significa que no hay drift.
Cualquier línea ~/+/- es drift.2
Decide la dirección
El código gana (la norma):
apply para empujar la config commiteada sobre el
cambio manual. Adopta el cambio: actualiza el .tf/manifiesto para que coincida con
la realidad, luego confirma que el plan está limpio.3
Audita los manifiestos (opcional)
Regenera y revisa el diff antes de hacer commit:
Simular degradado en development
Para ejercitar la ruta amarilla sin un incidente real:Smoke-test de los endpoints
HEALTH_MONITOR_TOKEN desde backend/horizon-api/.env.development y
verifica todos los endpoints de pull por componente. Sobrescribe el host o el token en línea:
Referencia de variables de entorno
Solo nombres — nunca commitees ni pegues valores.Código relacionado
- Runbook operativo:
docs/initiatives/betterstack/02-betterstack-runbook.md - Operaciones de la página de estado:
docs/operations/status-page.md - Script de sincronización de env:
scripts/env/sync-local.mjs