O que registrar em log de integração, e o que nunca

Log de integração tem dois estados possíveis, e os dois são ruins: ou não tem o que você precisa na hora do incidente, ou tem dado que nunca deveria ter sido gravado.

O caminho do meio é decidir antes o que registrar, em vez de jogar o objeto inteiro no log e resolver depois.

O que nunca pode entrar

Credencial. Chave de API, token, senha. Parece óbvio e acontece o tempo todo, porque alguém registra o objeto de requisição inteiro e o cabeçalho Authorization vai junto.

Código de verificação. O conteúdo do SMS é justamente o que protege a conta. Log com OTP em texto é log que dá acesso — e log costuma ser lido por mais gente do que o banco.

Dado de cartão. Número completo e código de segurança não podem ser armazenados, nem cifrados. Isso vale para o log tanto quanto para a tabela.

Corpo inteiro de requisição, por padrão. É como quase todo vazamento de log começa. Se precisar do corpo para investigar, registre campos escolhidos, não o objeto.

Vale lembrar que log vai para lugares que você às vezes esquece: agregador de terceiro, ferramenta de erro, backup, tela de suporte.

O que precisa entrar

O critério é simples: o que você vai querer ter quando algo quebrar às duas da manhã.

Um identificador que atravesse tudo. Um identificador de requisição gerado na entrada e propagado por toda chamada seguinte. Sem ele, você tem eventos soltos e nenhuma história.

O identificador do pedido do lado da plataforma. É por ele que o suporte encontra o caso.

Qual chamada externa foi feita, com rota e método. Sem valores sensíveis.

Status e duração. Duração é o que revela degradação antes de virar falha.

Qual tentativa. Se houve retentativa, o número dela. Três tentativas invisíveis viram três segundos de latência que ninguém consegue explicar.

Motivo da falha, classificado. Não a mensagem crua: uma categoria sua — saldo_insuficiente, fornecedor_indisponivel, limite_excedido. Categoria dá para contar e gerar alerta; texto livre, não.

Mascarar, não omitir

Omitir o campo dificulta a investigação. Mascarar preserva a forma sem entregar o conteúdo.

Telefone vira +5511*****8888 — dá para conferir se é o número certo sem expor. Chave vira ac_live_****3f2a, o suficiente para saber qual chave era. E-mail vira f****@dominio.com, que já diz o provedor.

O código do SMS não se mascara: registra-se apenas que chegou, com o horário. O conteúdo nunca.

Nível certo

Erro é para o que exige ação humana. Se ninguém precisa fazer nada, não é erro. Log de erro cheio de coisa normal treina o time a ignorar erro.

Aviso é para o que se recuperou sozinho mas indica desgaste — retentativa que funcionou na terceira, fornecedor que caiu e o failover cobriu.

Informação é para marco de negócio: pedido criado, SMS recebido, estorno feito.

Depuração é para desenvolvimento, e não deveria estar ligado em produção — é onde o corpo inteiro costuma vazar.

Estruture

Log em texto corrido é legível por humano e inútil para máquina. Estruturado, você filtra por identificador, conta por categoria e cria alerta.

A diferença prática aparece no incidente: com texto, você lê. Com estrutura, você pergunta "quantos falharam por fornecedor indisponível na última hora, por fornecedor" e tem a resposta em um comando.

Guarde pelo tempo certo

Log é dado pessoal quando contém endereço de origem, telefone ou identificador de usuário — e a LGPD se aplica.

Guardar para sempre é passivo: aumenta o estrago de um vazamento e o custo de armazenamento, sem benefício depois de certo ponto.

Defina prazo por tipo, e apague de verdade quando vencer. Descarte que não roda é política que não existe.

Um teste rápido

Pegue o log da última semana e procure por Bearer, por authorization, por sequências de seis dígitos isoladas e por dezesseis dígitos seguidos.

Se achar alguma coisa, você tem duas tarefas: parar de gravar, e considerar comprometido o que já foi gravado.

Se você tem chave exposta em log, o passo seguinte está em onde a chave de API nunca pode estar — inclusive o detalhe de descobrir por onde ela saiu antes de criar a nova.

Se a integração for com números virtuais, o identificador do pedido é o que vale gravar em cada linha — é por ele que qualquer investigação começa.