Observabilidad

# gateway.env — export telemetry to your OTLP collector
AIHUMMER_OTEL_ENDPOINT=http://otel-collector:4317

La observabilidad de AiHummer tiene **dos superficies**: la puerta de enlace sirve como **Prometeo `GET /metrics`** punto de acceso que puedes raspar para lo básico, y opcionalmente puede **enviar telemetría a través de OTLP** a un endpoint de OpenTelemetry que configures. Raspar `/metrics` para la monitorización básica; para trazas y métricas detalladas, apunta AiHummer a tu colector OTLP y visualiza los datos con los paneles de Grafana incluidos. > [!NOTE] > pprof (`/debug/pprof`) es **no** expuesto. ## El Prometeo `/metrics` punto final `GET /metrics` sirve métricas en formato de texto de Prometheus sin configuración adicional. Solo se exponen indicadores no sensibles — información de construcción, tiempo de actividad y ejecución del proceso, estado del pool de conexiones de la base de datos y un indicador de disponibilidad; no hay datos de inquilinos, ni secretos, ni etiquetas por solicitud. Para trazas y métricas detalladas, use el push OTLP. ## empuje OTLP Establezca una sola variable para activar la telemetría: ```ini # gateway.env — export telemetry to your OTLP collector AIHUMMER_OTEL_ENDPOINT=http://otel-collector:4317 ``` Con `AIHUMMER_OTEL_ENDPOINT` configurado, la puerta de enlace envía telemetría a ese colector. Desde allí, dirígela a tu backend (Tempo, un almacén de métricas, registros) y a Grafana. ## Manejo de pánicos y errores Los informes de errores **nunca se envían a ningún sitio externo**: la puerta de enlace no incluye ningún cliente de rastreador de errores externo ni ningún DSN externo — los datos sobre tus errores nunca salen de tu perímetro. Aun así, la resistencia a los pánicos es completa: - un pánico en un manejador HTTP se convierte en una respuesta de error corriente (un 500 que lleva un sobre `AIH-…`) — el proceso no muere y sigue atendiendo las demás solicitudes; - un pánico en una gorutina en segundo plano también se recupera y no derriba la puerta de enlace. Ambos casos acaban en el registro estructurado — léelos en la página **Registros** (abajo) o mediante `journalctl`. ## Registros en vivo en la interfaz de administración La interfaz de administrador **Registros** la página es una vista en tiempo real del diario del gateway: las nuevas líneas se agregan automáticamente cada pocos segundos, con desplazamiento automático mientras estás en la parte inferior. La barra de herramientas tiene una **búsqueda en línea** y un **filtro de nivel** (todo / errores / advertencias / información / depuración). Varias otras páginas (Panel de control, Sesiones, Canales) también se actualizan automáticamente, y listas largas (auditoría, cambios, notificaciones, y demás) se cargan página por página con un botón de "Mostrar más". Los registros completos de cada servicio todavía viven en systemd — `aihummer logs [unit]` o `journalctl -u aihummer-gateway`. ## Paneles de Grafana Los paneles de Grafana predefinidos se incluyen con la versión. Imprórtalos en tu instancia de Grafana para obtener las vistas operativas sin tener que crear paneles desde cero. ## Qué ver Estas son las señales que te indican que el sistema está sano y que los turnos están fluyendo: | Señal | Por qué importa | |---|---| | **Latencia de giro** | Capacidad de respuesta de extremo a extremo de los turnos del agente | | **Tasa de error** | Fallas en turnos / solicitudes: el primer signo de problemas | | **Disposiciones de entrega** | Si las respuestas están llegando realmente a los canales | | **Entregas pendientes** | Acumulación de respuestas no entregadas; el crecimiento sostenido significa que la entrega está atrapada | Un aumento sostenido en **entregas pendientes o repetidamente fallidas** es la advertencia temprana más clara de que la entrega se está acumulando: obsérvala durante implementaciones e incidentes. ## Puntos finales del sistema Junto con OTLP, la puerta de enlace expone pequeños endpoints HTTP útiles para sondas, relojes y diagnósticos de clientes: | Método | Punto final | Propósito | |---|---|---| | `GET` | `/metrics` | Métricas de Prometheus (compilación, tiempo de ejecución, grupo de BD, disponibilidad) | | `GET` | `/healthz` | Vivo + versión | | `GET` | `/readyz` | Disponibilidad (verifica Postgres; 503 si está caído) | | `GET` | `/v1/ping` | Verificación de alcance ligera | | `GET` | `/v1/time` | Hora del servidor | | `POST` | `/v1/client-log` | Ingerir eventos de registro del lado del cliente | Las sondas de salud y preparación se cubren en detalle en [systemd y controles de salud](/es/v1.0/operations/systemd-health). ## ¿A dónde vamos ahora? - Sondas y la lista de verificación previa al vuelo de producción: [systemd y controles de salud](/es/v1.0/operations/systemd-health). - Qué ver durante una actualización escalonada: [Política de actualización](/es/v1.0/operations/upgrade-policy).