Introdução: por que os logs da camada de proxy merecem uma conversa à parte

Imagine a situação. À noite, a conversão do seu parser cai um terço, de manhã a equipe de segurança pergunta quem acessou o quê através do gateway de proxy corporativo anteontem, e ao meio-dia o jurídico quer saber por que os arquivos guardam URLs completas com tokens de acesso de clientes dos últimos dois anos. As três perguntas esbarram na mesma entidade — os logs da camada de proxy. E quase sempre a conclusão é que os logs ou não contêm o necessário, ou contêm o que não deveriam, ou estão armazenados de um jeito que torna impossível encontrar qualquer coisa em tempo razoável.

Já falamos sobre observabilidade do pool de proxies: métricas de sucesso, latência por nó, alertas de degradação, dashboards. Aquilo é uma conversa sobre como o sistema se sente no geral. O tema de hoje é diferente. A métrica vai te dizer que a taxa de erros 429 subiu de dois para quatorze por cento. O log vai dizer qual conta exata, através de qual IP de operadora móvel, com qual cabeçalho User-Agent e em qual segundo recebeu aquela resposta. Métricas respondem à pergunta "o que está acontecendo"; logs respondem à pergunta "o que exatamente aconteceu e com quem". Aqui falamos exclusivamente sobre o conteúdo dos registros, o corte de dados sensíveis, a rotação de arquivos e a política de prazos de retenção.

Por que isso é crítico justamente agora? Primeiro, os volumes. O gateway de proxy médio, mesmo de uma equipe pequena de automação de marketing, gera de algumas centenas de milhares a dezenas de milhões de requisições por dia. Uma linha adicionada sem pensar no formato do log se multiplica por esses milhões. Segundo, a regulação. As exigências da legislação de proteção de dados estão ficando mais rígidas, e a camada de proxy é justamente onde identificadores de usuários, cookies e cabeçalhos de autorização passam em texto aberto. Terceiro, a economia. Armazenar terabytes de logs em índice quente de busca custa dinheiro, e muitas vezes esse dinheiro vai para dados que ninguém nunca vai consultar.

Neste guia você vai aprender: quais campos são obrigatórios em cada registro de log de proxy e por quê; quais dados jamais podem ser gravados, nem "por via das dúvidas"; como estruturar mascaramento e hashing para que os logs continuem úteis em investigações; como montar rotação e armazenamento em camadas; como definir um prazo de retenção que agrade engenheiros, pessoal de segurança e advogados. Vamos entregar templates prontos, checklists e analisar casos reais com números. Acomode-se — o material ficou extenso, mas cada parte dele é comprovada na prática.

Fundamentos: o que é um log da camada de proxy e do que ele é feito

Definição e lugar na arquitetura

A camada de proxy é o componente entre a sua aplicação (parser, gerenciador de contas, sistema de automação de contas de anúncios) e o mundo externo, que recebe uma requisição, escolhe um endereço de saída do pool, envia a requisição e devolve a resposta. Se você trabalha com proxies móveis, essa camada ainda gerencia a rotação de IP, a vinculação de sessões a contas e a troca entre operadoras.

O log da camada de proxy é uma sequência de registros, cada um descrevendo um evento nesse componente. Na maioria das vezes, o evento é uma requisição HTTP processada, mas eventos também são a troca de IP, o erro de conexão com um nó upstream, a rejeição de uma requisição por regra de acesso, a inicialização e a parada do processo.

Uma analogia útil é o diário de bordo de um navio. Nele não se copia o conteúdo do porão, mas se registra cada mudança de rumo, o horário, as coordenadas, as condições climáticas e quem estava de plantão. Do mesmo jeito, um bom log de proxy não guarda o corpo da requisição, mas registra tudo aquilo que permite reconstruir o percurso do evento.

Tipos de logs dentro da camada de proxy

Na prática, identificam-se quatro fluxos, e misturá-los em um único arquivo é o primeiro erro do iniciante:

  • Access log (log de acesso) — um registro para cada requisição processada. O fluxo mais volumoso, principal fonte para investigações e cobrança.
  • Error log (log de erros) — eventos que exigem atenção: impossibilidade de conectar ao nó upstream, timeouts, esgotamento do pool, queda do processo. O volume é dezenas ou centenas de vezes menor que o access log, e o valor por registro é maior.
  • Audit log (log de auditoria) — quem alterou a configuração, quem emitiu um token de acesso, quem adicionou ou removeu um nó do pool. Grava-se pouco, mas guarda-se por mais tempo.
  • Rotation/session log (log de rotação) — fluxo específico de proxies móveis: quando e por qual motivo o IP mudou, qual operadora, qual sessão está vinculada a qual conta. Sem ele, é impossível responder por que uma conta recebeu uma verificação de segurança.

Níveis de logging

Os níveis clássicos — DEBUG, INFO, WARN, ERROR, FATAL — também funcionam aqui, mas com uma nuance. Para o access log, o nível quase não faz sentido: cada requisição é INFO. Os níveis fazem sentido para o error log e eventos internos. Regra prática: em produção, a camada de proxy roda em INFO; o DEBUG é ligado pontualmente, para um cliente ou nó específico, e por tempo limitado. Por quê? Porque o modo DEBUG em proxy muitas vezes significa despejar todos os cabeçalhos, e isso é caminho direto para vazamento de dados de autorização em arquivos.

Formatos: texto versus estrutura

Há dez anos, o padrão era o formato de texto tipo Common Log Format, com campos separados por espaços. Hoje, o consenso do mercado é inequívoco: logs estruturados, geralmente em JSON, com cada campo nomeado. Os motivos são simples. Um registro estruturado pode ser filtrado por qualquer campo sem expressões regulares, é entendido por todos os sistemas de coleta e, o que importa para o nosso tema, permite remover ou mascarar campos específicos com facilidade. Tente extrair um cabeçalho Authorization de uma linha de texto onde ele pode ter caído em qualquer posição e você vai entender do que estou falando.

