Backend de observabilidade

O bloco de observabilidade (metrics, logs, traces, topology, monitors, rum e synthetics) pode ser servido por Datadog ou por Grafana Cloud. Os dois declaram as mesmas operações do catálogo, com nomes neutros de fornecedor.

Essa neutralidade é o que faz um segundo backend custar “escrever um connector” em vez de “reescrever o diagnóstico”. E é também o que torna os dois mutuamente exclusivos.

RUNNER_OBSERVABILITY=datadog   # default
RUNNER_OBSERVABILITY=grafana
RUNNER_OBSERVABILITY=none      # tenant sem observabilidade

A escolha é explícita, não inferida

O runner não decide o provider olhando qual credencial está presente. Isso é deliberado: inferir produziria um “meu Datadog parou de responder” sem causa visível na configuração.

datadog é o default, então todo runner existente segue idêntico sem mexer em nada.

Datadog

RUNNER_CONNECTORS=real
DD_API_KEY=…
DD_APP_KEY=…
# DD_SITE=datadoghq.com   # opcional: datadoghq.eu / us3 / us5 / ap1

Grafana Cloud

RUNNER_CONNECTORS=real RUNNER_OBSERVABILITY=grafana \
  GRAFANA_CLOUD_TOKEN=… \
  GRAFANA_PROM_URL=https://prometheus-prod-XX-prod-REGIAO.grafana.net/api/prom

Diferente do Datadog, o Grafana expõe um endpoint por datasource: Mimir, Loki e Tempo têm hosts distintos, cada um autenticando por HTTP Basic, com usuário = ID numérico da instância e senha = o token da Access Policy. Sem o _USER, o token vai como Bearer.

Só o token e o Mimir são obrigatórios. O Mimir é a espinha: o service graph e as métricas de Faro e Synthetics moram lá. Loki, Tempo e Alerting degradam operação a operação, com erro acionável.

Variável	Obrigatória	Para quê
`GRAFANA_CLOUD_TOKEN`	sim	Token da Access Policy.
`GRAFANA_PROM_URL`	sim	Mimir.
`GRAFANA_PROM_USER`	não	ID numérico da instância.
`GRAFANA_LOKI_URL` / `_USER`	não	Logs.
`GRAFANA_TEMPO_URL` / `_USER`	não	Traces.
`GRAFANA_STACK_URL`	não	API de Alerting (monitors).
`GRAFANA_SYNTHETICS_URL`	não	Default `https://synthetic-monitoring-api.grafana.net`.

Mapeamento de labels

Este é o ponto em que uma instalação de Grafana funciona no primeiro cliente e quebra no segundo.

service e env são conceito de primeira classe no Datadog. No Prometheus e no Loki, são convenção de label do cliente, que pode ser service, app, job, service_name do OTel. Os defaults abaixo são convenção, não garantia.

Variável	Default
`GRAFANA_SERVICE_LABEL`	`service`
`GRAFANA_ENV_LABEL`	`env`
`GRAFANA_NAMESPACE_LABEL`	`namespace`
`GRAFANA_HOST_LABEL`	`instance`
`GRAFANA_ROUTE_LABEL`	`http_route`

Descubra os seus com o endpoint /api/v1/labels do Mimir.

Checkly: o especialista que assume `synthetics`

CHECKLY_API_KEY=…
# CHECKLY_ACCOUNT_ID=…

O checkly é dedicado a uma capability. Presente, ele assume synthetics de quem for o provider geral, e convive tanto com Datadog quanto com Grafana.

Aqui, diferente da escolha do provider, inferir por credencial é seguro: o especialista só adiciona fonte, não disputa a leitura de outra.

O CHECKLY_ACCOUNT_ID é obrigatório na prática para token de usuário, porque sem ele a API responde 401 sem dizer por quê. Para token de conta ou de serviço, é dispensável.

Vercel: ortogonal, não concorrente

VERCEL_TOKEN=…
VERCEL_TEAM_ID=…

O Vercel não disputa dono de operação com o GitHub, porque os dois respondem fatos diferentes: o GitHub responde “que PR mergeou”, a Vercel responde “que artefato foi para o ar”. Por isso a Vercel cria operações próprias, com nome distinto de fornecedor, e entra direto no conjunto de connectors, sem passar por arbitragem.

O VERCEL_TEAM_ID é obrigatório na prática para token de time (sem ele a API responde 403 sem explicar) e ausente em conta pessoal. Use token read-only escopado ao time.

O critério: reusar a operação ou criar uma nova?

Se você for escrever um segundo connector para uma capability que já tem dono, o teste é semântico:

O consumidor que já usa a operação aceitaria a resposta do novo connector como equivalente?

Sim → reusa a operação. É o caso do Grafana em metrics.*: p99 é p99. O catalogHash fica intacto, nada muda para os consumidores, e o connector passa pela arbitragem, porque disputa dono de operação.

Não → operação nova, com nome distinto de fornecedor. É o caso da Vercel. O catalogHash muda conscientemente, e o connector entra direto, sem arbitragem, porque as operações são disjuntas.

Operação com mais de uma implementação exige contrato

Quando duas implementações servem a mesma operação, um nome compartilhado não basta: é preciso um contrato de output declarado. É ele que torna “trocar o dono da operação” seguro.

O contrato é por operação, não por capability, e é piso, não teto: campo extra passa, campo declarado ausente rebaixa a capability para opaque.

Ao adicionar ou alterar uma operação servida por dois ou mais connectors, atualize o contrato e rode a suíte de conformância contra as implementações, com cenário populado e vazio.