Painéis, alertas e desvio

Cada produto do Airframe recebe painéis e regras de alerta a partir da sua entrada do catálogo, e cada repositório recebe uma issue quando a nuvem deixa de corresponder ao seu código. Esta página é o guia prático para usá-los no dia a dia: onde ficam os painéis de um produto e como lê-los, como adicionar um painel próprio, o que fazer quando chega um alerta, e como lidar com uma issue de desvio. Observabilidade explica como os sinais viajam e o que cada produto recebe; esta página não repete isso.

1. Leia os painéis de um produto

Quem pode vê-los: cada pessoa do catálogo que tem uma conta do Grafana Cloud e um grafana_username no seu arquivo em people/. Uma mudança nesse campo é um merge request do catálogo que um líder da equipe da pessoa aprova. Depois a raiz do Grafana adiciona a pessoa ao stack e às suas equipes.

1. Abra o único stack do Grafana Cloud, projectairframe, e percorra as suas pastas: uma por jornada, domínio, contexto e produto, aninhadas nessa ordem. O produto de pedidos da organização de demonstração fica em shop, store, ordering, orders.
2. A pasta do produto tem três painéis, com o nome do produto: <product> service, <product> SLO e <product> cost. A equipe do produto pode editar a pasta; todos os outros podem vê-la.
3. O painel de serviço mostra as requisições, a proporção de erros do servidor (em vermelho acima de 2 por cento), a latência contra o objetivo da entrada (em laranja acima dele, em vermelho no dobro), as instâncias, a CPU e a memória, os painéis do Cloud SQL e do Pub/Sub, e os logs.
4. O painel de SLO mostra a disponibilidade e o orçamento de erros que resta em 30 dias contra o slo da entrada, e com que velocidade esse orçamento é consumido.
5. O painel de custos está em Custo e faturamento.

Cada painel tem um filtro env que abre em prod, e um filtro service. O filtro seleciona pelo rótulo env, que a plataforma define: o gateway OTLP a partir do deployment.environment da aplicação quando o recurso não traz env, o agente da plataforma em cada série que coleta, a partir do projeto, e o gateway de logs a partir do rótulo da entrada ou, se não houver, do do seu perímetro. No gateway OTLP um sinal cujo rótulo não é válido para a sua edição é marcado como unknown; no de logs, só as entradas de auditoria. Hoje nenhum produto da demo é faturado, então os painéis de nenhum produto têm dados ainda.

2. Adicione um painel próprio

Uma equipe que quer mais que os três painéis os escreve como código, no seu próprio repositório. A interface do Grafana serve para fazer um rascunho, mas um painel mudado só lá é sobrescrito na próxima reconciliação.

1. Onde: o repositório do produto, infra/grafana/main.tf. O template já gera ali uma chamada, overview, como ponto de partida.
2. Adicione uma chamada ao módulo grafana-dashboard do golden path com:
   • ready, a saída Ready do produto, como a chamada de partida a lê;
   • name, um identificador curto e único no produto, nunca service, slo nem cost, que a plataforma usa;
   • title, o nome que o Grafana mostra;
   • dashboard, com pelo menos panels. Um painel exportado da interface do Grafana funciona como jsondecode(file(...)); o id, o uid, a versão, a pasta e o título próprios dele são descartados, e as fontes de dados são nomeadas pelo tipo.
3. Rode airframe validate infra/grafana e depois abra um merge request.
4. Quem aprova: um membro da equipe do produto que não seja o autor, e depois o controle de aprovação. Onde nenhum membro da equipe tem conta no GitLab, a equipe de plataforma o substitui; hoje as aprovações dela são das próprias contas do mantenedor, então a separação entre duas pessoas ainda não é real.
5. Faça o merge. O pipeline planeja, verifica e aplica a raiz como plan:grafana, policy:grafana e apply:grafana. O apply não tem nenhuma credencial do Grafana: ele roda com a identidade de apply de produção do produto e escreve o painel como um arquivo sob o prefixo do produto no bucket da plataforma. Depois grafana:reconcile pede ao controle de aprovação que rode o pipeline do operations, cuja raiz do Grafana coloca o painel na pasta do produto, com a tag product-owned.