Aprofundamento: anatomia do registro e natureza dos riscos

Três perguntas que cada registro deve responder

Antes de discutir campos concretos, combinemos um critério. Um registro no access log da camada de proxy é útil se permite responder a três perguntas:

  1. Quem? Qual cliente, qual conta ou perfil, qual serviço interno iniciou a requisição.
  2. Através de quê? Qual nó de saída, qual IP, qual operadora, qual sessão foi usada.
  3. O que deu? Código de resposta, duração, volume de dados transferidos, se houve nova tentativa.

Repare: nessa lista não há a pergunta "o que exatamente foi transmitido". O conteúdo da requisição e da resposta são dados da aplicação, não da camada de proxy. A camada de proxy é transporte, e deve registrar eventos de transporte. Esse é um princípio fundamental de separação de responsabilidades, e a maioria dos problemas com dados sensíveis em logs vem justamente de violá-lo.

Identificadores e correlação

O campo mais valioso em um log moderno é o identificador de correlação (request ID ou trace ID). É uma string única que a aplicação gera ao criar a requisição e passa para a camada de proxy através de um cabeçalho interno. O proxy grava essa string no seu log, e a aplicação grava no dela. Resultado: você consegue vincular em segundos o evento no parser, o evento no proxy e o evento no sistema de rotação de IP. Sem correlação, você vai correlacionar registros por horário com precisão de segundo — e com dezenas de milhares de requisições por segundo, isso é missão impossível.

O segundo identificador mais importante é o identificador de sessão. Em proxies móveis, sessão é o período em que as requisições de uma conta específica passam pelo mesmo IP. É a sessão que vincula o access log ao log de rotação. Se uma conta foi bloqueada, você olha as sessões dela, vê que em uma hora mudaram três IPs de regiões diferentes e entende a causa.

Categorias de dados sensíveis no tráfego de proxy

Vamos detalhar o que exatamente passa pela camada de proxy e representa risco ao cair em logs:

  • Dados de autorização: cabeçalhos Authorization, Proxy-Authorization, Cookie, Set-Cookie, X-API-Key e similares. Um token no log equivale a um token em acesso aberto para qualquer um com acesso aos logs — e esse círculo costuma ser bem mais amplo do que o de pessoas com acesso aos segredos.
  • Dados pessoais na URL: endereços de e-mail em parâmetros de busca, telefones, identificadores de usuários de plataformas externas, nomes em caminhos. Aí entram as exigências da legislação de proteção de dados, e os logs se tornam um armazenamento sujeito a controle.
  • Credenciais do próprio proxy: login e senha de autenticação no proxy, que o cliente envia no cabeçalho. O cenário clássico de vazamento é o proxy gravar a string de conexão completa no formato user:pass@host no error log quando a conexão falha.
  • Corpos de requisição e resposta: formulários de login, dados de pagamento, conteúdo de mensagens pessoais. Em configuração normal, a camada de proxy não deveria vê-los, mas na hora de depurar a tentação de ligar o dump é grande.
  • Identificadores indiretos: a combinação de User-Agent, IP do cliente e horário exato permite desanonimizar uma pessoa mesmo sem dados pessoais explícitos. Reguladores em várias jurisdições classificam essas combinações como dados pessoais.

A dimensão jurídica

Aqui é preciso cuidado. Se pela sua camada de proxy passam dados de usuários — clientes do seu serviço, assinantes, compradores —, os logs que contêm identificadores deles se tornam tratamento de dados pessoais, com todas as obrigações decorrentes: finalidade definida, prazo limitado, proteção no armazenamento, localização. Logs não são "lixo técnico", como muita gente os enxerga. São um banco de dados, só com estrutura incomum. A solução de engenharia aqui é simples: minimizar os dados pessoais nos logs ao ponto em que deixem de ser pessoais — via hashing e tokenização, que veremos adiante. Com isso, a carga jurídica sobre os logs cai radicalmente.

A economia do registro

Outra dimensão é o dinheiro. Tomemos um gateway hipotético de dez milhões de requisições por dia. Um registro em JSON compacto, sem campos desnecessários, pesa cerca de trezentos bytes. Isso dá três gigabytes por dia, cerca de noventa por mês. Adicione a URL completa com todos os parâmetros e todos os cabeçalhos da requisição — e o registro infla para um e meio a dois kilobytes. Já são vinte gigabytes por dia e seiscentos por mês. Se esses dados ficam em índice quente de busca com replicação, a diferença de custo é de ordem de magnitude. Cada campo no esquema do log é uma decisão financeira tomada para os próximos anos.

Método 1: projetar o esquema do registro — o que é obrigatório gravar

Princípio da suficiência mínima

O esquema do log não se projeta a partir da pergunta "o que conseguimos gravar", mas da pergunta "a que perguntas precisamos saber responder". Faça a lista dos cenários de investigação e verifique se cada um é coberto pelos campos existentes. Cenários típicos para a camada de proxy: entender um bloqueio de conta, descobrir a causa do aumento de erros, cobrança por cliente, verificação de cumprimento de limites, investigação de incidente de segurança, comprovar que uma requisição específica não passou por você.

Campos obrigatórios do access log

