Como usar referências externas e correlação para investigar uma ocorrência

Um erro aconteceu na sua aplicação. E agora? Essa pergunta parece simples até você abrir os eventos disponíveis e encontrar centenas de registros do mesmo período, produzidos por serviços diferentes, com nomes parecidos e sem uma ligação evidente entre eles.

Você consegue encontrar a mensagem de erro, mas ainda não sabe qual pedido foi afetado, qual pagamento estava em andamento ou quais outras etapas fizeram parte da mesma tentativa. Sem referências e correlação, sua investigação depende de copiar identificadores entre sistemas, estimar horários e separar manualmente o sinal do ruído.

Uma investigação de eventos fica mais objetiva quando cada ocorrência carrega referências que você consegue usar depois. A referência externa liga o evento a uma entidade do seu domínio. A correlação liga eventos que pertencem à mesma sessão, transação ou fluxo. Com filtros por tipo e janelas de tempo, você transforma essas relações em um caminho prático para reconstruir o que aconteceu.

Comece pela ocorrência, não pela lista inteira

O primeiro evento que você encontra raramente conta a história completa. Ele é um ponto de partida. Pode ser um erro de processamento, uma falha de integração ou uma operação que terminou em um estado inesperado.

Antes de abrir registros aleatórios, anote o que a ocorrência já informa:

• qual é o type do evento;
• em qual ambiente e projeto ele aconteceu;
• qual é o timestamp registrado;
• se existe uma referência externa;
• se existe um identificador de correlação;
• quais propriedades podem orientar a próxima busca.

Esses dados ajudam você a formular uma pergunta menor. Em vez de procurar “tudo que aconteceu quando o sistema falhou”, você pode procurar “quais eventos afetaram este pedido durante esta janela de processamento?”. Uma investigação boa reduz o espaço de busca a cada passo.

O que é uma referência externa

Uma referência externa conecta um evento a uma entidade que existe fora do registro de eventos. Pode ser um pedido, pagamento, usuário, assinatura, arquivo, projeto ou qualquer objeto que tenha significado para o seu produto.

Na Eyedux, essa referência é representada por external_object. Ela pode informar:

• id: o identificador da entidade no seu sistema;
• property: a propriedade usada para identificar essa entidade, como id, order_code ou outra chave;
• source: a origem do identificador, como uma tabela, serviço ou sistema externo.

O valor da referência está em você conseguir sair do evento e chegar ao objeto que explica o impacto. Se um erro de processamento aponta para o pedido afetado, você não precisa inferir a entidade a partir de uma mensagem de texto ou procurar o código do pedido em todos os campos.

Uma referência não é apenas um valor solto

Registrar somente um identificador em uma propriedade já pode ajudar, mas uma referência estruturada preserva mais contexto. Ao informar a propriedade e a origem, você reduz a ambiguidade de valores que podem se repetir em sistemas diferentes.

Compare estas duas situações:

• properties.order_id = "1625441789654-02", sem explicar qual sistema ou chave está sendo usada.
• external_object apontando para a propriedade id da origem de pedidos correspondente.

A primeira situação registra um dado útil. A segunda transforma esse dado em uma relação que sua equipe pode consultar e interpretar de forma consistente.

O que é correlação de eventos

Correlação é a relação entre ocorrências que fazem parte de uma mesma execução ou jornada. Um usuário pode iniciar uma sessão, a aplicação pode criar uma transação, um worker pode processar uma mensagem e um serviço externo pode devolver uma resposta. Esses eventos podem ter tipos e entidades diferentes, mas ainda pertencer ao mesmo fluxo.

Na Eyedux, essa relação é representada por correlation_object. Assim como uma referência externa, ela pode carregar um id, uma property e uma source. A diferença está na pergunta que ela responde:

• Referência externa: qual entidade do seu domínio este evento afetou?
• Correlação: a qual execução, sessão, transação ou fluxo este evento pertence?

Um mesmo pedido pode aparecer em várias tentativas de processamento. A referência externa pode ser a mesma, enquanto a correlação muda para cada tentativa ou execução. Separar os dois conceitos permite investigar tanto o histórico da entidade quanto uma ocorrência específica daquele histórico.

Escolha uma correlação que sobreviva ao fluxo

O identificador de correlação precisa ser propagado pelos componentes que participam da mesma jornada. Se o serviço que recebe a requisição cria um identificador, os workers e integrações envolvidos precisam recebê-lo e enviá-lo nos eventos que produzem.

Prefira um identificador estável dentro do fluxo e evite usar o timestamp como correlação. Horários ajudam a limitar a busca, mas não garantem que eventos com o mesmo instante pertençam à mesma execução. Também evite criar um identificador novo a cada etapa se o objetivo é reconstruir a jornada inteira.

Se você não envia a correlação no momento da instrumentação, a Eyedux não consegue inventar essa relação depois. É possível investigar por entidade, tipo e tempo, mas a conexão será uma hipótese baseada em contexto, não uma relação explícita registrada pela aplicação.

