Backend de observabilidade

O bloco de observabilidade (metrics, logs, traces, topology, monitors, rum e synthetics) pode ser servido por Datadog, por Grafana Cloud ou por SigNoz. Os três 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 os torna mutuamente exclusivos.

RUNNER_OBSERVABILITY=datadog   # default
RUNNER_OBSERVABILITY=grafana
RUNNER_OBSERVABILITY=signoz
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.

SigNoz

RUNNER_CONNECTORS=real RUNNER_OBSERVABILITY=signoz \
  SIGNOZ_ENDPOINT=http://signoz.observability.svc.cluster.local:8080 \
  SIGNOZ_API_KEY=…

O SigNoz é o primeiro backend auto-hospedado suportado, e isso muda duas coisas em relação aos outros dois.

O endpoint costuma ser interno. Datadog e Grafana Cloud são hosts públicos de fornecedor; um SigNoz seu normalmente só existe dentro da sua rede. O RootPilot alcança porque o runner roda lá dentro — é uma consequência direta do modelo BYOC, e um SaaS de observabilidade não chegaria nesse endereço. Use o nome de serviço interno, não exponha a instância para configurar o RootPilot.

A versão varia. Datadog e Grafana Cloud têm uma versão só, a que o fornecedor opera. Um SigNoz auto-hospedado pode estar meses atrás. O connector usa a API query_range v5; instalação anterior a ela não é suportada, e o self-check de boot reporta a versão encontrada em vez de falhar de forma obscura na primeira leitura.

Variável	Obrigatória	Para quê
`SIGNOZ_ENDPOINT`	sim	Base da instância. Pode ser HTTP interno.
`SIGNOZ_API_KEY`	sim	Chave de service account (header `SIGNOZ-API-KEY`).

Capabilities: o que ele serve, e o que não

Serve metrics, logs, traces, topology (o service map, que no SigNoz vive como métrica) e monitors (as alert rules).

Não serve rum nem synthetics, e essa ausência é declarada de propósito. O frontend monitoring do SigNoz é OTel de browser, que não responde as mesmas perguntas do RUM do Datadog, e não há produto de synthetics. Como o RootPilot esconde da superfície do agente a ferramenta cuja operação ninguém serve, essas tools simplesmente não aparecem — em vez de aparecerem e responderem meia-verdade. Um SigNoz + Checkly continua com synthetics, porque o especialista entra por fora.

Mapeamento de campos

Mesmo problema do Grafana, com um chão mais firme: o SigNoz é OTel-native, então o vocabulário tende a ser semconv. Os defaults são um piso defensável, não um chute — mas continuam ajustáveis, porque o semconv 1.27 renomeou deployment.environment para deployment.environment.name e as duas gerações convivem em campo.

Variável	Default
`SIGNOZ_SERVICE_FIELD`	`service.name`
`SIGNOZ_ENV_FIELD`	`deployment.environment`
`SIGNOZ_NAMESPACE_FIELD`	`k8s.namespace.name`
`SIGNOZ_HOST_FIELD`	`host.name`
`SIGNOZ_ROUTE_FIELD`	`http.route`

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. Sem CHECKLY_API_KEY, o synthetics fica com o provider. O boot diz quem ficou com a capability nos dois casos, numa linha capability arbitration (owner: checkly ou owner: datadog).

Aqui, diferente da escolha do provider, inferir por credencial é seguro: com a chave, o especialista assume; sem ela, nada muda para o provider.

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.

Analytics: a segunda família exclusiva

RUNNER_ANALYTICS=amplitude   # ou mixpanel, ou none

Amplitude e Mixpanel respondem a mesma pergunta — volume de evento, usuários ativos, retenção — trocando de fonte. Então eles reusam as mesmas operações do catálogo e são mutuamente exclusivos, exatamente pelo mesmo motivo do bloco de observabilidade: duas fontes declarando a mesma operação fariam o Agent recusar subir, porque o despacho precisa saber para quem mandar.

A escolha é explícita e nunca inferida por credencial presente, pelo mesmo motivo de sempre: inferir daria um “meu Amplitude parou de responder” sem causa visível.

A Mixpanel serve 8 das 16 operações, e isso é desenho

Não existe API de Boards, o Insights só responde por bookmark de relatório salvo (sem listagem), e não há realtime nem métrica de sessão computada do lado do servidor. Num projeto Mixpanel, as ferramentas que dependem dessas operações somem da superfície do agente — em vez de devolverem uma lista vazia que se leria como “este projeto não tem dashboards”.

Cota

A Query API da Mixpanel permite 60 consultas por hora e 5 concorrentes, por projeto. O Amplitude não tem equivalente. O connector já trata isso: a leitura de volume tira a linha de base da mesma consulta em vez de fazer duas, e um 429 volta com o prazo de espera em vez de virar “a fonte caiu”.

Deploy: três fontes, três perguntas — nenhuma concorrente

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.

Argo CD: a terceira pergunta

ARGOCD_SERVER_URL=https://argocd-server.argocd.svc.cluster.local
ARGOCD_TOKEN=…

Se o seu backend vai para Kubernetes por GitOps, nem o GitHub nem a Vercel respondem o que importa. As três perguntas são distintas, e é por isso que os três connectors coexistem sem disputar nada:

Fonte	Responde
GitHub	que PR mergeou
Vercel	que artefato de front foi para o ar
Argo CD	que revisão o cluster está rodando

A terceira é a única que sobrevive à pergunta “o merge de ontem já está em produção?” — entre o merge e o deploy cabe o incidente inteiro.

Dois ganhos concretos: a revisão sincronizada é o commit, então deploy → commit → PR → diff sai direto, sem depender de casar tag de imagem; e o rollback é um evento no registro (uma sincronização para uma revisão já vista), em vez de algo a inferir de um commit de revert.

O servidor costuma ser interno ao cluster, e o Agent o alcança por rodar lá dentro. Use conta local com RBAC de leitura — ver Escopos e permissões.

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 e do Argo CD. 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.