Quando uma operação passa por uma requisição HTTP, uma fila e um ou mais serviços externos, seus registros ficam distribuídos entre processos distintos. Sem um dado comum, investigar um incidente exige fazer buscas por horário, usuário ou conteúdo, critérios que podem ser ambíguos ou sensíveis. Um identificador de correlação em PHP permite agrupar os eventos relacionados a uma operação e reconstruir seu percurso.
Para funcionar, o identificador precisa ter uma origem definida, ser transmitido explicitamente entre limites assíncronos e aparecer nos registros de forma consistente. Ele não é uma solução completa de observabilidade nem uma credencial: serve para relacionar eventos, não para explicar por si só o que falhou nem quem tem autorização.
O que resolve e o que fica de fora
Um identificador de correlação é um valor opaco associado a uma requisição ou operação. Ao incorporá-lo aos logs da aplicação, é possível localizar mensagens produzidas em diferentes componentes que compartilham esse valor. Por exemplo, é possível relacionar o recebimento de uma requisição ao despacho de um trabalho, ao seu consumo e à resposta de uma API externa.
Isso melhora o diagnóstico quando os logs estão centralizados e podem ser consultados por campos. No entanto, não garante que todos os componentes tenham registrado o identificador corretamente, nem mede duração, volume ou erros agregados. As métricas servem para tendências e alertas; os rastreamentos distribuídos mostram relações e tempos entre componentes; os logs fornecem eventos e contexto. São sinais complementares.
Correlação também não deve ser confundida com autenticação, autorização ou identidade do usuário. Conhecer um identificador não deveria dar acesso a dados nem permitir executar uma operação. Se o valor for exposto em uma URL ou em um sistema de terceiros, ele poderá ficar visível para mais pessoas do que o previsto.
Definir onde ele é gerado e como é validado
Em uma aplicação, o ponto habitual para iniciar o contexto é o middleware HTTP que recebe a requisição. Ele pode aceitar um identificador recebido para manter a continuidade com um proxy ou serviço anterior, ou gerar um novo quando não houver nenhum. A política deve ser explícita: confiar em todos os valores externos pode permitir entradas malformadas, excessivamente longas ou preparadas para contaminar os logs.
Para tráfego público, uma opção segura é sempre gerar um identificador interno e, se for necessário preservar o valor recebido, tratá-lo como dado não confiável e validá-lo rigorosamente. Outra alternativa é aceitar o valor do cabeçalho somente de componentes confiáveis, com regras configuradas no perímetro. A escolha depende da arquitetura e de quem pode chamar o serviço.
O formato deve ser fácil de validar e compatível com os sistemas que o transportam. É possível usar um valor aleatório gerado por uma fonte criptográfica do sistema, como random_bytes(), codificado em um conjunto limitado de caracteres. Não é recomendável construí-lo com marcas de tempo, endereços IP ou dados pessoais. Um identificador único não precisa revelar informações de negócio.
$correlationId = bin2hex(random_bytes(16));
Este exemplo gera um valor hexadecimal aleatório; ele não prescreve um formato universal. Defina um comprimento máximo, os caracteres permitidos e o cabeçalho que será usado pelos componentes, por exemplo, X-Correlation-ID. Se a plataforma já adota um padrão de rastreamento, evite criar um mecanismo paralelo sem necessidade: a correlação de logs e o contexto de rastreamento podem coexistir, mas não são conceitos idênticos.
Propagar o contexto por cada limite
No middleware, valide ou crie o identificador no início da requisição e adicione-o ao contexto de logging. Se ele for devolvido ao cliente em uma resposta, certifique-se de que nenhuma informação adicional seja exposta e de que a política de confiança esteja clara. O restante da aplicação deve receber o contexto por meio de uma dependência explícita, em vez de depender de variáveis globais difíceis de testar.
Dentro do processo PHP, passe o identificador aos serviços que registram eventos relevantes. Para trabalhos assíncronos, inclua-o nos metadados da mensagem ou em um campo dedicado do payload, conforme as convenções do sistema de filas. Ao consumir a mensagem, restaure o contexto antes de executar o trabalho e limpe-o ao terminar. Isso é especialmente importante em processos de longa duração, nos quais o mesmo worker atende mensagens sucessivas: um contexto que não foi limpo pode vazar para outra operação.
Ao chamar uma API externa, transmita o valor em um cabeçalho acordado somente se o provedor der suporte a isso e se for apropriado compartilhá-lo. Não envie dados internos desnecessários. Para integrações que não preservam cabeçalhos, registre o identificador junto com o resultado local da chamada; não presuma que o sistema remoto o devolverá nos próprios logs.
Se a requisição produzir vários trabalhos independentes, cada um poderá manter o identificador da operação de origem. Se, por outro lado, for necessário distinguir suboperações, adicione um identificador próprio para cada uma e mantenha a relação por meio do contexto de rastreamento ou de campos de negócio não sensíveis. Evite reutilizar o mesmo valor com semânticas diferentes sem documentar isso.
Usá-lo em logs estruturados, não como substituto da observabilidade
Registre o identificador como um campo estruturado, por exemplo, correlation_id, em vez de incorporá-lo apenas a uma frase de texto. Assim, uma plataforma de logs pode filtrar e agrupar eventos sem depender de buscas aproximadas. Mantenha uma convenção uniforme entre a aplicação, os workers e as integrações, e verifique se o serializador não o omite.
Inclua-o em eventos úteis para o diagnóstico: recebimento da requisição, criação da mensagem, início e fim do trabalho e resultado de uma chamada externa. Não é necessário repeti-lo em cada linha se o sistema oferecer contexto persistente por operação. Nesse caso, verifique se o contexto é redefinido entre requisições e se os registros continuam interpretáveis quando um componente não oferece suporte a ele.
Não use o identificador como rótulo de métricas de alta cardinalidade. Criar uma série temporal para cada requisição pode elevar o custo e tornar as métricas pouco úteis. Também não registre junto a ele tokens, senhas, dados de pagamento, o conteúdo completo de mensagens nem informações pessoais desnecessárias. Aplique as regras da organização para minimização, acesso e retenção de logs.
Tentativas, execuções adiadas e falhas
Uma nova tentativa do mesmo trabalho geralmente mantém o identificador de correlação original: ela continua fazendo parte da mesma operação lógica. Para distinguir as tentativas, registre um número de tentativa ou um identificador específico para ela, sem substituir o contexto original. Assim, é possível investigar tanto o percurso completo quanto a causa de cada execução.
Se um trabalho for agendado para ser executado muito mais tarde, mantenha o identificador como metadado persistente; não dependa do estado em memória do processo nem de uma sessão HTTP que já terminou. Se o trabalho iniciar uma operação nova e autônoma, defina se ele herdará o contexto de origem ou receberá um novo, e registre a relação entre ambos. Essa decisão evita que uma correlação ampla demais misture tarefas não relacionadas.
Quando a fila ou um serviço externo descartar metadados, documente esse limite e mantenha o contexto no componente que você controla. A aplicação deve continuar operável se o identificador estiver ausente: gere um ao entrar no processo ou registre claramente que o contexto não estava disponível.
Testes e verificações operacionais
- Teste o middleware com identificador ausente, válido e malformado; confirme que ele aplica a política definida e que o valor não excede os limites.
- Verifique se o identificador da requisição aparece nos logs dos serviços internos e nos metadados da mensagem enviada à fila.
- Execute uma mensagem em um worker e confirme que o contexto é incorporado aos logs e limpo antes da próxima mensagem.
- Simule uma nova tentativa e confirme que a correlação original é mantida e que é possível diferenciar a tentativa.
- Verifique a saída da chamada externa e o tratamento de erros, sem expor segredos nem corpos sensíveis nos registros.
- Revise se os dashboards e alertas não dependem da busca por identificadores individuais nas métricas.
Uma verificação de ponta a ponta deve acompanhar uma operação de teste desde a entrada HTTP até o trabalho e sua integração, consultando os logs pelo mesmo campo. Se ele estiver ausente em algum trecho, identifique o limite exato: middleware, serialização da mensagem, consumidor, cliente HTTP ou configuração do logger. Essa observação indica onde corrigir a propagação, em vez de adicionar registros indiscriminadamente.
A decisão prática é manter um contexto pequeno, explícito e não sensível, com regras claras de confiança e ciclo de vida. Assim, o identificador de correlação em PHP reduz o tempo de busca durante um incidente sem substituir controles de segurança, rastreamentos, métricas nem um desenho cuidadoso dos logs.