Abaixo está o núcleo do esquema que recomendamos como mínimo para qualquer camada de proxy. Cada campo vem com a explicação do porquê:

  • ts — timestamp em UTC com milissegundos, formato ISO 8601. Nada de fuso local: em um pool distribuído, os nós ficam em regiões diferentes, e o horário local tornaria a correlação impossível.
  • req_id — identificador de correlação, recebido do cliente ou gerado pelo proxy caso o cliente não o tenha enviado.
  • client_id — identificador interno do cliente ou serviço autenticado no proxy. Não é login nem senha, mas sim a chave interna.
  • profile_id — identificador da conta ou perfil em nome do qual a requisição é feita, se o seu sistema trabalha com essas entidades. É esse campo que vincula o log à lógica de negócio de multi-contas.
  • session_id — identificador da sessão de proxy, que vincula a requisição a um período específico de vínculo com um IP.
  • upstream_id — identificador do nó de saída no pool. Não o IP em si, mas o código interno dele: um IP pode ser reutilizado, um código não.
  • upstream_ip_hash — hash do IP de saída com salt. Permite agrupar requisições por endereço sem guardar o endereço aberto por muito tempo.
  • carrier e region — operadora e região do nó de saída, para proxies móveis. É crítico para analisar o comportamento das plataformas em relação a diferentes operadoras.
  • method — método HTTP.
  • host — domínio de destino. Domínio, não URL completa.
  • path_template — caminho com as partes variáveis substituídas, por exemplo /users/{id}/posts. Mantém o valor analítico sem vazar identificadores.
  • status — código de resposta do servidor de destino.
  • proxy_status — status interno de processamento: sucesso, timeout para o nó upstream, rejeitado por regra, pool esgotado. Separa erros do servidor de destino dos erros do próprio proxy.
  • duration_ms — tempo total de processamento; útil também dividir em tempo de conexão, tempo até o primeiro byte e tempo de transferência.
  • bytes_in e bytes_out — volume de dados transferidos. Base para cobrança e busca de anomalias.
  • retry — número da tentativa, se o proxy faz novas tentativas.
  • tls — versão do TLS e indicador de handshake bem-sucedido.
  • ua_class — não o User-Agent em si, mas sua classe: navegador móvel, desktop, aplicativo. O User-Agent completo, quando necessário, fica em um cadastro à parte, sob um código curto.

Exemplo de registro

É assim que fica um registro construído com esse esquema:

{"ts":"2026-03-14T08:21:37.412Z","req_id":"01HRX7K9M2P4Q","client_id":"c_0412","profile_id":"p_88213","session_id":"s_7f3a91","upstream_id":"n_msk_017","upstream_ip_hash":"a91f...c2","carrier":"op_a","region":"ru-mow","method":"GET","host":"example-platform.com","path_template":"/api/v2/feed/{id}","status":200,"proxy_status":"ok","duration_ms":842,"ttfb_ms":611,"bytes_in":1204,"bytes_out":48211,"retry":0,"tls":"1.3","ua_class":"mobile_android"}

Trezentos e poucos bytes. Nenhum segredo, nenhum identificador pessoal de usuários externos, mas o quadro completo do evento. Com esse registro dá para responder a todos os seis cenários de investigação da lista acima.

Campos obrigatórios do log de rotação

Para proxies móveis, o log de rotação é tão importante quanto o access log. O esquema mínimo: timestamp, session_id, upstream_id, motivo da rotação (por agendamento, por solicitação do cliente, por erro, por atingir o limite de requisições), hash do IP antigo e do novo, operadora, duração da sessão anterior, número de requisições na sessão anterior. É por esse log que você vai entender que a conta recebeu uma verificação não pelo conteúdo das ações, mas porque em dez minutos o IP mudou quatro vezes.

Passo a passo para implantar o esquema

  1. Liste os cenários de investigação relevantes para a sua equipe. Pelo menos cinco.
  2. Para cada cenário, defina o conjunto mínimo de campos que o cobre.
  3. Junte os conjuntos e remova as duplicatas. Esse é o rascunho do esquema.
  4. Passe por cada campo com a pergunta: ele contém segredo, dado pessoal ou identificador indireto? Se sim, substitua por hash, classe ou template.
  5. Registre o esquema em um documento versionado. Cada registro deve conter o campo schema_version.
  6. Implemente validação: um registro fora do esquema deve ser rejeitado na etapa de montagem do log, e não descoberto seis meses depois.
  7. Rode uma carga de teste e meça o tamanho médio do registro. Multiplique pelo volume diário e compare com o orçamento de armazenamento.

Método 2: cortar os dados sensíveis — o que nunca gravar

Lista negra de campos

Comecemos pelas proibições absolutas. Esses dados não devem entrar em nenhum fluxo de logs da camada de proxy, em nenhum nível, incluindo DEBUG:

  • Valores dos cabeçalhos Authorization, Proxy-Authorization, Cookie, Set-Cookie, e de qualquer cabeçalho cujo nome contenha key, token, secret ou session.
  • Credenciais de conexão ao proxy em qualquer forma, incluindo strings no formato user:pass@host.
  • Corpos de requisição e resposta. Por completo. Se para depurar for preciso ver o corpo, isso se faz do lado da aplicação, em armazenamento temporário, com exclusão automática.
  • A query string completa com parâmetros. Parâmetros regularmente contêm e-mail, telefone, tokens de links de uso único.
  • O User-Agent completo combinado com o IP do cliente — isso é uma impressão digital que permite identificar a pessoa.
  • Endereços IP abertos de usuários finais do seu serviço, se a camada de proxy atender não só processos internos.

Quatro técnicas de anonimização

Proibir é fácil. O difícil é preservar o valor analítico. Aqui vai o ferramental que permite isso:

Redação (redaction)

Substituição total do valor por um marcador como [REDACTED]. Aplica-se ao que não tem valor analítico: cabeçalhos de autorização, senhas. Detalhe importante: a redação precisa ocorrer na etapa de montagem do registro, dentro do processo do proxy, e não em pós-processamento dos arquivos. Pós-processamento significa que o segredo já chegou ao disco e entrou em buffers, backups e replicações.

Mascaramento (masking)

Ocultação parcial mantendo o formato. E-mail i***@d*****.br, telefone +55 9** **** 12 34. Permite que um operador de suporte reconheça os dados por comparação, mas não os recupere do log. Aplica-se onde é necessária verificação visual humana e, honestamente, na camada de proxy isso é raro. Muitas vezes o mascaramento é um meio-termo para equipes que ainda não estão prontas para o hashing.

Hashing com salt

