Registros, métricas y avisos

Esta guía cubre cómo seguir lo que hace un servicio: sus registros, sus métricas, las últimas peticiones que le llegan, los errores que repite (incidencias, y el autofix que puede arreglarlos), los monitores y las alertas, los avisos por correo, los avisos por webhook a Slack, Discord o tu propio servidor y los avisos en el escritorio.

Registros

Todo lo que produce un despliegue queda en cuatro flujos:

Cada línea queda además asociada a la etapa del pipeline en la que se escribió, que es como la página del commit enseña lo que imprimió cada paso. La pestaña Logs filtra por nivel y por flujo; el nivel se lee del texto, también cuando viene coloreado.

fundaia logs tienda api -f                     # en vivo
fundaia logs tienda api -n 500 --stream build  # las últimas 500 de la construcción
fundaia logs tienda api --step health          # solo la comprobación de salud
fundaia logs tienda api --deployment 41 -t     # otro despliegue, con la hora de cada línea
fundaia logs tienda api --trace 4bf92f35…      # solo una petición, por su id de traza

• Color. La interfaz interpreta las secuencias ANSI de podman build, Maven, npm o tu aplicación; al texto que llega sin color le resalta niveles, horas, rutas y códigos de estado. La terminal deja los escapes tal cual.
• Trazas. Si una línea lleva un identificador de traza (traceparent, trace_id=, un traceId en JSON…), se guarda y se puede filtrar por él.
• Secretos. El valor de un secreto que aparezca en una línea se tacha antes de guardarla.
• Cuánto duran. La salida del contenedor se guarda 30 días; el registro de cada despliegue, 90.

Métricas

La plataforma mide cada servicio en marcha cada quince segundos: CPU, memoria usada frente a la concedida y red. La pasarela cuenta además las respuestas por código de estado y la latencia (p50, p95, p99) de todo lo que pasa por ella; el tráfico entre servicios del proyecto no se ve.

La pestaña Métricas dibuja la última hora, 6 horas, 24 horas o 7 días.

fundaia metrics tienda api                  # la última hora
fundaia metrics tienda api --minutes 10080  # la última semana

Las medidas se conservan al detalle unas 48 horas, y después se agrupan en una por cada cinco minutos (CPU en media, memoria en pico) hasta cumplir 35 días.

Peticiones

La pestaña Peticiones de un servicio con dirección pública enseña, en vivo, lo que la pasarela ha contestado: la hora, el método, la ruta, el estado (en verde, azul, ámbar o rojo según sea 2xx, 3xx, 4xx o 5xx), cuánto tardó, la dirección del cliente y su navegador. Una marca dice si la respondió la caché, si hubo que despertar el servicio, si era un WebSocket o si la rechazó la propia pasarela (por la lista de direcciones IP, el límite de peticiones, el mantenimiento o la contraseña; ver Dominios), o si la contestó ella sola: una redirección, un preflight de CORS o una ruta rota (ver Reglas de la pasarela). Una petición que una ruta manda a otro servicio aparece en las peticiones de ese servicio, con la ruta que escribió el visitante. Encima, el total, la mediana (p50), el p95 y el porcentaje de 5xx de lo que se ve, que siguen a los filtros: clase de estado, método y un trozo de la ruta.

• De la consulta se guardan los nombres, nunca los valores: /buscar?q=zapatos&token=abc queda como /buscar?q=…&token=…, para que un token en una URL no acabe en ninguna pantalla.
• Son las últimas 500 por servicio y viven en memoria: no se escriben en la base de datos, así que no cuestan nada al servicio y un reinicio de la plataforma las olvida. Para el histórico están las métricas.
• Las llamadas entre servicios del proyecto no pasan por la pasarela y no aparecen.

fundaia requests tienda api                    # las 50 más recientes y el resumen
fundaia requests tienda api --status 5xx -n 200
fundaia requests tienda api --path /api --method POST
fundaia requests tienda api -f                 # en vivo; con --json, un objeto por línea

Con MCP, list_requests devuelve lo mismo, con los mismos filtros.

Incidencias y autofix

La plataforma lee los errores y avisos que imprime un contenedor mientras sirve, y agrupa los que tienen la misma forma (con ids, números y horas quitados): mil repeticiones son una incidencia con un contador. Están en la pestaña Incidencias del servicio y en la página de cada commit.

fundaia incidents tienda api
fundaia incident <id> resolved     # o ignored, u open

Una incidencia resuelta que vuelve a pasar se reabre; una ignorada no vuelve a molestar.

El autofix encarga a un componente Claude Code que la arregle. Está apagado por defecto y se configura por servicio:

fundaia autofix tienda api --mode pullRequest --agent <id-del-componente>
fundaia fix <id-de-la-incidencia>      # pedirlo ahora