Tirar uma chamada tira o painel na próxima reconciliação. As regras de alerta e os objetivos próprios de um produto, pelos módulos grafana-alert e grafana-slo, estão projetados; enquanto isso, as regras básicas cobrem os alertas.

3. Confira o lado da aplicação

Um produto não precisa configurar nada para a sua telemetria, mas a aplicação precisa manter três hábitos, que os adaptadores do golden path já seguem:

• escrever os logs como linhas JSON na saída padrão, com severity, trace_id e span_id;
• enviar traces e métricas com OTLP para o endereço que a plataforma injeta, e não enviar nada quando não há nenhum;
• nunca ter uma credencial do Grafana.

O resto do caminho é da plataforma, como descreve Observabilidade.

4. Aja diante de um alerta

Um alerta chega à equipe do produto por e-mail, a partir do ponto de contato da equipe, e só os membros que têm uma conta do Grafana o recebem. O título nomeia a regra, como Latency p95 above twice the SLO, e o resumo nomeia o produto, o serviço, o valor e o objetivo. Uma regra é um aviso urgente ou um ticket, e um aviso urgente se repete a cada quatro horas até ser resolvido.

1. Abra os painéis de serviço e de SLO do produto no horário do alerta, e leia o painel de logs.
2. Onde: o runbook do produto, um arquivo do seu repositório que é da equipe e das suas pessoas de plantão. Siga-o.
3. Corrija com um merge request. Voltar atrás é um merge request de reversão, planejado e aplicado como qualquer outro; enquanto isso a revisão anterior do Cloud Run continua disponível.
4. Se uma correção à mão não puder esperar, peça uma concessão de nível 2, como descreve Concessões e via de emergência, e escreva a correção no código depois.
5. Escreva o que aconteceu em postmortems/, um arquivo por incidente.

Hoje os alertas de todas as equipes chegam ao mantenedor, porque o Grafana Cloud aceita só os endereços dos seus membros e as contas do mantenedor são os seus únicos membros. O plantão e o escalonamento estão projetados; hoje um alerta é um e-mail. As regras básicas julgam a produção pelo mesmo rótulo env.

5. Leia e feche uma issue de desvio

Onde: as issues do repositório dono da raiz, com o rótulo audit::drift e o título Drift: <root>. Os agendamentos diários planejam cada raiz às 06:00 UTC no landing-zone, às 06:20 no control-plane e às 06:40 no operations; os repositórios de produto têm agendamentos próprios. Desvio explica o porquê.

A issue lista os recursos que diferem e a ação que o plano tomaria em cada um, nunca os valores deles: o plano de um merge request os mostra. Descubra no registro de auditoria quem mudou o quê, e depois aja conforme o que encontrar:

O que você encontra	O que fazer
Uma pessoa mudou um recurso à mão	Não faça merge de nada: o próximo apply da raiz a partir da main o coloca de volta
Um padrão do provedor ou uma mudança externa	Um merge request que o adote ou o fixe; o plano dele não mostra mudança
Um valor guardado de forma diferente de como foi escrito, como uma duração	Escreva-o como ele é guardado
Uma raiz aplicada de um notebook se desviou	Aplique-a com uma concessão, e registre a concessão
O plano falhou	Corrija a raiz ou os papéis da sua identidade em um merge request
Uma verificação falha com um plano vazio	Faça o que diz a mensagem da verificação

Não feche uma issue de desvio à mão. A execução agendada que encontra a raiz correspondendo de novo adiciona uma nota, Converged, e a fecha. Uma issue fechada enquanto o desvio dura volta na próxima execução agendada como uma nova, porque o relatório só procura issues abertas.

Onde fica

No repositório operations:

• roots/grafana/: pastas, painéis e regras de alerta a partir do catálogo
• docs/telemetry.md: o caminho da telemetria

No repositório golden-path:

• modules/grafana-dashboard/: o painel próprio de um produto

No repositório control-plane:

• templates/drift-report/: as issues de desvio

No repositório landing-zone:

• docs/guides/operations.md: o desvio e o que fazer com ele