O valor é substituído pelo resultado de uma função de hash criptográfico com salt secreto. Valores iguais geram hashes iguais, então agrupamento e contagem de únicos continuam funcionando, mas a recuperação do valor original sem o salt é impossível. Essa é a ferramenta principal para endereços IP, identificadores de usuário de plataformas externas, User-Agent completo. Requisito fundamental: o salt fica guardado separado dos logs, em um gerenciador de segredos, e é rotacionado periodicamente. Ao rotacionar o salt, perde-se a possibilidade de correlacionar hashes antigos e novos — é um preço consciente pela segurança, e o período de rotação do salt em geral coincide com o prazo de retenção dos logs detalhados.

Tokenização

O valor é substituído por um token aleatório, e a correspondência token-valor fica em um armazenamento separado e protegido, com controle rígido de acesso. Diferente do hashing, é reversível — mas só para quem tem acesso à tabela de correspondência. Aplica-se quando a investigação de um incidente pode exigir a recuperação do valor original por decisão de um responsável de segurança. Por exemplo, a URL completa da requisição em caso de suspeita de abuso. A tabela de correspondência vive por um prazo próprio, mais curto.

Template de caminhos

Vamos parar um momento nos caminhos de URL. O caminho /users/88213/messages/4471 contém dois identificadores. Gravá-lo inteiro é preservar dados pessoais indiretos. Gravar só o domínio é perder a analítica por endpoint. Solução: template de caminho. Segmentos numéricos, UUIDs, strings longas com cara de hash são substituídos por placeholders: /users/{id}/messages/{id}. A analítica por tipo de requisição se mantém por completo, e os identificadores desaparecem. Implementa-se com um conjunto de regras de substituição aplicadas na etapa de montagem do registro.

Onde exatamente acontece o corte

A arquitetura correta pressupõe três linhas de defesa:

  1. No processo do proxy: o formador do log conhece o esquema e simplesmente não pega campos proibidos. Essa é a linha principal.
  2. No agente de coleta: regras de filtragem que buscam padrões de segredos (strings do tipo Bearer seguidas de uma sequência longa, construções tipo JWT, números de cartão pela fórmula de Luhn) e as substituem por marcadores. É a proteção contra erros do desenvolvedor que adicionou um campo novo.
  3. No armazenamento: um scanner periódico que procura padrões de segredos nos dados já salvos e dispara alertas. É um detector, não um filtro: se ele encontrou algo, as duas primeiras linhas foram furadas e é preciso investigar.

Checklist de corte de dados sensíveis

  • Cabeçalhos de autorização e cookies são redigidos dentro do processo, não em pós-processamento.
  • Credenciais do proxy nunca entram no error log, incluindo mensagens de erro de conexão.
  • Corpos de requisição e resposta não são registrados em nenhum nível.
  • A query string é descartada ou transformada em template.
  • Endereços IP são hasheados com salt; o salt fica separado e é rotacionado.
  • Caminhos de URL são convertidos em templates por regras.
  • O User-Agent é substituído por classe ou código de cadastro.
  • O agente de coleta tem regras de busca de padrões de segredos.
  • O armazenamento é escaneado periodicamente em busca de segredos.
  • O modo DEBUG é ativado para um client_id específico, por tempo limitado, com desligamento automático.

Método 3: rotação e armazenamento em camadas

Para que serve a rotação

Rotação de logs é o fechamento periódico do arquivo atual e a abertura de um novo, seguidos de compressão, movimentação ou exclusão dos antigos. Sem rotação, o arquivo cresce sem limite, e fica impossível lê-lo, comprimi-lo ou apagá-lo seletivamente, além de um disco cheio derrubar o próprio processo do proxy. Parece básico, mas na nossa experiência não menos de um terço dos incidentes de indisponibilidade de gateways de proxy caseiros está relacionado justamente a disco cheio por causa de logs.

Critérios de rotação

O arquivo é fechado quando um dos critérios ocorrer primeiro:

  • Por tamanho — normalmente de cem megabytes a um gigabyte. Menos que isso gera arquivos demais; mais, demora para comprimir e é ruim de transferir.
  • Por tempo — uma hora para gateways de alta carga, um dia para os pequenos. A rotação temporal torna os nomes de arquivo previsíveis e facilita a busca.
  • Por evento — reinício do processo, mudança de versão do esquema. Um arquivo não deve conter registros de dois esquemas diferentes.

Prática recomendada: rotacionar por tempo com limite de tamanho. Por exemplo, a cada hora, mas no máximo quinhentos megabytes por arquivo. O nome inclui nó, fluxo e timestamp de início: access-gw-msk-01-2026031408.jsonl.

Mecânica sem perdas

Um detalhe crítico que muita gente esquece: a rotação não deve causar perda de registros. O erro clássico é renomear o arquivo e criar um novo enquanto o processo continua escrevendo no descritor antigo. As abordagens corretas: o próprio processo abre um arquivo novo quando a condição ocorre (rotação embutida); ou o rotacionador externo envia um sinal para o processo reabrir o arquivo depois de renomeá-lo; ou, preferível nas arquiteturas modernas, o processo escreve na saída padrão e o agente de coleta captura o fluxo e gerencia os arquivos por conta própria. A terceira opção retira do processo do proxy toda a responsabilidade sobre o disco.

Compressão

Logs JSON estruturados comprimem maravilhosamente — a taxa típica vai de oito a quinze vezes, graças aos nomes de campos repetidos e ao conjunto limitado de valores. Isso significa que um gigabyte de logs crus vira setenta a cem megabytes de arquivo. Escolha do algoritmo: para arquivos que serão lidos com frequência, algoritmos rápidos com compressão moderada; para arquivo morto, compressão máxima. Comprima não logo após fechar o arquivo, mas com um atraso de um a dois períodos de rotação: os arquivos recentes costumam ser necessários para análise rápida.

Modelo de armazenamento em camadas

