Em 15 de setembro de 2026, a JetBrains publicou uma explicação técnica sobre o funcionamento do recurso Service Map na extensão OpenTelemetry, que mapeia as relações reais entre microsserviços enquanto o aplicativo é executado no ambiente de desenvolvimento. A explicação foi elaborada por Nikita Dukin e Egor Klimov, em uma colaboração entre a equipe Rider Execution e a equipe Software Engineering Research.
A ideia parte de um problema prático conhecido: o diagrama da arquitetura pode parecer organizado, mas talvez reflita o estado do sistema de meses atrás e não mostre um novo serviço ou uma fila de mensagens cuja documentação não foi atualizada. A JetBrains considera que a análise estática do código nem sempre é suficiente, pois ela descreve o que pode acontecer no código-fonte, não o que realmente acontece entre os serviços durante a execução.
Os traces são a fonte do mapa
A extensão depende de dados do OpenTelemetry, que coleta logs, métricas e traces. Enquanto os logs explicam o que aconteceu e as métricas mostram a dimensão do fenômeno, os traces revelam o percurso da solicitação pelo sistema. Cada trace é composto por unidades de trabalho chamadas spans, e o OpenTelemetry fornece convenções semânticas padronizadas para elas, como spans de HTTP Client e HTTP Server.
A extensão usa esses traces para entender a arquitetura operacional sem vincular o algoritmo a uma estrutura ou linguagem específica. Se os aplicativos e as bibliotecas enviarem traces de acordo com as expectativas do OpenTelemetry, o recurso poderá visualizar as comunicações independentemente da tecnologia utilizada. A JetBrains observa que a mesma lógica pode funcionar com aplicativos JVM, .NET, Python, Go e outros, além de poder ser usada no IntelliJ IDEA, GoLand, PyCharm, WebStorm e Rider.
Como o mapa é construído dentro do ambiente de desenvolvimento?
Quando o ambiente de desenvolvimento é executado com a extensão OpenTelemetry ativada, a extensão inicia um servidor local leve que recebe dados de telemetria. Ao executar o aplicativo, a extensão configura as variáveis de ambiente padrão do OpenTelemetry para que o aplicativo envie seus traces a esse servidor local.
O servidor processa os traces recebidos de forma assíncrona, constrói um modelo interno da arquitetura e o atualiza continuamente. Quando a aba Service Map é aberta, a extensão recupera o modelo estrutural mais recente e o exibe como um diagrama visual. Assim, o mapa não é um documento estático criado manualmente, mas o resultado direto das comunicações observadas pelo sistema durante sua execução.
O desafio não é desenhar, mas interpretar os dados
Os traces chegam de forma independente, e não há garantia de ordem de recebimento. Um trace do serviço filho pode chegar antes do trace do serviço pai, e o trace não informa um momento final que garanta que nenhum trace atrasado chegará. Além disso, o OpenTelemetry não fornece um tipo estritamente separado para cada trace; os traces carregam um mapa de pares chave-valor que descreve a semântica da operação.
Por isso, a JetBrains classificou a reconstrução da arquitetura como um algoritmo de processamento de fluxo de dados. A extensão não espera o trace ser concluído; ela examina cada trace assim que ele chega. Ela usa atributos como http.request.method e http.response.status_code para determinar se a operação é uma comunicação HTTP, enquanto outros atributos indicam uma consulta a banco de dados ou uma interação com um sistema de mensagens.
Depois de classificar o trace, o algoritmo determina o serviço que o emitiu. Se o serviço for novo, ele será adicionado ao mapa; se já existir, os novos dados serão mesclados a ele e suas estatísticas serão atualizadas. Nas comunicações HTTP, a extensão procura a relação entre o span CLIENT emitido pelo serviço solicitante e o span SERVER produzido no serviço receptor. O contexto do trace acompanha a solicitação, o que torna o span SERVER filho do span CLIENT. Se a outra extremidade existir, a relação será desenhada imediatamente; caso contrário, o span será mantido na memória até que os dados correspondentes cheguem.
As outras dependências usam regras diferentes. Normalmente, uma chamada ao banco de dados é representada por um único span CLIENT, a partir do qual a extensão infere um nó de banco de dados com base nos atributos semânticos. Já os sistemas de mensagens exigem mais flexibilidade, pois a relação entre produtor e consumidor pode aparecer por meio de uma relação pai-filho ou através de links de traces, dependendo do sistema de mensagens e do método de instrumentação utilizado.
Por que isso importa na prática?
O principal valor está no fato de que o mapa revela o comportamento observado, e não apenas a arquitetura esperada. Se o sistema mostrar durante o desenvolvimento várias comunicações HTTP ou consultas a um banco de dados, quando se esperava uma única comunicação, isso poderá ser descoberto antes do lançamento. O mapa também ajuda a entender dependências que não foram documentadas ou que mudaram ao longo do tempo.
No entanto, a precisão do resultado continua relacionada à qualidade da telemetria. O algoritmo precisa de traces corretos, da propagação do contexto de rastreamento entre os serviços e do uso dos atributos semânticos esperados. Portanto, o Service Map não fornece automaticamente uma imagem completa de qualquer sistema apenas com a instalação da extensão; o que as ferramentas de instrumentação não enviarem, ou o que chegar sem contexto, poderá não aparecer nas relações inferidas. O artigo também explica que o modelo evolui à medida que novas evidências chegam, tornando o mapa uma representação operacional atualizada, e não um veredito final sobre o projeto arquitetural.