Pulsar Arreglar con Claude (o fundaia fix) funciona aunque el modo esté en off, y si el proyecto tiene un solo componente Claude Code no hace falta elegirlo. Los despliegues fallidos y las vulnerabilidades se arreglan igual: ver Arreglos con Claude Code.

El agente primero intenta reproducir el fallo; si no puede, se detiene sin tocar nada. Por defecto actúa a partir de 5 repeticiones, como mucho 3 veces al día por servicio y con un techo de coste por intento; se paga con el crédito del agente y necesita que el servicio venga de GitHub con la GitHub App instalada.

Monitores

Un monitor pide una dirección cada cierto tiempo y mira la respuesta. Se crean en Alertas, el botón de la barra de cada proyecto, con fundaia monitors add o con la herramienta create_monitor.

• Cada cuánto: entre 30 segundos y 10 minutos (cada minuto por defecto), con una espera máxima más corta que eso (10 segundos por defecto).
• Qué cuenta como bien: los códigos que digas (200, 2xx, 200-299 o varios separados por comas; 2xx,3xx por defecto) y, si quieres, un texto que tiene que aparecer en la respuesta. Una redirección no se sigue.
• Caído tras N fallos seguidos (3 por defecto). Entonces se avisa por correo (la preferencia Monitores), a los webhooks del proyecto (monitor-down), en el historial y en el escritorio; y lo mismo cuando vuelve a responder (monitor-up). Un monitor nuevo empieza Comprobando y su primera respuesta buena no se anuncia.
• Un servicio dormido no se despierta: el monitor no lo comprueba, se ve como Durmiendo y ese tiempo no cuenta ni a favor ni en contra. Si quieres que lo despierte para comprobarlo, márcalo (--wake); entonces cada comprobación lo despierta. Las peticiones de un monitor nunca cuentan como visita: no impiden que el servicio se duerma.
• Historia: cada comprobación se suma a un tramo de cinco minutos, que se guarda 30 días. De ahí salen la disponibilidad de 24 horas, 7 días y 30 días y la línea con el tiempo de respuesta medio de cada media hora del último día.
• En pausa se deja de comprobar sin perder la historia; al reanudarlo empieza de nuevo en Comprobando, igual que al cambiar lo que comprueba.

fundaia monitors add tienda api --path /health --every 30s
fundaia monitors add tienda worker --path /ready --internal --expect 200 --keyword ok
fundaia monitors add tienda --url https://status.proveedor.com/api --every 5m
fundaia monitors list tienda
fundaia monitors show tienda 'api /health'
fundaia monitors pause tienda 'api /health'
fundaia monitors rm tienda 'api /health' --confirm 'api /health'

Monitores de cron

Un monitor de cron (heartbeat) no pregunta: espera a que le avisen. Es para lo que no tiene una dirección que comprobar: la copia nocturna, un cron de tu servidor, un job de GitHub Actions o un worker que procesa una cola. Tu trabajo hace una petición a una dirección secreta cuando termina; si el aviso no llega a tiempo, o llega diciendo que ha fallado, el monitor cae y se avisa igual que con cualquier otro monitor (correo, webhooks monitor-down y monitor-up, historial y escritorio).

Se crean en Alertas → Añadir monitor → Un cron o un worker, con fundaia monitors add --heartbeat o con create_monitor y kind: heartbeat.

• Cuándo debería avisar: cada cierto tiempo (de un minuto a 30 días, --every 5m) o según una expresión cron en una zona horaria (--cron "0 3 * * *" --zone Europe/Madrid; Europe/Madrid por defecto), que sigue sola el cambio de hora.
• El margen (--grace, diez minutos por defecto, de un minuto a siete días) es cuánto puede retrasarse el aviso antes de darlo por caído. Ponlo algo por encima de lo que tarda tu trabajo: con 0 3 * * * y 30 minutos de margen, si a las 03:30 no ha llegado nada, se avisa.
• Un monitor nuevo empieza Comprobando; su primer aviso no se anuncia, pero si nunca llega, se avisa de que ha caído: el trabajo no llegó a ejecutarse.

• **El cuerpo de un POST** (hasta 1 KB, sin caracteres de control) se guarda como mensaje: las últimas líneas de un log o «1,2 GB copiados». El de un fallo es el motivo del aviso.
• La dirección es un secreto: quien la tenga puede decir que todo va bien. Se guarda solo su huella (sha256), como un deploy hook, y se enseña una vez, al crearla. Si la pierdes, Nueva dirección (o fundaia monitors rotate) da otra y la anterior deja de funcionar. Ninguna herramienta MCP la enseña. Una dirección que no existe contesta 404, igual que una que existió.
• Contesta rápido y no se deja inundar: 200 OK en cuanto se guarda; más de doce avisos por minuto a la misma dirección reciben 429 con Retry-After, igual que una dirección que prueba tokens al azar. Cada aviso es una fila pequeña: se guardan los últimos 200 de cada monitor durante 30 días.
• Historial: cada aviso con su tipo (Correcto, Empezó, Falló, No llegó), cuánto tardó la ejecución y su mensaje. La línea de 24 horas dibuja la duración de cada ejecución y la disponibilidad cuenta los avisos buenos frente a los fallos y los retrasos.
• Tus tareas programadas se pueden vigilar sin URL: la campana de cada tarea (o --task <id>) crea un monitor que toma su cron y que la propia tarea avisa al empezar, al terminar y al fallar.

