Conceptos básicos de incidentes

8 ejemplos para empezar con la respuesta a incidentes de Postgres: 5 básicos y 3 intermedios.

Prerrequisitos

# Confirma que puedes acceder al primario y tienes un rol de solo lectura para la clasificación
psql "$DATABASE_URL" -c "SELECT version();"
psql "$DATABASE_URL" -c "SELECT pg_is_in_recovery();"

• Acceso a pg_stat_activity, pg_locks y vistas de replicación.
• Una rotación de guardia con una ruta de escalada documentada.
• Runbooks almacenados en git, no en una wiki que nadie lee durante las interrupciones.

Ejemplos básicos

1. Clasificación de severidad

Mapea el impacto del usuario a un nivel de severidad antes de cambiar la producción.

• Sev-1 incluye la retención de WAL de la ranura de replicación llenando el disco en el primario.
• Sev-2 incluye el agotamiento del pool de conexiones que causa 503.
• Reclasifica cuando los hechos cambian; no fijes la severidad con el primer mensaje del paginador.

Relacionado: Mejores prácticas de respuesta a incidentes - higiene de runbooks

2. Lista de verificación de los primeros 15 minutos

Ejecuta esta secuencia antes del diagnóstico profundo.

-- 1. ¿Está la instancia aceptando conexiones?
SELECT now() AS ts, pg_is_in_recovery() AS is_replica;
 
-- 2. ¿Quién está conectado y en qué está esperando?
SELECT pid, usename, application_name, state, wait_event_type, wait_event,
       now() - query_start AS query_age, left(query, 120) AS query_snip
FROM pg_stat_activity
WHERE pid <> pg_backend_pid()
ORDER BY query_start NULLS LAST
LIMIT 30;
 
-- 3. ¿Sesiones bloqueadas?
SELECT blocked.pid AS blocked_pid, blocking.pid AS blocking_pid,
       left(blocked.query, 80) AS blocked_q
FROM pg_stat_activity blocked
JOIN pg_stat_activity blocking ON blocking.pid = ANY(pg_blocking_pids(blocked.pid))
WHERE cardinality(pg_blocking_pids(blocked.pid)) > 0;

• Publica el estado en el canal de incidentes cada 15 minutos durante Sev-1/2.
• Asigna roles: Comandante del Incidente, Comunicaciones, Líder Técnico, Escriba.
• Captura marcas de tiempo para cada acción; las necesitarás para el post-mortem.

3. Plantilla de comunicación

Mantén informados a los interesados sin filtrar texto de consulta sensible.

[INC-1234] Sev-2 - Latencia elevada de la API en el servicio de checkout
Estado: Investigando
Impacto: ~15% de las solicitudes de checkout caducan después de 30s
Inicio: 2026-07-09 14:22 UTC
Acciones: Verificando saturación del pool de conexiones y esperas de bloqueo en el primario
Próxima actualización: 14:37 UTC

• Enlaza a la página de estado si tienes una.
• No pegues contraseñas de producción, PII o salida completa de EXPLAIN en canales públicos.
• Informa al producto cuándo esperas la próxima actualización, incluso si la respuesta es "todavía investigando".

4. Rol seguro de clasificación de solo lectura

Crea un rol que pueda diagnosticar sin mutar datos.

CREATE ROLE incident_reader LOGIN PASSWORD 'rotate-after-incident';
GRANT pg_read_all_stats TO incident_reader;
GRANT CONNECT ON DATABASE app TO incident_reader;
GRANT USAGE ON SCHEMA public TO incident_reader;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO incident_reader;
ALTER DEFAULT PRIVILEGES IN SCHEMA public
  GRANT SELECT ON TABLES TO incident_reader;

• Rota las credenciales después de que el incidente se cierre.
• Prefiere réplicas de lectura para consultas de diagnóstico pesadas durante picos de carga.
• Nunca otorgues SUPERUSER a las cuentas de guardia "solo para el incidente".

5. Cuándo realizar un failover

El failover es una decisión de negocio, no solo técnica.

# Ejemplo de Patroni: verifica el estado del clúster antes del failover manual
patronictl -c /etc/patroni/patroni.yml list

• Realiza failover cuando el primario no sea recuperable o se confirme corrupción en el primario.
• No realices failover solo por consultas lentas; arregla la consulta o mata los bloqueadores primero.
• Espera breves errores de conexión durante el corte de DNS o proxy; advierte a los equipos de aplicaciones.

Relacionado: Emergencia de latencia de replicación - diagnóstico de latencia antes de la reconstrucción

Ejemplos intermedios

6. Captura de la línea de tiempo del incidente

Las notas estructuradas hacen que los post-mortems sean rápidos.

mkdir -p incidents/INC-1234
cat >> incidents/INC-1234/timeline.md <<'EOF'
| Hora (UTC) | Actor | Acción |
|------------|-------|--------|
| 14:22 | pager | Sev-2 abierto, latencia de checkout |
| 14:25 | dba | pg_stat_activity muestra 200 idle in transaction |
EOF

• Almacena artefactos en git: consultas ejecutadas, salida de EXPLAIN, diferencias de configuración.
• Redacta datos del cliente antes de confirmar.
• Vincula la línea de tiempo con el ticket de Jira/Linear.

7. Terminación coordinada de backends

Termina solo con política y registro.

-- Encuentra sesiones idle in transaction largas (causa raíz común de incidentes)
SELECT pid, usename, application_name, state,
       now() - xact_start AS xact_age, query
FROM pg_stat_activity
WHERE state = 'idle in transaction'
  AND now() - xact_start > interval '5 minutes';
 
-- Termina un backend (requiere rol apropiado)
SELECT pg_terminate_backend(12345);

• Requiere aprobación de dos personas para pg_terminate_backend en Sev-1 a menos que sea un runbook automatizado.
• Registra pid, application_name y el ID del ticket en el canal de incidentes.
• Después de la terminación masiva, observa las tormentas de conexión a través de PgBouncer.

8. Transferencia a Post-Mortem

Cierra el ciclo del incidente con seguimientos accionables.

## Post-Mortem Requerido (Sev-1/2)
- Causa raíz (5 Porqués)
- Tiempo de detección / tiempo de mitigación
- Qué salió bien
- Elementos de acción con responsables y fechas de vencimiento
- Actualizaciones de runbooks fusionadas a main

• Programa el post-mortem dentro de los cinco días hábiles.
• Cultura sin culpables: enfócate en sistemas y procesos, no en individuos.
• Cada elemento de acción necesita un responsable; "equipo" no es un responsable.

Relacionado: Diagnóstico de tormentas de bloqueo - cuándo la terminación es la mitigación

Versiones de la pila: Esta página fue escrita para PostgreSQL 18.4 (estable 18, mantenimiento 17), pgvector 0.8+, PgBouncer 1.x, Patroni 3.x y PostGIS 3.5+.