Paneles, alertas y deriva

Cada producto de Airframe recibe paneles y reglas de alerta a partir de su entrada del catálogo, y cada repositorio recibe un issue cuando la nube deja de coincidir con su código. Esta página es la guía práctica para usarlos en el día a día: dónde están los paneles de un producto y cómo leerlos, cómo agregar un panel propio, qué hacer cuando llega una alerta, y cómo tratar un issue de deriva. Observabilidad explica cómo viajan las señales y qué recibe cada producto; esta página no lo repite.

1. Lee los paneles de un producto

Quién puede verlos: cada persona del catálogo que tiene una cuenta de Grafana Cloud y un grafana_username en su archivo bajo people/. Un cambio en ese campo es un merge request del catálogo que aprueba un líder del equipo de la persona. Después la raíz de Grafana agrega a la persona al stack y a sus equipos.

Abre el único stack de Grafana Cloud, projectairframe, y recorre sus carpetas: una por recorrido, dominio, contexto y producto, anidadas en ese orden. El producto de pedidos de la organización de demostración está bajo shop, store, ordering, orders.
La carpeta del producto tiene tres paneles, con el nombre del producto: <product> service, <product> SLO y <product> cost. El equipo del producto puede editar la carpeta; todos los demás pueden verla.
El panel de servicio muestra las solicitudes, la proporción de errores del servidor (en rojo por encima del 2 por ciento), la latencia contra el objetivo de la entrada (en naranja por encima de él, en rojo al doble), las instancias, la CPU y la memoria, los paneles de Cloud SQL y Pub/Sub, y los registros.
El panel de SLO muestra la disponibilidad y el presupuesto de errores que queda en 30 días contra el slo de la entrada, y qué tan rápido se consume ese presupuesto.
El panel de costos está en Costo y facturación.

Cada panel tiene un filtro env que abre en prod, y un filtro service. El filtro selecciona por la etiqueta env, que fija la plataforma: la puerta de enlace OTLP a partir del deployment.environment de la aplicación cuando el recurso no trae env, el agente de la plataforma en cada serie que recoge, a partir del proyecto, y la puerta de enlace de registros a partir de la etiqueta de la entrada o, si no, de la de su perímetro. En la puerta de enlace OTLP una señal cuya etiqueta no es válida para su edición se marca como unknown; en la de registros, solo las entradas de auditoría. Hoy ningún producto de la demo tiene facturación, así que los paneles de ningún producto tienen datos todavía.

2. Agrega un panel propio

Un equipo que quiere más que los tres paneles los escribe como código, en su propio repositorio. La interfaz de Grafana sirve para hacer un borrador, pero un panel cambiado solo allí se sobrescribe en la siguiente reconciliación.

Dónde: el repositorio del producto, infra/grafana/main.tf. La plantilla ya genera ahí una llamada, overview, como punto de partida.
Agrega una llamada al módulo grafana-dashboard del golden path con:
- ready, la salida Ready del producto, como la lee la llamada de partida;
- name, un identificador corto y único en el producto, nunca service, slo ni cost, que usa la plataforma;
- title, el nombre que muestra Grafana;
- dashboard, con al menos panels. Un panel exportado de la interfaz de Grafana funciona como jsondecode(file(...)); se descartan su propio id, uid, versión, carpeta y título, y las fuentes de datos se nombran por tipo.
Ejecuta airframe validate infra/grafana y después abre un merge request.
Quién aprueba: un miembro del equipo del producto que no sea el autor, y después la compuerta de aprobación. Donde ningún miembro del equipo tiene cuenta de GitLab, el equipo de plataforma lo reemplaza; hoy sus aprobaciones son de las propias cuentas del mantenedor, así que la separación entre dos personas todavía no es real.
Haz el merge. El pipeline planifica, verifica y aplica la raíz como plan:grafana, policy:grafana y apply:grafana. El apply no tiene ninguna credencial de Grafana: se ejecuta con la identidad de apply de producción del producto y escribe el panel como un archivo bajo el prefijo del producto en el bucket de la plataforma. Después grafana:reconcile le pide a la compuerta de aprobación que ejecute el pipeline de operations, cuya raíz de Grafana coloca el panel en la carpeta del producto, con la etiqueta product-owned.