fundaia monitors add tienda --heartbeat --name "Copia nocturna" --cron "0 3 * * *" --zone Europe/Madrid --grace 30m
fundaia monitors add tienda --heartbeat --name "Worker de correos" --every 5m --grace 2m
fundaia monitors rotate tienda "Copia nocturna"

# crontab: avisa solo si la copia termina bien
0 3 * * * /usr/local/bin/copia.sh && curl -fsS -m 10 --retry 5 -o /dev/null https://infrastructure.fundaia.com/api/infra/ping/fhb_…

# con el código de salida: 0 va bien, cualquier otro cae al momento
/usr/local/bin/copia.sh; curl -fsS -m 10 --retry 5 -o /dev/null https://infrastructure.fundaia.com/api/infra/ping/fhb_…/$?

# GitHub Actions: al final del job, haya ido bien o mal
      - name: Avisar a Fundaia
        if: always()
        run: curl -fsS -m 10 --retry 5 -o /dev/null ${{ secrets.FUNDAIA_PING }}/${{ job.status == 'success' && 'ok' || 'fail' }}

Alertas de logs

Una alerta de logs vigila lo que imprime un servicio mientras sirve (el flujo runtime) y se dispara cuando un patrón aparece N veces en M minutos (5 veces en 5 minutos por defecto). El patrón es un texto, sin distinguir mayúsculas, o una expresión regular; una expresión que no compila, o una que repite un grupo que ya se repite (como (a+)+, que puede tardar segundos por línea), se rechaza al guardarla. Solo se miran los primeros 2000 caracteres de cada línea.

• Se evalúa al escribir las líneas, en memoria: no cuesta ninguna consulta por línea.
• Se dispara una vez y sigue disparada mientras sigan llegando coincidencias; se da por resuelta cuando pasa una ventana entera sin ninguna. Después espera (30 minutos por defecto) antes de poder dispararse otra vez.
• Al dispararse y al resolverse avisa por correo (Alertas de logs), a los webhooks (log-alert, log-alert-resolved), en el historial y en el escritorio.

fundaia alerts add tienda api --logs ERROR --count 5 --minutes 5
fundaia alerts add tienda api --logs 'timeout after \d+ ms' --regex --count 3

Alertas de errores 5xx y de latencia

La pasarela ya ve cada petición pública; con eso, en memoria y sin escribir nada por petición, se calculan para los últimos cinco minutos el porcentaje de respuestas 5xx y el p95 del tiempo de respuesta.

• Errores: se dispara cuando más del X % de las respuestas fueron 5xx (5 % por defecto).
• Latencia: se dispara cuando el p95 pasa de N milisegundos (1000 por defecto).
• Con un mínimo de peticiones (20 por defecto): tres peticiones no son una tendencia. Lo que responde la propia pasarela (una página de mantenimiento, una IP fuera de la lista, el límite de peticiones o la contraseña) no cuenta.
• Se comprueban cada 30 segundos, se resuelven cuando la ventana vuelve a estar por debajo y avisan por correo (Errores y latencia), a los webhooks (error-rate-high, error-rate-resolved, latency-high, latency-resolved), en el historial y en el escritorio.
• El p95 sale de un histograma con escalones de un 10 %: es una estimación por arriba, nunca por debajo.

fundaia alerts add tienda api --error-rate 5 --min-requests 50
fundaia alerts add tienda api --latency 800
fundaia alerts list tienda
fundaia alerts edit tienda 'Latencia de api' --threshold 1200
fundaia alerts rm tienda 'Latencia de api' --confirm 'Latencia de api'

Con MCP: list_monitors, read_monitor, create_monitor, update_monitor, delete_monitor, list_alerts, create_alert, update_alert y delete_alert. Borrar pide el nombre en confirm.

Avisos por correo

La plataforma escribe a cada miembro del espacio cuando pasa algo que conviene saber. Cada aviso se apaga por persona en la pantalla del espacio, bajo Avisos por correo; todos vienen encendidos.

