rollfuse
OBSERVABILIDADE

Rollback Automático com uma Métrica que Você Vê no Grafana

Como funciona

Um conector lê uma consulta PromQL pelo proxy de fonte de dados do Grafana, e um guardrail aborta o rollout quando a média da janela ultrapassa o limite.

O número que mostra que um rollout está dando errado provavelmente já está num dashboard do Grafana: uma proporção de erros, uma latência p95, uma fila crescendo. O Grafana mostra esse número para uma pessoa. Um guardrail do rollfuse pode agir sobre ele: um conector lê a mesma consulta pela API HTTP do Grafana e, quando o valor ultrapassa um limite durante um rollout, o rollfuse aborta o rollout automaticamente.

Esta página mostra esse caminho para uma fonte de dados compatível com Prometheus no Grafana, e a alternativa de você mesmo enviar os valores.

Como o rollfuse lê uma métrica pelo Grafana

Um conector do rollfuse faz um GET numa URL HTTPS, envia o segredo dele como Authorization: Bearer <segredo> e transforma a resposta JSON em observações. Ele faz isso periodicamente e sempre que você pede uma sincronização.

O proxy de fonte de dados do Grafana repassa uma requisição para uma das fontes de dados dele, identificada pelo UID, em /api/datasources/proxy/uid/<datasource-uid>/.... O Grafana autentica chamadas à API com um token de conta de serviço (service account) enviado como Bearer. Juntando as duas coisas, a URL do conector é o endpoint de consulta instantânea do Prometheus que fica atrás do seu Grafana:

https://grafana.exemplo.com.br/api/datasources/proxy/uid/<datasource-uid>/api/v1/query?query=<sua PromQL, codificada para URL>

e o segredo do conector é o token da conta de serviço do Grafana.

Testamos isso contra um Grafana Cloud em 11/10/2026. Com o token da conta de serviço, o proxy respondeu 200 com a resposta padrão da API do Prometheus ({"status":"success","data":{"resultType":"vector","result":[...]}}). Sem o token, respondeu 401.

1. Defina a métrica no rollfuse

Uma definição de métrica dá nome à métrica e à unidade. Ela não guarda consulta; a PromQL fica na URL do conector.

POST /v1/projects/{project_id}/metric-definitions
{
  "name": "Proporção de 5xx no checkout",
  "key": "checkout_5xx_ratio",
  "aggregation_type": "average",
  "unit": "ratio"
}

2. Teste o mapeamento contra o seu Grafana

A resposta do Prometheus guarda cada série em data.result, com o ponto num par [timestamp, "valor"]. Dá para testar o mapeamento contra a URL real antes de salvar qualquer coisa; a pré-visualização busca uma vez e não grava nada:

POST /v1/projects/{project_id}/connectors/preview
{
  "source_url": "https://grafana.exemplo.com.br/api/datasources/proxy/uid/<datasource-uid>/api/v1/query?query=<PromQL codificada para URL>",
  "secret": "<token da conta de serviço do Grafana>",
  "root_path": "data.result",
  "value_field": "value.1",
  "observed_at_field": "value.0",
  "observed_at_format": "unix_seconds"
}

A resposta mostra o corpo que o Grafana devolveu e as observações que o mapeamento gerou, ou qual campo não foi encontrado.

3. Crie o conector

Os mesmos quatro campos de mapeamento vão para uma versão de modelo de contrato no seu projeto, que precisa ser enviada para revisão e aprovada antes que um conector possa usá-la. Depois crie o conector com a URL do Grafana, o token da conta de serviço como secret, a definição de métrica e o ambiente em que o rollout roda. O tutorial de conectores mostra a pré-visualização, a criação e a sincronização.

4. Anexe um guardrail ao rollout

Um guardrail referencia a definição de métrica, um operador de comparação, um limite e uma janela de avaliação. Você pode criá-lo no console ou pela API:

POST /v1/rollouts/{rollout_id}/guardrails
{
  "metric_definition_id": "<metric_definition_id>",
  "comparison_operator": "gt",
  "threshold": 0.01,
  "evaluation_window_seconds": 900
}

O tutorial de rollback automático mostra essa chamada e como ler o histórico de avaliações do guardrail.

Escreva uma consulta que devolva um número só

Cada série em data.result vira uma observação, e o guardrail compara a média de todas as observações da janela com o limite. Uma consulta que devolve uma série por pod ou por rota misturaria tudo numa média só. Agregue até sobrar uma série, por exemplo:

sum(rate(http_requests_total{status=~"5.."}[5m])) / sum(rate(http_requests_total[5m]))

Se o seu serviço marca as métricas com a variação da flag, a consulta também pode medir só a variação que está sendo liberada, em vez do serviço inteiro.

Ou envie os valores você mesmo

Se o seu Grafana não é acessível pela internet, ou a fonte de dados não é compatível com Prometheus, um job seu pode rodar a consulta e enviar o resultado ao rollfuse com uma service credential que tenha o escopo metrics:write:

POST /v1/environments/{environment_id}/metric-definitions/{metric_definition_id}/observations
{
  "observations": [
    { "value": 0.004, "occurred_at": "2026-10-11T14:00:00Z" }
  ]
}

O guardrail trata essas observações do mesmo jeito que as gravadas por um conector.

O que acontece numa violação

Quando a média da janela ultrapassa o limite, o rollfuse aborta o rollout: a flag volta a servir a variação padrão para 100% daquele ambiente, e o rollout para de avançar. Os SDKs recebem a nova configuração na próxima atualização. Nada é deployado de novo; o código novo só deixa de ser servido enquanto alguém investiga.

O rollback automático está disponível em todos os planos, dentro de um limite de guardrails por plano (Free: 1, Starter: 5, Growth e Enterprise: ilimitado). Veja os planos em preços.

Cada variação nos seus dashboards

O Grafana consegue mostrar como cada variação se comporta se o seu serviço exporta métricas marcadas com a variação. O repositório público rollfuse/examples-go-prometheus faz isso com o SDK de Go: marca checkout_requests_total e checkout_request_duration_seconds com variation_key, conta rollfuse_flag_evaluations_total por flag, variação e motivo, e traz um dashboard do Grafana para essas métricas. Essa instrumentação fica no código do seu serviço; o rollfuse não envia métricas para o Grafana.

Limites que vale conhecer

  • O Grafana precisa ser acessível por HTTPS público. O conector só aceita URLs https e se recusa a conectar em endereços privados, de loopback ou link-local, então um Grafana que só responde dentro da sua rede não pode ser a fonte. Nesse caso, envie os valores você mesmo.
  • O token vai em toda sincronização. Use uma conta de serviço que só precise consultar aquela fonte de dados, e troque o segredo do conector quando trocar o token.
  • Sem dado, sem rollback. Se o Grafana ou a fonte de dados param de responder por mais tempo que a janela de avaliação, a janela fica sem observações; o rollfuse registra isso como dados insuficientes, não como violação, e o rollout não é abortado.
  • As avaliações do guardrail ficam no rollfuse. Um membro logado com a permissão guardrails:manage as consulta no console ou pela API com a própria sessão; service credentials não conseguem lê-las.
  • O mapeamento acima vale para fontes de dados compatíveis com Prometheus. Outros tipos de fonte de dados respondem no próprio formato e precisam de um mapeamento próprio, se couberem no modelo do conector.
  • Um projeto pode ter até 20 conectores.

Fontes