Airframe

Por qué Airframe

Observable y documentado por defecto

Un equipo no debería tener que construir su propio monitoreo ni dibujar sus propios diagramas de arquitectura. La entrada del catálogo de un producto le da una carpeta de Grafana, paneles y reglas de alerta; sus registros, métricas y trazas llegan a ellos sin configuración; y cada merge publica la parte del producto en un mapa de toda la organización, que se reconstruye solo.

Cómo un producto se vuelve observable y documentado

  1. La entrada le da una carpeta y paneles

    Cuando se fusiona la entrada del catálogo de un producto, la raíz de Grafana del repositorio operations se ejecuta en la cadena de reconciliadores. En el único stack de Grafana Cloud de la organización crea la carpeta del producto, que su equipo puede editar y todos pueden ver, con un panel de servicio y un panel de SLO que abren en producción, junto al panel de costos de la página de FinOps.

  2. Las reglas de alerta vienen con ella

    La misma raíz crea las reglas de alerta básicas del producto, con umbrales tomados del campo slo de la entrada: el presupuesto de errores que se consume rápido o despacio, errores del servidor por encima del 2 por ciento, latencia por encima del objetivo o del doble, Cloud SQL cerca de sus límites, mensajes de Pub/Sub que esperan más de diez minutos y un tema de mensajes fallidos que no está vacío. Seleccionan producción por la etiqueta env y envían un correo al punto de contacto del equipo. Hoy ese punto de contacto llega a las cuentas del propio mantenedor, porque Grafana Cloud acepta solo direcciones de sus propios miembros y las cuentas del mantenedor son sus únicos miembros.

  3. La telemetría fluye sin configuración

    Una aplicación escribe registros JSON en su salida estándar y envía trazas y métricas con OTLP a la dirección que le da la plataforma; nunca tiene una credencial de Grafana. La plataforma tiene un par de puertas de enlace por edición, producción y no producción. Las trazas y las métricas van a la puerta de enlace OTLP de la edición con el token de identidad del servicio, y los registros viajan por Cloud Logging y un buffer de Pub/Sub hasta la puerta de enlace de registros. Las puertas de enlace, Grafana Alloy en Cloud Run, verifican la etiqueta env de cada señal, le marcan su edición y la reenvían con un token de solo escritura. La dirección llega en la salida Ready del producto, y los módulos del golden path la pasan a cada servicio.

  4. Cada merge publica su parte del mapa

    El pipeline de cada repositorio de producto incluye el componente catalog-publish, y también el del catálogo y los de cuatro repositorios de la plataforma. En un merge request, el componente genera el fragmento del repositorio, su parte del mapa, sin ninguna credencial, y falla cuando falta la descripción general o el runbook. Después del merge publica el fragmento bajo el prefijo propio del repositorio: para un producto, su servicio, sus especificaciones de API y de eventos, los productos que llama, su runbook y sus registros de decisiones.

  5. El mapa se reconstruye solo

    Un agregador reconstruye el mapa con los últimos fragmentos justo después de cada publicación y cada hora, en catalog.projectairframe.dev detrás de IAP, donde todos en la organización pueden leerlo. Toma la lista de productos del catálogo, omite un fragmento roto para que el resto se siga construyendo y conserva las últimas tres versiones. El mapa sigue la rama main de cada repositorio, no lo que está desplegado.

Un ejemplo práctico

Esta es una parte de la entrada del producto invoicing en el catálogo de la demo, y lo que la plataforma deriva de ella. La carpeta, los paneles y las reglas de alerta salen solo de la entrada; las señales necesitan que los proyectos del producto tengan facturación, y hoy ningún producto de la demo la tiene, así que la telemetría de abajo es la que fluiría.