Referência externa e correlação trabalham juntas

Imagine que o evento inicial indique que o pedido 7efc4ca0-52e4-4cfc-8a30-5fb0217ad6ab falhou durante o processamento. A referência externa leva você ao pedido. Se os eventos relacionados também carregarem a correlação order-run-2026-09-04-0031, você consegue separar essa tentativa de outras tentativas do mesmo pedido.

{
  "type": "order.processing.failed",
  "type_group": "orders",
  "external_object": {
    "id": "7efc4ca0-52e4-4cfc-8a30-5fb0217ad6ab",
    "property": "id",
    "source": "database:business_xpto.orders"
  },
  "correlation_object": {
    "id": "order-run-2026-09-04-0031",
    "property": "run_id",
    "source": "worker:orders-ingestion"
  },
  "environment": "production"
}

Nesse exemplo, external_object identifica a entidade afetada e correlation_object identifica a execução que reuniu os eventos. Um evento de “processamento iniciado”, outro de “integração consultada” e o erro final podem ter tipos diferentes, mas ainda assim ser encontrados pela mesma correlação.

Essa combinação é especialmente útil quando uma entidade participa de muitos fluxos. Filtrar apenas pelo pedido pode misturar uma tentativa atual com ocorrências antigas. Filtrar apenas pela correlação pode omitir o contexto de negócio. Usar os dois recortes permite alternar entre o objeto afetado e a jornada específica.

Como os filtros reduzem o ruído

Depois de identificar uma referência ou correlação, use filtros para restringir a consulta. A Eyedux oferece filtros por type, external_object e correlation_object, além de intervalos de tempo relativos ou personalizados.

Filtre pelo tipo quando souber a etapa

Se você sabe que está investigando falhas no processamento, filtre pelo tipo order.processing.failed. Esse recorte evita que eventos informativos, de debug ou de outros fluxos ocupem as primeiras páginas da consulta.

O filtro por tipo funciona melhor quando sua taxonomia é estável. Se cada serviço usa uma grafia diferente para a mesma etapa, você terá de repetir consultas ou ampliar o intervalo até incluir nomes que deveriam representar um único fluxo. A nomenclatura definida no artigo anterior é parte da qualidade desta investigação.

Filtre pela referência externa

Use external_object quando sua pergunta for sobre uma entidade: “o que aconteceu com este pedido?”, “quais eventos afetaram este pagamento?” ou “em qual etapa este usuário encontrou o erro?”. A busca pelo identificador externo direciona a consulta para os eventos associados àquela entidade.

Confira se você está usando a propriedade e a origem corretas. O mesmo valor textual pode representar um ID de banco, um código público ou uma chave de outro sistema. A referência estruturada existe justamente para preservar essa diferença.

Filtre pela correlação quando a pergunta for sobre uma execução

Use correlation_object quando a pergunta for “quais etapas fizeram parte desta tentativa?”. Esse filtro é útil para investigar uma transação, sessão, job, ingestão ou fluxo que atravessa vários serviços.

Se o primeiro evento contém a correlação, use o detalhe desse evento para copiar o identificador e pesquisar os demais registros. Se a correlação está ausente, combine o tipo, a referência externa e o período como uma aproximação consciente, deixando claro que a relação não foi enviada explicitamente.

Comece com um intervalo relativo

Intervalos relativos são uma forma rápida de testar uma hipótese. Para uma falha recente, você pode começar pelos últimos 15 minutos, uma hora ou 24 horas. A Eyedux também oferece períodos maiores, como 7, 30, 90 dias e um ano, quando você precisa observar recorrência.

Começar com uma janela curta reduz o volume e acelera a leitura. Se o evento não aparecer ou se a etapa anterior tiver acontecido antes do esperado, amplie o período gradualmente. Uma janela ampla demais logo no início pode esconder a sequência relevante entre registros não relacionados.

Use um intervalo personalizado para reconstruir a sequência

Quando você conhece o timestamp da ocorrência, defina um intervalo personalizado com início e fim. Inclua tempo suficiente antes do erro para capturar a origem e depois dele para capturar retries, respostas e efeitos posteriores.

Não trate o timestamp como uma ordem absoluta entre sistemas. Relógios, filas e processamento assíncrono podem produzir eventos fora da ordem que você imaginava. Use a data para limitar a busca e os tipos, referências, propriedades e correlação para interpretar a sequência.

Um passo a passo de investigação