Aqui chegamos à ideia central do armazenamento econômico. Nem todos os logs têm a mesma demanda. O acesso aos registros é extremamente desigual: a esmagadora maioria das consultas aos logs se refere às últimas 24 horas, uma parcela relevante à última semana, e apenas consultas isoladas a dados com mais de um mês. Guardar tudo em armazenamento igualmente caro e rápido é desperdício. Daí o modelo em camadas:

Camada quente

Últimas 24 horas — três dias. Índice de busca completo, todos os campos indexados, resposta à consulta em segundos. É a camada mais cara por gigabyte. Aqui ficam investigações operacionais, depuração, análise de incidentes recentes.

Camada morna

De três a trinta dias. Dados em formato colunar comprimido em armazenamento de objetos, busca através de um motor que lê os arquivos diretamente. Resposta à consulta em dezenas de segundos, mas custo de armazenamento uma ordem de magnitude menor. Aqui ficam relatórios semanais, análise de reclamações de clientes, análise de tendências de bloqueio.

Camada fria

De trinta dias até o fim do prazo de retenção. Arquivos comprimidos na classe mais barata de armazenamento de objetos, possivelmente com latência de acesso. Busca apenas por horário exato e nó, seguida de descompactação e análise manual. Aqui ficam solicitações jurídicas, auditoria, investigações de incidentes antigos.

Agregados

Uma camada separada da qual muita gente esquece. Antes de excluir os registros detalhados, calculam-se agregados a partir deles: número de requisições, distribuição de códigos de resposta, duração média — por cliente, nó, domínio, hora. Os agregados ocupam frações de por cento do volume dos detalhados e são guardados por anos. São eles que permitem responder "como era há um ano" sem guardar um ano de registros detalhados.

Passo a passo para configurar rotação e camadas

  1. Defina o fluxo de saída do processo do proxy: saída padrão para o agente de coleta é preferível a gravar direto em arquivo.
  2. Configure a rotação por tempo (hora ou dia) com limite de tamanho.
  3. Defina a compressão com atraso de um a dois períodos após o fechamento do arquivo.
  4. Separe os fluxos: access, error, audit, rotation — em arquivos ou índices distintos.
  5. Configure a movimentação para a camada morna por idade do arquivo, com conversão para formato colunar.
  6. Configure a movimentação para a camada fria e a exclusão ao atingir o prazo de retenção.
  7. Implemente o cálculo diário de agregados a partir da camada quente e a gravação deles em armazenamento de longa duração separado.
  8. Crie alertas de espaço livre em disco no nó e de atraso de envio ao agente de coleta: se os logs não saem, eles se acumulam localmente.
  9. Trimestralmente, confira que a exclusão realmente acontece: conte o arquivo mais antigo de cada camada.

Método 4: política de prazos de retenção

Três forças que definem o prazo

O prazo de retenção de logs é um compromisso entre três forças que puxam para lados diferentes. Os engenheiros querem guardar mais tempo: nunca se sabe quando será preciso analisar um incidente antigo. O financeiro quer guardar menos: cada gigabyte custa dinheiro. Segurança e jurídico são o lado mais interessante: ao mesmo tempo exigem guardar por tempo suficiente para investigações e por tempo curto o bastante para não acumular dados cuja vazamento gerará responsabilização. Cada registro com dados pessoais guardado além do necessário é um passivo, não um ativo.

Princípio: o prazo depende da sensibilidade e da demanda

Fluxos diferentes e campos diferentes vivem tempos diferentes. Essa é a ideia-chave da seção. Não existe um "prazo de retenção de logs" único — existe uma matriz de prazos:

  • Access log detalhado: de quatorze a noventa dias. A demanda cai exponencialmente, a sensibilidade é média mesmo após a anonimização.
  • Error log: de trinta a cento e oitenta dias. O volume é pequeno, o valor para análise de problemas recorrentes é alto.
  • Audit log: de um a três anos. Quem alterou a configuração e emitiu acessos — são dados requisitados em investigações muito tempo depois. O volume é ínfimo.
  • Rotation log: o mesmo que o access log — um sem o outro não faz sentido.
  • Tabela de tokenização: mais curta que os próprios logs — de sete a trinta dias. Passado o prazo, os tokens nos logs se tornam irreversíveis.
  • Agregados: de dois a cinco anos. Não contêm dados pessoais, ocupam pouco espaço, são valiosos para analítica de longo prazo.

Como calcular o prazo para a sua situação

Propomos um framework prático de cinco perguntas:

  1. Qual é o cenário de investigação realista mais longo? O cliente reclama de um bloqueio de conta ocorrido há três semanas — logo, os logs detalhados são necessários por no mínimo vinte e um dias, mais uma margem.
  2. Existem obrigações externas? Contratos com clientes podem exigir guardar registros de acesso por determinado prazo para resolver disputas de cobrança. Exigências de reguladores para operadores de certas categorias de dados também podem estabelecer mínimos.
  3. Quais dados nos logs continuam sensíveis após a anonimização? Se foi aplicado hashing com rotação de salt, a sensibilidade após a rotação cai quase a zero, e o armazenamento pode ser prolongado.
  4. Quanto custa o armazenamento em cada camada? Calcule o custo de um mês de armazenamento quente, morno e frio no seu volume. Muitas vezes se descobre que um ano de logs em armazenamento frio custa menos do que uma semana em quente.
  5. O que se perde ao excluir? Se os agregados cobrem a analítica de longo prazo, os registros detalhados podem ser excluídos sem receio.

Suspensão jurídica da exclusão

Elemento obrigatório da política é o mecanismo de suspensão da exclusão (legal hold). Se foi iniciada uma investigação de incidente ou recebida uma solicitação oficial, a exclusão automática do período afetado deve ser congelada até o fim da apuração. Tecnicamente, é um flag no arquivo ou prefixo no armazenamento de objetos, que o processo de exclusão verifica. Organizacionalmente, é um regramento de quem tem o direito de colocar e retirar esse flag. Sem esse mecanismo, você vai se ver na situação de ter os dados necessários excluídos por agendamento justamente no dia em que foram precisos.