product: invoicing
journey: settle
domain: billing
context: invoicing
team: billing-core
slo: { availability: 99.5, latency_p95_ms: 400 }
  • Una carpeta para el producto bajo settle, billing e invoicing, que billing-core edita y todos ven
  • Los paneles "invoicing service" e "invoicing SLO", que abren en prod, junto a "invoicing cost"
  • Reglas de alerta con los umbrales de la entrada: un presupuesto de errores para una disponibilidad del 99,5 por ciento, un ticket cuando la latencia p95 se mantiene por encima de 400 ms y una alerta urgente por encima de 800 ms
  • Alertas al punto de contacto de billing-core, que hoy envía correos a las cuentas del propio mantenedor
  • Trazas y métricas que llevan el nombre de servicio de invoicing, su dominio y su entorno, y métricas de recursos de la nube etiquetadas con la ruta del producto, settle/billing/invoicing/invoicing, sin ninguna credencial de Grafana en el repositorio
  • Una página de servicio para invoicing en catalog.projectairframe.dev, construida a partir del fragmento que su repositorio publica en cada merge a main: su descripción general, sus responsables, su runbook y sus registros de decisiones

Qué lo hace cierto

Cada producto tiene sus paneles y sus reglas de alerta desde su entrada.
La raíz de Grafana de operations, que se ejecuta cuando cambia el catálogo, crea la carpeta de cada producto del catálogo, que su equipo edita y todos ven, sus paneles de servicio y de SLO y sus reglas de alerta básicas, con umbrales tomados del campo slo de la entrada; las reglas seleccionan producción por la etiqueta env, y una serie que falta no es una alerta.
Una alerta llega al equipo del producto, y hoy eso significa al mantenedor.
Cada regla se dirige por la etiqueta del equipo al punto de contacto del equipo, que envía un correo a los miembros del equipo que tienen cuenta en Grafana, y una alerta urgente se repite cada cuatro horas hasta que se resuelve. Grafana Cloud acepta solo direcciones de sus propios miembros, y hoy esos miembros son las cuentas del propio mantenedor, así que las alertas de cada equipo, y las de la plataforma, llegan al mantenedor.
Una aplicación no necesita configuración y no tiene ninguna credencial de Grafana.
La salida Ready de la fábrica de proyectos lleva la dirección de la puerta de enlace de la edición del producto, producción o no producción, y el módulo de Cloud Run del golden path la inyecta en cada servicio. Las trazas y las métricas llegan a la puerta de enlace OTLP con el token de identidad del servicio, que la verificación de invocador de la puerta de enlace admite; los registros llegan a la puerta de enlace de registros por el sink del proyecto del producto y el buffer de Pub/Sub. Las puertas de enlace tienen el token de solo escritura de la edición, la única credencial de Grafana de ese lado.
Cada señal dice de qué edición vino.
La puerta de enlace OTLP conserva el env de una señal solo cuando es válido para su propia edición y reemplaza un valor faltante o ajeno por unknown; la puerta de enlace de registros conserva un env válido y, si no, le da a la línea el de su perímetro, así que solo las entradas de auditoría quedan en unknown. Las dos marcan la edición como perimeter. El módulo de Cloud Run del golden path les da a las trazas y las métricas de un servicio su nombre de servicio, su dominio y su entorno, y el agente de la plataforma etiqueta las métricas de recursos de Cloud de cada proyecto de producto facturado con la ruta del producto y su recorrido y dominio.
Cada producto publica su propia parte del mapa, y solo la suya.
El job validate:fragment del componente catalog-publish genera el fragmento en el merge request sin ninguna credencial y falla si falta la descripción general o el runbook; en la rama main protegida, release:catalog lo publica con la identidad que el repositorio ya tiene. La identidad de aplicación de producción de un producto solo puede escribir bajo el prefijo de su producto, y el repositorio del catálogo escribe como platform-catalog@ bajo el suyo. Los cuatro repositorios de la plataforma comparten una identidad, platform-docs@, cuyo permiso cubre todo el prefijo de la plataforma, así que nada impide que uno de ellos escriba la parte de otro.
El mapa se reconstruye solo a partir de los últimos fragmentos.
El agregador, un job de Cloud Run, corre cuando una identidad que publica lo pide después de una publicación, que es todo lo que esa identidad puede hacer en el proyecto, y cada hora según una programación. Lee la lista de productos del catálogo, omite un fragmento roto con sus motivos en el registro de la ejecución y conserva las últimas tres versiones. El sitio detrás de IAP busca una versión nueva cada minuto y sigue sirviendo la última si no puede leerla.