Quitar una llamada quita el panel en la siguiente reconciliación. Las reglas de alerta y los objetivos propios de un producto, mediante los módulos grafana-alert y grafana-slo, están diseñados; mientras tanto, las reglas básicas cubren las alertas.

3. Revisa el lado de la aplicación

Un producto no necesita configurar nada para su telemetría, pero la aplicación tiene que mantener tres hábitos, que los adaptadores del golden path ya siguen:

escribir los registros como líneas JSON en la salida estándar, con severity, trace_id y span_id;
enviar trazas y métricas con OTLP a la dirección que inyecta la plataforma, y no enviar nada cuando no hay ninguna;
nunca tener una credencial de Grafana.

El resto del camino es de la plataforma, como describe Observabilidad.

4. Actúa ante una alerta

Una alerta llega al equipo del producto por correo, desde el punto de contacto del equipo, y solo la reciben los miembros que tienen una cuenta de Grafana. Su título nombra la regla, como Latency p95 above twice the SLO, y su resumen nombra el producto, el servicio, el valor y el objetivo. Una regla es un aviso urgente o un ticket, y un aviso urgente se repite cada cuatro horas hasta que se resuelve.

Abre los paneles de servicio y de SLO del producto en la hora de la alerta, y lee el panel de registros.
Dónde: el runbook del producto, un archivo de su repositorio que es del equipo y de sus personas de guardia. Síguelo.
Corrige el problema con un merge request. Volver atrás es un merge request de reversión, planificado y aplicado como cualquier otro; mientras tanto la revisión anterior de Cloud Run sigue disponible.
Si una corrección a mano no puede esperar, pide una concesión de nivel 2, como describe Concesiones y vía de emergencia, y escribe la corrección en el código después.
Escribe lo que pasó en postmortems/, un archivo por incidente.

Hoy las alertas de todos los equipos le llegan al mantenedor, porque Grafana Cloud acepta solo las direcciones de sus miembros y las cuentas del mantenedor son sus únicos miembros. Las guardias y el escalamiento están diseñados; hoy una alerta es un correo. Las reglas básicas juzgan producción con la misma etiqueta env.

5. Lee y cierra un issue de deriva

Dónde: los issues del repositorio dueño de la raíz, con la etiqueta audit::drift y el título Drift: <root>. Los programas diarios planifican cada raíz a las 06:00 UTC en landing-zone, a las 06:20 en control-plane y a las 06:40 en operations; los repositorios de producto tienen sus propios programas. Deriva explica por qué.

El issue enumera los recursos que difieren y la acción que el plan tomaría con cada uno, nunca sus valores: los muestra el plan de un merge request. Averigua en el registro de auditoría quién cambió qué, y después actúa según lo que encuentre:

Lo que encuentras	Qué hacer
Una persona cambió un recurso a mano	No hagas merge de nada: el siguiente apply de la raíz desde main lo devuelve a su estado
Un valor por defecto del proveedor o un cambio externo	Un merge request que lo adopte o lo fije; su plan no muestra cambios
Un valor guardado distinto de como se escribió, como una duración	Escribe el valor como se guarda
Derivó una raíz que se aplica desde una laptop	Aplica la raíz con una concesión, y registra la concesión
El plan falló	Corrige la raíz o los roles de su identidad en un merge request
Una verificación falla con un plan vacío	Haz lo que dice el mensaje de la verificación

No cierres un issue de deriva a mano. La ejecución programada que encuentra la raíz coincidiendo otra vez agrega una nota, Converged, y lo cierra. Un issue cerrado mientras dura la deriva vuelve en la siguiente ejecución programada como uno nuevo, porque el informe solo busca issues abiertos.

Dónde está

En el repositorio operations:

En el repositorio golden-path:

modules/grafana-dashboard/: el panel propio de un producto

En el repositorio control-plane:

templates/drift-report/: los issues de deriva

En el repositorio landing-zone:

docs/guides/operations.md: la deriva y qué hacer con ella