Documentação da política

A política de retenção é um documento, não uma configuração em arquivo de config. Conteúdo mínimo: lista dos fluxos de logs e campos; para cada um, a finalidade da coleta, o prazo de retenção em cada camada, o método de anonimização; responsáveis pela política e pela sua execução; procedimento de suspensão da exclusão; procedimento de verificação de que a exclusão acontece; periodicidade de revisão — normalmente uma vez por ano ou quando o esquema mudar. Esse documento é a primeira coisa que um auditor vai pedir e a primeira que vai te proteger em um incidente: ele mostra que os dados foram tratados com critério.

Template da matriz de retenção

Preencha para o seu caso uma tabela com as colunas: fluxo, campos com sensibilidade, método de anonimização, camada quente (dias), camada morna (dias), camada fria (dias), agregados (meses), fundamento do prazo, responsável. Uma linha por fluxo. A matriz pronta cabe em uma página e resolve noventa por cento das discussões entre equipes.

Erros típicos: o que não fazer

Registrar tudo "por via das dúvidas"

O erro mais comum e mais caro. O argumento "melhor ter e não usar" não funciona com logs: dados não usados custam dinheiro, criam risco de vazamento e transformam o armazenamento em um lugar onde é impossível achar o necessário em meio ao desnecessário. Cada campo deve responder a uma pergunta concreta da lista de cenários.

Ligar o DEBUG em produção e esquecer de desligar

O modo DEBUG em proxy quase sempre significa despejar cabeçalhos. Ativado numa sexta à noite para investigar um problema, na segunda-feira ele já encheu o disco com tokens de autorização de todos os clientes. Regra: o DEBUG é ativado com filtro e com timer de desligamento automático.

Gravar segredos em mensagens de erro

O desenvolvedor monta a mensagem de erro de conexão e insere nela a string de conexão completa — com login e senha. E o error log é guardado por mais tempo que o access log e consultado por mais gente. Revise todos os pontos de formação de mensagens de erro em busca de interpolação de credenciais.

Misturar fluxos em um único arquivo

Access, error e audit em um arquivo só significa que registros de audit, que deveriam viver três anos, são apagados junto com os de access em um mês, e que registros de access, que deveriam ser comprimidos, ficam misturados com registros de error esparsos, que precisam ser lidos a olho nu.

Guardar o horário em fuso local

Nós do pool em regiões diferentes, mudança de horário de verão em algumas jurisdições, comparação com logs de sistemas externos — tudo isso quebra no horário local. Só UTC, só ISO 8601.

Anonimizar em pós-processamento

Um script que passa à noite pelos arquivos removendo tokens é o reconhecimento de que os tokens ficaram o dia inteiro no disco em texto aberto e ainda passaram por buffers do agente de coleta, réplicas e, possivelmente, backups. Anonimização é na etapa de montagem do registro.

Não verificar que a exclusão funciona

A política está escrita, o prazo definido, a automação configurada — e dois anos depois você descobre que, por uma mudança de permissões no bucket, a exclusão vinha falhando silenciosamente e o armazenamento contém todo o histórico. Verificar o arquivo mais antigo de cada camada é um ritual trimestral.

Guardar o salt de hashing junto com os logs

Salt no arquivo de configuração do proxy, no mesmo repositório ou no mesmo disco, é o mesmo que não ter salt. Nesse caso, IPs hasheados são recuperados por força bruta em minutos. O salt vai para o gerenciador de segredos, com acesso restrito e rotação.

Registrar a URL completa

A query string é um concentrado de dados sensíveis: e-mail em parâmetros de busca, tokens de links de uso único, identificadores de usuário. Domínio mais caminho em template é suficiente para qualquer analítica de transporte.

Ferramentas e recursos

Servidores proxy e suas capacidades de logging

A maioria dos servidores proxy maduros e proxies reversos suporta formato configurável de access log, incluindo saída em JSON, e permite excluir ou sobrescrever campos via configuração. Na escolha, preste atenção em três coisas: a possibilidade de emitir log estruturado sem formato de texto intermediário; a possibilidade de adicionar ao registro um cabeçalho de correlação vindo do cliente; e a possibilidade de proibir completamente o registro de cabeçalhos específicos no nível da configuração, não do código. Se a camada de proxy for caseira, o que não é raro em sistemas de gestão de proxies móveis, use a biblioteca de logging estruturado da sua linguagem com suporte a processadores de registro — é no processador que se implementam a redação e o hashing.

Agentes de coleta

O agente de coleta é o processo no nó que lê a saída do proxy, aplica filtros e envia registros para o armazenamento. Critérios-chave de escolha: suporte a regras de substituição por expressões regulares para a segunda linha de defesa; buffer em disco quando o armazenamento estiver indisponível, para não perder registros; baixo consumo de recursos, porque o agente vive ao lado do processo do proxy no mesmo nó; suporte a roteamento de fluxos diferentes para destinos diferentes.

Armazenamentos e motores de busca

Para a camada quente, servem índices de busca com busca full-text por campo ou bancos analíticos colunares, que nos últimos anos vêm substituindo os índices clássicos graças à melhor compressão e velocidade de agregação. Para as camadas morna e fria, armazenamento de objetos com formato de arquivo colunar e motor de consulta que os lê diretamente. Escolha armazenamento de objetos com políticas de ciclo de vida: a transição automática entre classes de armazenamento e a exclusão por idade se resolvem por configuração, sem código próprio.

Ferramentas de anonimização

Uma classe separada de ferramentas são os scanners de segredos, originalmente criados para encontrar chaves em repositórios de código. Seus motores de padrões também se aplicam a logs: encontram tokens, chaves de provedores de nuvem, strings tipo JWT. Configurado para rodar periodicamente sobre o armazenamento, um scanner desses vira a terceira linha de defesa. Para template de caminhos e hashing não existem ferramentas especializadas — são algumas dezenas de linhas no processador de log.

