Observabilidade

Observabilidade é poder ver o que um produto em execução está fazendo, pelos seus logs, suas métricas e seus traces. No Airframe, uma equipe a recebe sem construir nada: os sinais do seu produto viajam para um único stack do Grafana Cloud, e seus painéis e suas regras de alerta vêm da sua entrada no catálogo. Esta página segue um sinal de uma aplicação até o Grafana, e depois lista o que cada produto recebe.

Um único stack do Grafana Cloud

O Grafana Cloud é um serviço hospedado para logs, métricas, traces, painéis e alertas. O Airframe usa um único stack dele, chamado projectairframe, para a organização inteira e não um por domínio, para que uma requisição que cruza dois domínios possa ser seguida de ponta a ponta. O ambiente de onde um sinal veio é um rótulo, não um stack separado.

O nível gratuito do Grafana Cloud permite exatamente um stack, então ele foi criado à mão no portal do Grafana durante o bootstrap. Tudo dentro dele é código: a raiz do Grafana do repositório operations cria as equipes, as pastas e suas permissões, e adiciona ao stack e às suas equipes toda pessoa do catálogo que tem um nome de usuário do Grafana.

O caminho de um sinal

Uma aplicação não sabe nada sobre para onde vai sua telemetria. Ela escreve seus logs como linhas JSON na sua saída padrão, envia traces e métricas por OTLP, o protocolo do OpenTelemetry, para o endereço que a plataforma dá a ela, e nunca tem uma credencial do Grafana. Tudo entre a aplicação e o Grafana é da plataforma.

Os traces e as métricas vão direto para o gateway OTLP da edição. A cada lote, o serviço apresenta um token de identidade de curta duração que o identifica, e o gateway admite só quem ele foi instruído a aceitar.
Os logs fazem um caminho mais longo. O Cloud Run os captura no Cloud Logging, um sink no projeto do produto os manda para um tópico do Pub/Sub que serve de buffer, e o buffer os empurra para o gateway de logs da edição.
Os eventos do navegador, como erros e tempos de página, vão para /_telemetry no próprio nome de host do produto, atrás do login único, e o serviço os encaminha com a sua identidade.
As métricas dos recursos de nuvem, como a CPU de uma instância do Cloud SQL, são lidas do Cloud Monitoring do Google por uma pequena instância coletora por edição, que as envia pelo gateway OTLP.

Os gateways rodam o Grafana Alloy, o coletor de telemetria do Grafana, no Cloud Run: um par por edição, um para OTLP e outro para logs, porque um serviço do Cloud Run expõe uma única porta. Eles vão a zero. Eles descartam credenciais e ruído, conferem os rótulos de cada sinal e encaminham para o Grafana com o token só de escrita da edição, a única credencial do Grafana daquele lado. Um produto não precisa configurar nada: o endereço do gateway chega na saída Ready da sua fábrica de projetos, e os módulos do golden path o passam para cada serviço.

Rótulos que dizem de onde um sinal veio

Dois rótulos são conferidos em todo sinal. O rótulo env é o ambiente: prod, np, sandbox, eph-<iid> para a prévia de um merge request, ou platform. O gateway OTLP o mantém só quando ele é válido para a sua própria edição e troca um valor ausente ou estranho por unknown; o gateway de logs mantém um válido e, se não houver, dá à linha o do seu perímetro, então só as entradas de auditoria ficam em unknown. Os dois marcam a edição como perimeter. De onde ele vem: o gateway OTLP o toma de deployment.environment.name ou de deployment.environment quando o recurso não traz env, e o módulo de Cloud Run do golden path define este último em cada serviço. O agente da plataforma o define em cada série que coleta, a partir do projeto e, na não produção, do nome do serviço de Cloud Run (sandbox ou eph-<iid>). O gateway de logs reduz o do perímetro da mesma forma e dá platform às linhas de um projeto da plataforma. As próprias tarefas agendadas da plataforma declaram platform no seu recurso, então as suas séries trazem env="platform"; o relatório de custos guarda o ambiente do projeto a que um custo pertence em um rótulo à parte, project_env. As séries do relatório de drift ainda chegam como unknown até a próxima versão da plataforma, que traz o componente que o declara.

Os outros rótulos dependem do caminho do sinal. O módulo de Cloud Run do golden path dá aos traces e às métricas de um serviço o seu nome de serviço, o seu domínio e o seu ambiente, como os atributos do OpenTelemetry service.name, service.namespace e deployment.environment. O agente da plataforma rotula as métricas de recursos da nuvem de cada projeto de produto faturado com product, o caminho do produto, e domain, a sua jornada e o seu domínio. O gateway de logs mantém o projeto, o serviço, o tipo de recurso e a severidade de cada linha de log. Os sinais de uma aplicação não trazem nenhum rótulo de equipe nem de criticidade.

O que cada produto recebe

A raiz do Grafana roda na cadeia de reconciliadores depois de cada merge no catálogo. A partir da entrada de cada produto, ela cria:

uma pasta para o produto, que a sua equipe pode editar e todo membro pode ver;
três painéis: o do serviço (requisições, erros, latência, instâncias, recursos), o de SLO, ou objetivo de nível de serviço, para as suas metas de confiabilidade, e o de custos, com o acumulado do mês e a previsão contra monthly_budget, laranja em 80 por cento e vermelho em 100. Os painéis do serviço e de SLO abrem em prod, e o seu primeiro filtro, env, troca o ambiente;
regras de alerta básicas, com limites tirados do campo slo da entrada: o orçamento de erros sendo consumido rápido ou devagar, mais de 2 por cento de erros do servidor, latência acima do objetivo ou do dobro dele, o Cloud SQL perto dos seus limites, mensagens do Pub/Sub esperando mais de dez minutos e um tópico de mensagens mortas que não está vazio. Elas julgam só a produção, e uma série ausente não é um alerta.

Os alertas são roteados pelo rótulo da equipe para o ponto de contato da equipe, que manda um e-mail aos membros da equipe que têm uma conta do Grafana, e um aviso urgente se repete a cada quatro horas até ser resolvido. O Grafana Cloud aceita só os endereços dos seus próprios membros, e hoje esses membros são as próprias contas do mantenedor, então os alertas de toda equipe chegam ao mantenedor.

Os painéis de custos leem a exportação de faturamento, que um job diário transforma em métricas; a página de FinOps acompanha esse orçamento.

Os painéis próprios de um produto

Uma equipe que quer mais do que os três painéis os escreve como código no seu próprio repositório: uma chamada ao módulo grafana-dashboard do golden path na raiz infra/grafana do produto, com os painéis em Terraform ou um painel exportado da interface do Grafana.

Essa raiz não tem nenhuma credencial do Grafana. Ela roda com a identidade de apply de produção do produto, no ambiente do GitLab grafana, e escreve cada painel como um arquivo sob o prefixo próprio do produto em um bucket. A raiz do Grafana da plataforma lê o bucket e coloca cada painel na pasta do produto, com a tag product-owned. O repositório é a versão de referência: um painel mudado só na interface do Grafana é sobrescrito na reconciliação seguinte, então uma equipe o exporta para a sua raiz para mantê-lo.

As prévias e a sandbox também são observáveis

As prévias e a sandbox enviam pelo gateway de não produção como todo o resto. Elas levam o seu próprio env, para que quem revisa veja a prévia de um merge request nos mesmos painéis ao escolher eph-<iid>: o golden path define deployment.environment com esse valor no serviço da prévia, o gateway OTLP o toma como env, e o agente da plataforma e o gateway de logs o derivam do nome do serviço. As regras de alerta selecionam só a produção, então as prévias e a sandbox nunca acionam ninguém.

O que é da própria plataforma

Os jobs agendados da plataforma, como a detecção de desvio, o coletor de prévias e os relatórios de custos e de cobertura, enviam suas próprias métricas. Uma pasta da plataforma tem o painel geral, os custos da plataforma e as medidas de entrega, e as suas regras mandam um e-mail para o ponto de contato da plataforma, por exemplo quando um pipeline agendado não reportou em um dia. O controle tem uma verificação de disponibilidade própria: uma verificação HTTP do Synthetic Monitoring do Grafana Cloud consulta o seu endereço /health a cada 60 segundos a partir de duas sondas, e uma regra avisa a plataforma quando mais de uma sonda falha por dois minutos, ou quando a verificação não informa nada (aplicada). Um segundo grupo de regras vigia as entradas de auditoria que um sink estreito na pasta envia ao Loki, como uma tentativa de criar uma chave, uma recusa de uma política ou uma concessão (limites de confiança). Hoje esse endereço também é a própria conta do mantenedor; o endereço do grupo da equipe da plataforma o substitui quando for membro do stack.

Projetado, não construído

O plantão (projetado). A ferramenta de plantão e incidentes do Grafana teria uma escala e uma cadeia de escalonamento por equipe, montadas a partir do bloco de plantão da equipe no catálogo. Hoje um alerta é um e-mail.
O agente de operações e o agente de auditoria (projetados). O primeiro investigaria um alerta no nível que o campo agentic_ops da entrada permite; o segundo procuraria em toda a organização desperdício e recursos órfãos. Hoje nenhum dos dois existe.
Equipe e criticidade nos sinais de uma aplicação (projetados). Seus traces, métricas e logs não trazem nenhum rótulo assim.
O resto das regras básicas (projetadas). As regras básicas também incluem o Cloud Run no seu máximo de instâncias, reinícios ou falta de memória, e uma verificação de contratos bloqueada na main; a raiz do Grafana ainda não cria essas regras.
As verificações de disponibilidade dos produtos (projetadas). As verificações de disponibilidade pelo nome de host de produção de cada produto são a próxima versão da raiz de telemetria. Hoje só o controle tem uma (acima).
As regras de alerta e os objetivos próprios de um produto (projetados). Os módulos grafana-alert e grafana-slo os publicariam como o grafana-dashboard publica painéis; enquanto isso, as regras básicas cobrem os alertas.

O custo permanente é de cerca de USD 7 por mês pela instância coletora de não produção; a de produção cabe na cota sempre gratuita do Google, os gateways vão a zero e o Grafana fica no seu nível gratuito.

Onde fica

No repositório operations:

No repositório golden-path:

modules/grafana-dashboard/: o painel próprio de um produto como código

No repositório landing-zone:

docs/guides/observability.md: o guia de observabilidade