1. Registre o ponto de partida. Anote o tipo, timestamp, ambiente, projeto e qualquer identificador presente na ocorrência. Se o evento foi reportado por uma pessoa, preserve também o contexto da reclamação ou alerta.
2. Abra o detalhe do evento. Consulte as propriedades, metadados, referência externa e correlação. O detalhe ajuda você a trocar uma mensagem genérica por identificadores que podem ser reutilizados nas próximas consultas.
3. Identifique a entidade afetada. Se houver external_object, busque os eventos associados ao mesmo objeto. Confirme se a propriedade e a origem correspondem à entidade que você está investigando.
4. Identifique a execução. Se houver correlation_object, use o mesmo identificador para encontrar as etapas da sessão, transação ou job. Esse é o recorte que separa uma tentativa específica de outras ocorrências da entidade.
5. Defina uma janela inicial. Comece com um intervalo relativo curto ou com alguns minutos antes e depois do timestamp conhecido. Amplie somente se a sequência estiver incompleta.
6. Filtre por tipo. Procure primeiro os eventos que representam etapas relevantes, como início, sucesso, retry, resposta externa e falha. Evite misturar todos os tipos enquanto ainda está formando a hipótese.
7. Ordene e pagine os resultados. Use a ordenação por data para ler a sequência e avance pelas páginas quando necessário. A paginação evita assumir que os primeiros resultados representam todo o histórico.
8. Compare a sequência com o comportamento esperado. Procure a primeira divergência: uma etapa que não aconteceu, uma resposta inesperada, uma repetição ou uma mudança de entidade. A causa pode estar antes do erro visível.
9. Abra os eventos decisivos. A consulta lista o contexto suficiente para navegar; o detalhe do evento é onde você confirma propriedades, referências e dados técnicos antes de concluir.

Esse processo não exige que você comece sabendo a causa. Ele transforma a investigação em uma série de perguntas verificáveis: qual entidade foi afetada, qual execução estava em andamento, quais etapas ocorreram e em que momento a sequência deixou de ser esperada.

Agrupe por tipo quando o caso vira padrão

Nem toda investigação termina em uma única ocorrência. Depois de examinar um caso, você pode querer saber se o mesmo tipo aparece com frequência, quando foi registrado pela última vez ou quais tipos concentram a atividade na janela escolhida.

A consulta de logs da Eyedux pode retornar agrupamentos por tipo. Nesse modo, o resultado representa grupos com contagem e timestamp mais recente, em vez de cada evento individual. Isso ajuda você a decidir onde aprofundar a investigação antes de abrir centenas de detalhes.

O agrupamento responde “quais tipos aparecem e com que frequência?”. A consulta detalhada responde “o que aconteceu nesta ocorrência?”. Use cada uma no momento adequado e não confunda contagem por tipo com prova de causalidade. Um tipo frequente pode ser normal; um tipo raro pode ser crítico.

Como a Eyedux apoia esse fluxo

A Eyedux reúne os mecanismos necessários para transformar essas perguntas em consultas operacionais:

• filtro por type para restringir a etapa ou ocorrência investigada;
• filtro por external_object para buscar eventos ligados a uma entidade do seu sistema;
• filtro por correlation_object para acompanhar uma execução ou jornada;
• intervalos relativos e personalizados para controlar o período da busca;
• ordenação por data e paginação para percorrer o histórico sem carregar tudo de uma vez;
• agrupamento por tipo para identificar padrões antes de abrir cada evento;
• consulta do detalhe para confirmar propriedades, metadados e referências da ocorrência.

O resultado depende da instrumentação da sua aplicação. A Eyedux consegue consultar e organizar as referências que você envia, mas não consegue associar retroativamente um evento a um pedido ou fluxo se essa informação nunca foi registrada.

Isso não é distributed tracing completo

Referências externas e correlação oferecem contexto para investigação, mas não substituem uma solução completa de distributed tracing. Elas não formam automaticamente uma árvore de spans, não medem todas as relações de causa entre serviços e não reconstroem a topologia de uma requisição sem que você a instrumente dessa forma.

O que você ganha é uma estrutura explícita para responder perguntas operacionais importantes: qual entidade foi afetada, qual fluxo estava em andamento, quais eventos ocorreram perto do erro e quais tipos apareceram na mesma janela. Para muitos incidentes de aplicação, esse contexto já reduz bastante o tempo gasto procurando sinais espalhados.

Também há limites práticos. Identificadores inconsistentes quebram a busca, referências ausentes obrigam você a trabalhar com hipóteses e janelas muito grandes aumentam o ruído. Por isso, defina um contrato de instrumentação: quais eventos carregam cada referência, como os IDs são propagados e quais propriedades devem acompanhar os tipos mais importantes.

Da ocorrência ao histórico que explica o problema

Investigar um erro não é apenas encontrar a mensagem que falhou. É reconstruir o contexto suficiente para explicar o que a aplicação tentou fazer, qual entidade foi afetada e em qual execução a falha apareceu.

external_object conecta seus eventos ao domínio. correlation_object conecta as etapas de uma mesma jornada. Filtros por tipo, intervalos de tempo, ordenação, paginação e agrupamento ajudam você a reduzir o ruído até chegar aos eventos decisivos.

Próximo passo: consulte a documentação da API para entender como estruturar referências externas e identificadores de correlação no envio dos seus eventos. No próximo conteúdo, vamos mostrar como transformar esse histórico em métricas e views para acompanhar padrões sem repetir a investigação manualmente.