Gestão de segredos

O salt para hashing e a tabela de tokenização devem viver em um gerenciador de segredos com registro de acesso. Pode ser tanto a solução de um provedor de nuvem quanto um armazenamento de segredos implantado por conta própria. O critério é poder dar ao processo do proxy acesso ao salt sem que um humano tenha acesso ao valor dele.

O que ler e no que se orientar

Os pontos de referência são os guias do mercado de logging seguro das comunidades de segurança aplicada, onde há listas exaustivas de dados proibidos em logs; a documentação dos reguladores sobre minimização de dados pessoais; e as recomendações de armazenamento em camadas dos provedores de nuvem, que trazem cálculos de custo. Vale também ler os materiais sobre especificações de rastreamento distribuído — é de lá que se deve tirar o formato dos identificadores de correlação.

Casos e resultados

Caso 1: equipe de automação de marketing, redução de seis vezes no volume de logs

Situação inicial: gateway para trabalhar com contas de anúncios através de um pool de proxies móveis, cerca de quatro milhões de requisições por dia. Os logs eram gravados em formato de texto com URL completa, todos os cabeçalhos da requisição e o primeiro kilobyte do corpo da resposta "para depurar". O registro médio tinha cerca de dois kilobytes, o volume diário era de oito gigabytes, tudo em índice quente de busca com retenção de noventa dias. O custo do índice era uma linha notável no orçamento de infraestrutura.

O que fizeram: migração para o esquema JSON de vinte campos descrito acima. Cabeçalhos, corpo e query string foram descartados. Os caminhos viraram templates. Foram introduzidas camadas: três dias quente, trinta morno, noventa frio. Foram implementados agregados por hora com retenção de três anos.

Resultado: registro médio de trezentos e vinte bytes, volume diário de 1,3 gigabyte, e cerca de cem megabytes por dia após compressão na camada morna. O custo de armazenamento caiu aproximadamente oitenta e cinco por cento. Efeito colateral inesperado: a velocidade de análise de incidentes aumentou, porque os analistas pararam de se afogar em cabeçalhos e passaram a ver imediatamente os campos essenciais. E dois meses depois, o scanner de segredos implantado como terceira linha encontrou nos arquivos antigos mais de doze mil tokens ativos de contas de anúncios — foram revogados e reemitidos.

Caso 2: serviço de scraping de marketplaces, investigação de bloqueios pelo log de rotação

Situação: a equipe raspa cards públicos de produtos através de proxies móveis e enfrenta uma onda de bloqueios em parte das sessões. As métricas mostram aumento de erros, mas não a causa. O access log existe; o log de rotação, não.

O que fizeram: adicionaram o log de rotação com motivo da troca de IP e duração da sessão, e o vincularam ao access log via session_id. Em dois dias de dados já ficou visível: as sessões bloqueadas em esmagadora maioria tinham duração inferior a três minutos — a rotação disparava por um timer agressivo, e a plataforma de destino via o mesmo perfil vindo de três IPs diferentes em um intervalo curto. Sessões com mais de vinte minutos eram bloqueadas três vezes menos.

Resultado: após reconfigurar a rotação, a fatia de sessões bloqueadas caiu de onze para menos de três por cento. O custo: cerca de quarenta bytes por registro de rotação, dez mil registros por dia — um volume que nem se nota diante do access log. Conclusão que consideramos importante: para proxies móveis, o log de rotação não é opcional, é fluxo obrigatório.

Caso 3: plataforma com clientes externos, adequação dos logs às exigências de dados pessoais

Situação: o serviço oferece acesso proxy a clientes, e por ele passam requisições de usuários finais dos clientes. Nos logs: IPs de usuários finais, User-Agents completos, URLs completas. A auditoria jurídica classifica os logs como base de dados pessoais com prazo de retenção de um ano.

O que fizeram: IPs substituídos por hashes com salt, rotacionado a cada trinta dias; User-Agent trocado por código de cadastro; URL reduzida a domínio e template de caminho. Foi montada uma matriz de retenção com justificativa dos prazos. Foi introduzido o mecanismo de suspensão da exclusão. Os logs detalhados ficaram limitados a quarenta e cinco dias, e os agregados, a três anos.

Resultado: após a rotação do salt, os logs com mais de trinta dias deixaram de conter dados que permitam identificar o usuário mesmo indiretamente e foram retirados do escopo de base de dados pessoais. O volume de obrigações de proteção diminuiu, e a capacidade de analisar incidentes do último mês se manteve integralmente. A auditoria aceitou a matriz de retenção como comprovação suficiente de tratamento criterioso.

Caso 4: incidente de disco cheio

Curto, mas ilustrativo. Um gerenciador de proxy caseiro gravava logs em arquivo sem rotação. Em quatro meses, o arquivo chegou a quarenta gigabytes, o disco do nó encheu, o processo caiu ao tentar gravar e um pool de vinte modems ficou parado por três horas durante a noite. Depois do incidente: saída para a saída padrão, agente de coleta com buffer, rotação por hora, alerta de espaço livre. Nunca mais se repetiu. O custo da solução foi um dia de trabalho.

FAQ: perguntas difíceis sobre logs da camada de proxy

É preciso registrar requisições bem-sucedidas ou só os erros bastam?

É preciso. Requisições bem-sucedidas são a base para cobrança, para calcular a proporção de erros (sem denominador, a fração não faz sentido), para analisar o comportamento das plataformas em relação a diferentes operadoras e para comprovar que uma requisição específica não passou por você. A economia deve estar no tamanho do registro, não na quantidade deles. Se o volume for mesmo inaceitável, aplique amostragem: registre todos os erros e cada décima requisição bem-sucedida com um flag de amostragem, para multiplicar pelo fator na agregação.

Como investigar um incidente se o IP está hasheado e o salt já foi rotacionado?