Los dos últimos avisan antes de la caída: un servicio que se queda sin memoria muere con 137, y uno que se reinicia en bucle puede parecer verde en el lienzo. Se comprueban cada cinco minutos y se avisa una vez por episodio: Memoria al límite termina cuando lleva diez minutos por debajo del 80 %, y Reinicios en bucle cuando lleva media hora sin reiniciarse. Cada episodio queda también en el historial del proyecto, aunque nadie tenga el aviso encendido.

Avisos por webhook: Slack, Discord, Telegram, Teams, Google Chat o tu servidor

Además del correo, cada proyecto puede contar lo que le pasa a un canal de Slack, Discord, Microsoft Teams o Google Chat, a un chat de Telegram o a cualquier dirección HTTPS. Se añaden en Editar proyecto → Avisos, con fundaia webhook add <proyecto> <url> o con la herramienta add_webhook.

• El formato se adivina por la URL: hooks.slack.com envía un mensaje de Slack con un botón que abre la pantalla exacta, discord.com/api/webhooks/… un embed de Discord en color, y cualquier otra dirección recibe JSON. Mattermost o Rocket.Chat entienden el formato de Slack: elígelo con --format slack.

• El token del bot de Telegram es un secreto: la URL entera se guarda cifrada, como cualquier otra, y nunca se vuelve a enseñar; en pantalla solo se ve api.telegram.org/…sage. Si te falta chat_id se rechaza al crearlo, y lo que la gente escribe (nombres, motivos) se escapa antes de llegar al mensaje, así que nadie puede colar enlaces ni menciones.
• El JSON va firmado: cada envío lleva X-Fundaia-Event, X-Fundaia-Delivery y X-Fundaia-Signature: sha256=<hmac> sobre el cuerpo exacto, el mismo esquema que GitHub. El secreto se enseña una sola vez, al crearlo.

{
  "id": "whd_…",
  "event": "deployment-failed",
  "at": "2026-10-15T10:00:00.000Z",
  "title": "No se pudo desplegar api #12 en Tienda (production)",
  "reason": "El build terminó con código 1",
  "url": "https://infrastructure.fundaia.com/p/prj_…/s/sve_…/logs/dep_…",
  "project": { "id": "prj_…", "name": "Tienda" },
  "environment": "production",
  "service": { "name": "api", "serviceEnvironmentId": "sve_…" },
  "deployment": { "id": "dep_…", "number": 12, "commitSha": "abcdef1…", "commitSubject": "Arregla el login" },
  "workflowRun": null
}

• Cada aviso elige sus eventos y se puede pausar sin olvidarlo. Enviar prueba (o fundaia webhook test) manda un mensaje de ejemplo y dice si llegó; debajo de cada aviso queda cómo fue el último envío y, si falló, por qué.
• La URL es un secreto: se guarda cifrada y en pantalla solo se ve el host y el final. Solo se aceptan direcciones https:// públicas: localhost, 192.168.x.x o un .lan se rechazan, y una redirección no se sigue.
• Un destino caído no retrasa nada: el envío espera como mucho cinco segundos y nunca hace fallar un despliegue.
• Los eventos de monitores y alertas se llaman monitor-down, monitor-up, log-alert, log-alert-resolved, error-rate-high, error-rate-resolved, latency-high y latency-resolved. El JSON lleva además monitor (id, name, target, statusCode) o alert (id, name, kind, value, threshold). Un aviso creado antes de que existieran tiene que marcarlos.

Resumen semanal

Cada lunes a las 08:00, hora de Madrid (el cambio de hora no lo mueve), cada miembro de cada espacio que tenga al menos un proyecto recibe un correo con la semana que terminó el domingo:

• Se apaga por persona y espacio en Avisos por correo (Resumen semanal), con fundaia digest off o desde el iPhone. Ver el de esta semana (o fundaia digest preview) lo enseña tal y como saldría, y Enviármelo ahora (fundaia digest send) te lo manda aunque lo tengas apagado.
• Una vez por persona y semana: cada envío se reserva antes de mandarlo, así que ni un reinicio ni dos pasadas a la vez lo mandan dos veces. Si el servidor estuvo parado el lunes, sale en cuanto vuelve, hasta dos días tarde; después se da esa semana por perdida.
• Un espacio sin proyectos no recibe nada.
• Va en HTML (que sigue el modo oscuro del lector) y en texto plano, con los enlaces completos a la instancia.

Avisos en el escritorio

Desde el menú de tu cuenta, en Escritorio, el navegador puede avisarte aunque estés en otra pestaña: cuando un despliegue que has visto empezar queda en marcha, cuando uno falla, cuando Fundaia vuelve atrás sola, y cuando un monitor o una alerta de un proyecto que ves cambia. Solo con la pestaña en segundo plano; al pulsar el aviso vuelves a la pestaña, en el servicio. Se activa por navegador (el navegador pide permiso la primera vez) y se apaga desde el mismo sitio. En la terminal, fundaia watch cuenta lo mismo de los monitores y las alertas.