Alertas do conector

Para: Dev — Conferido em 2026-10-18.

O que medir e alertar no seu conector para saber, em minutos, se o dinheiro do seu produto e o do Dracma continuam batendo. Os limiares abaixo são pontos de partida: ajuste ao seu volume.

O que é

Um conjunto mínimo de sinais de saúde do dinheiro e de saúde do receptor. Cada sinal responde a uma pergunta: o dinheiro está parado? Está duplicado? O Dracma e o meu livro divergiram? O meu receptor está de pé?

O Dracma tem os próprios alertas por operação (entregas em DLQ, caixa baixo, regras em revisão), descritos em Alertas e e-mails. Os alertas desta página são seus: só o conector sabe, por exemplo, que um intento ficou pendente por tempo demais.

Quando usar

Configure-os antes do go-live (Checklist de go-live) e dispare cada um de teste uma vez, para provar que o aviso chega a uma pessoa. Alerta que nunca foi disparado de teste não conta como configurado.

Como funciona

Saúde do dinheiro

Sinal Limiar sugerido Severidade O que significa e o que fazer
Intento do outbox pendente há mais que 10 minutos P2 O Dracma está fora ou a chamada está falhando. Veja os 5xx e 429; confira GET /v1/ping. O worker já repete com a mesma chave
Fila de decisão manual (needs_decision) com caso parado Mais de 4 horas: aviso. Mais de 24 horas: crítico P2, depois P1 Um humano precisa decidir um estorno, devolução ou pagamento tardio (Política de exceções)
Fetch-back incoerente com o intento (id, valor, moeda ou jogador diferentes) Qualquer ocorrência P1 Pode ser bug ou ataque. Não credite; investigue pelo trace_id
Reconciliação diária com divergência Qualquer divergência P1 Os livros não batem. Não "conserte" o seu livro para bater: congele e investigue (Reconciliar com o seu livro)
Crédito sem depósito paid correspondente Qualquer ocorrência P1 É o desvio mais grave: dinheiro creditado que o Dracma não liquidou
Mais de um crédito para o mesmo external_id Qualquer ocorrência P1 A restrição de unicidade do seu livro deveria impedir; se aparecer, o dedup falhou
Caixa livre da operação abaixo do mínimo que você define Defina pelo seu volume de saques P2 GET /v1/balances: caixa livre é available menos pending_out. Saque sem caixa recebe 422 insufficient_operation_balance (Saldos e caixa livre)
Saques em processing há muito tempo Defina pelo seu SLA com o jogador P2 O PSP pode estar lento; o Dracma não reenvia sozinho um saque em andamento (Ciclo do saque)

Saúde do receptor e da integração

Sinal Limiar sugerido Severidade O que significa e o que fazer
Webhook com assinatura inválida Mais de 0 em 5 minutos P2 Ataque, ou rotação de segredo mal feita. Confira os segredos ativos (Segredo e rotação)
401 ou 403 nas chamadas do conector ao Dracma Mais de 0 P2 Credencial, relógio ou operação suspensa. 403 operation_suspended pede o suporte
Desvio de relógio (server_time do GET /v1/ping) Mais de 5 segundos P2 Fora de 300 s todas as chamadas dão 401. Confira o NTP
Job de GET /v1/events sem sucesso Mais de 15 minutos P2 Webhooks perdidos não estão sendo recuperados
Atraso do poller (agora menos created_at do último evento aplicado) Defina; 15 minutos é um bom começo P2 O conector está atrasado em relação ao Dracma
Fração de 5xx e 429 do Dracma nas suas chamadas Defina pela sua linha de base P2 429 é o seu próprio ritmo; 5xx persistente é incidente do lado do Dracma (Limites e quotas)
Entregas de webhook em dlq ou em tentativas altas Qualquer entrega em dlq P2 O seu receptor ficou fora do ar por mais de 72 horas, ou está recusando. Reentregue pelo painel (Webhooks no painel)

Métricas sugeridas

Nomes de exemplo para as métricas do seu conector; use a convenção do seu produto.

Métrica Tipo Rótulos
conector_dracma_outbox_pendentes e conector_dracma_outbox_idade_maxima_segundos Gauge kind (deposit, withdrawal)
conector_dracma_chamadas_total Counter rota, status
conector_dracma_webhook_verificacao_total Counter resultado (ok, assinatura_invalida, fora_da_janela, id_divergente, duplicado)
conector_dracma_eventos_atraso_segundos Gauge nenhum
conector_dracma_fetchback_divergente_total Counter tipo
conector_dracma_decisoes_abertas e conector_dracma_decisoes_idade_maxima_segundos Gauge motivo
conector_dracma_reconciliacao_divergencias Gauge dia
conector_dracma_desvio_relogio_segundos Gauge nenhum

Logs e rastreio

  • Registre o Dracma-Trace-Id de toda resposta de erro, e o trace_id do corpo do problem+json. É o que o suporte pede (Suporte).
  • Em todo registro de dinheiro inclua external_id, o id do Dracma, o Dracma-Event-Id e a version aplicada.
  • Nunca registre o segredo, o header Dracma-Signature inteiro, CPF completo nem chave PIX em claro.
  • Registre a decisão do aplicador de estado ("aplicado", "duplicado", "versão antiga", "incoerente"). Sem isso, uma divergência de reconciliação não tem como ser explicada.

Exemplos

Verificação de relógio, para rodar a cada minuto e alertar com desvio acima de 5 segundos (exemplo em Go, do pacote de Exemplos executáveis):

cd exemplos/go && DRACMA_KEY_ID=key_test_SEU_ID DRACMA_KEY_SECRET_FILE=/caminho/seguro/segredo go run ./cmd/ping

A saída traz desvio= e o programa avisa no erro padrão quando o desvio passa de 5 segundos.

Regra de alerta para o outbox, em pseudoconfiguração:

alerta: conector_dracma_outbox_idade_maxima_segundos{kind="withdrawal"} > 600
por: 2 minutos
severidade: P2
mensagem: saque pendente há mais de 10 minutos; veja o trace_id do último erro

Erros e casos de borda

  • Alerta com ruído é alerta ignorado: se o P2 do outbox dispara toda vez que o Dracma fica 11 minutos fora, aumente o tempo ou agrupe.
  • Não alerte por 429 isolado: ele é o limitador funcionando. Alerte pela taxa.
  • Reconciliação com divergência no dia de hoje durante a madrugada pode ser só o dia ainda aberto: 409 day_open não é divergência (Reconciliação).
  • Um alerta crítico de dinheiro deve acordar alguém. Um P2 pode esperar o horário comercial.

Veja também