Essa é uma fronteira consciente. Após a rotação do salt, os dados se tornam irreversíveis — nisso está o valor de proteção. Investigações que exigem recuperar o IP devem caber no período de vigência do salt, normalmente coincidente com o prazo de retenção detalhada. Se os seus cenários de investigação costumam ultrapassar esse período, aumente o período de rotação do salt, mas com a consciência de que isso prolonga o tempo em que os logs continuam sensíveis. Para investigações realmente longas, use simultaneamente o mecanismo de suspensão da exclusão e o salt.

Qual a diferença entre logs da camada de proxy e tracing?

O tracing descreve o caminho de uma requisição por vários serviços com intervalos de tempo aninhados. O log descreve um evento em um componente. Os dois se complementam por meio do identificador de correlação comum: pelo trace você vê que a requisição passou oitocentos milissegundos na camada de proxy; pelo log, você vê por que: quinhentos na conexão com o nó upstream, duzentos no TLS, cem na transferência. Não tente substituir um pelo outro.

Vale a pena criptografar os logs no armazenamento?

Sim, em todas as camadas. Mesmo logs anonimizados contêm informação de negócio: quais domínios você acessa, com que intensidade, através de quais operadoras. A criptografia do lado do armazenamento é configuração padrão em armazenamentos de objetos, ativada por um flag. Além disso, limite o acesso à camada quente por papéis: analistas veem agregados e campos anonimizados; responsáveis de segurança veem tudo.

Como lidar com logs ao operar em várias regiões?

Grave o horário em UTC e a região do nó em um campo separado. O armazenamento pode ser centralizado ou regional, conforme as exigências de localização de dados: se pela camada de proxy passam dados de usuários de determinada jurisdição, os logs com identificadores anonimizados deles podem cair na exigência de armazenamento nessa jurisdição. Confirme com o jurídico antes do projeto, não depois.

Posso usar logs de proxy para cobrança de clientes?

Pode e deve, com duas ressalvas. Primeira: a cobrança se baseia em agregados, não em registros detalhados — somas por client_id por período. Os agregados vivem mais tempo e não contêm dados sensíveis. Segunda: se o log é base para cálculos com clientes, ele fica sujeito a exigências de imutabilidade — registros não são editados depois do fato, arquivos recebem somas de verificação, e o acesso de escrita é exclusivo do processo de coleta.

Como garantir que um campo novo adicionado por um desenvolvedor não contenha segredo?

Processualmente: toda alteração no esquema de log passa por revisão com a pergunta obrigatória sobre a sensibilidade de cada campo novo, e a versão do esquema é incrementada. Tecnicamente: a segunda linha de defesa no agente de coleta detecta padrões de segredos independentemente do nome do campo, e a terceira — o scanner do armazenamento — sinaliza se algo escapou. Além disso, é útil ter um teste que passa pelo formador do log uma requisição com um token falso conhecido e verifica que o token não apareceu na saída.

O que fazer com os logs quando um nó sai do pool?

Os logs do nó ficam no armazenamento até o fim do prazo de retenção — eles descrevem eventos que aconteceram, e excluí-los junto com o nó quebra a integridade do histórico. Os buffers locais do nó devem ser enviados ao armazenamento antes do desligamento, e para isso o procedimento de saída inclui a espera pelo esvaziamento do buffer do agente de coleta. O identificador do nó não é reutilizado para novos nós, caso contrário os registros de dois dispositivos diferentes se misturam.

Como avaliar se a política de retenção está adequada?

Trimestralmente, faça três verificações. Primeira: pegue os cinco últimos incidentes e confirme que, para cada um, os dados necessários estavam disponíveis na camada correta. Segunda: conte quantas consultas aos logs no trimestre se referiram a dados com mais de trinta dias; se for zero, a camada fria pode ser reduzida. Terceira: confirme que o arquivo mais antigo de cada camada não é mais velho que o prazo estabelecido. Se as três verificações passarem, a política está adequada.

Conclusão: logs como sistema projetado, não subproduto

Vamos reunir o essencial. Os logs da camada de proxy não são algo que "se grava sozinho", mas um sistema projetado, com esquema próprio, fronteiras próprias e ciclo de vida próprio. Ele responde às perguntas "quem", "através de quê" e "o que deu", e por princípio não responde à pergunta "o que foi transmitido" — essa é responsabilidade da aplicação.

O que gravar: timestamp em UTC, identificadores de correlação, cliente, perfil e sessão, código do nó, IP anonimizado, operadora e região, método, domínio e template de caminho, códigos de resposta e de status interno, durações, volumes, número da tentativa. Para proxies móveis — log de rotação obrigatório com motivo da troca de IP.

O que não gravar: cabeçalhos de autorização e cookies, credenciais do proxy, corpos de requisição e resposta, URLs completas com parâmetros, User-Agents completos combinados com IP, endereços abertos de usuários finais. Anonimização — dentro do processo, com duas linhas adicionais de defesa no agente de coleta e no scanner do armazenamento.

Como armazenar: fluxos separados, rotação por tempo com limite de tamanho, compressão, camadas do quente ao frio com agregados na saída, matriz de prazos por fluxo, mecanismo de suspensão da exclusão e verificação regular de que a exclusão acontece.

Próximos passos que recomendamos fazer nesta semana. Primeiro: extraia cem registros aleatórios do seu log atual e passe por eles o checklist de corte de dados sensíveis — o resultado provavelmente vai te surpreender. Segundo: calcule o tamanho médio do registro e multiplique pelo volume diário e pelo prazo de retenção; compare com o que seria usando o esquema deste guia. Terceiro: monte uma matriz de retenção de uma página e mostre a segurança e jurídico — é uma conversa que é melhor ter antes de um incidente do que depois.

Logs são a memória da sua infraestrutura. Uma boa memória lembra o importante, esquece o desnecessário e não guarda o que pode fazer mal. Projete-a exatamente assim.