Provedor GlitchTip — observabilidade (baseline)¶

Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-09-10

O que é¶

O GlitchTipProvider é a impl de FeatureProvider para a feature glitchtip da Central de Apps. Quando o /xadm-setup chama POST /api/setup/provision {app_id, feature:"glitchtip"}, o auth garante (idempotente) o projeto GlitchTip do app em bug.xadm.biz e devolve o DSN (client-grade) no client_config — que o setup grava no app.json.

A API do GlitchTip é compatível com Sentry: criar projeto por POST /api/0/teams/{org}/{team}/projects/, ler o DSN por GET /api/0/projects/{org}/{slug}/keys/ (dsn.public).

Configuração (env no recurso `auth` no Coolify)¶

Todas environment variables do serviço (runtime), marcando só o token como Secret:

Env	Valor	Secret
`GLITCHTIP_ADMIN_URL`	`https://bug.xadm.biz` (ou URL interna, se o `auth` não alcançar de dentro)	não
`GLITCHTIP_ADMIN_TOKEN`	Auth Token do GlitchTip (Profile → Auth Tokens; gerar logado como owner da org)	sim
`GLITCHTIP_ORG`	slug da organização (ex. `x-adm`)	não
`GLITCHTIP_TEAM`	slug do time (ex. `xadm`)	não

Ausentes → o provider recusa provisionar com erro claro (GLITCHTIP_ADMIN_URL ...), sem quebrar o boot; o par fica em estado falha + last_error, re-tentável quando as envs existirem.

Comportamento¶

Slug derivado do nome: o GlitchTip ignora o slug enviado e deriva o slug do nome do projeto (ex. "Auth Service" → central-backend). Por isso o provider descobre o slug real: lista GET /api/0/projects/ e casa por (org + nome) — não assume slug == app_id.
Idempotente: acha o projeto pelo nome; existe → reusa. Não existe → cria (POST .../teams/{org}/{team}/projects/, com platform derivado da stack) → re-lista p/ pegar o slug → lê o DSN em .../projects/{org}/{slug}/keys/ (dsn.public do 1º key).
Sem segredo per-app: o DSN é a chave pública (client-grade) — não vai secret_ref. O SENTRY_AUTH_TOKEN (upload de sourcemap) é org-wide e é env de build do app, não gerido aqui.
Alerta padrão (best-effort): ao garantir o projeto, o provider também garante um alerta padrão — notifica a cada 1 evento em 1 minuto por e-mail aos membros do projeto (POST .../projects/{org}/{slug}/alerts/, corpo camelCase timespanMinutes:1, quantity:1, alertRecipients:[{recipientType:"email"}]). Idempotente (não recria se o projeto já tem algum alerta) e best-effort: falha aqui só loga (WARN) — nunca quebra a provisão do DSN, que é o entregável. Um projeto que já tinha alerta próprio é respeitado.
Falha do provedor (inacessível, resposta inesperada) → falha + last_error, sem config parcial.

Alerta de silêncio do integrador-client¶

O próprio central emite, no seu projeto GlitchTip, um evento por episódio de silêncio de uma instalação do integrador-client — uma issue por cliente, reincidências na mesma issue (decisão 0028, runbook heartbeat do integrador-client). A reincidência só notifica se a regra de alerta do projeto for por evento — o alerta padrão acima ("1 evento em 1 minuto").

Como o provider respeita alerta próprio pré-existente, confira o projeto do central antes de ligar o heartbeat: em Alerts do projeto, a regra tem de disparar por quantidade de eventos, não só em "issue nova". Se for só "issue nova", troque pela regra por evento — senão o 2º silêncio de um cliente cai calado na issue antiga.

Verificação¶

# provisiona o glitchtip do próprio auth (dogfood) e confere o DSN na resposta
curl -s -X POST https://auth.xadm.biz/api/setup/provision \
  -H "Authorization: Bearer <JWT xadm_admin>" -H "Content-Type: application/json" \
  -d '{"app_id":"auth","feature":"glitchtip","grupo":"xadm","nome":"Auth"}' | jq .
# → { "client_grade": { "enabled": true, "dsn": "https://<pub>@bug.xadm.biz/<n>" } }

Re-executar o mesmo comando deve devolver o mesmo DSN (idempotente), sem criar projeto novo.

Reversão¶

deprovision não implementado (política: não destrói recurso por default). Para desligar, o admin desliga a capacidade no par (o auth para de servir o bloco no /config); o projeto GlitchTip permanece em bug.xadm.biz até remoção manual.