Real-Time Microservice Mapping with OpenTelemetry
How traces auto-generate accurate architecture diagrams in your IDE
1The documentation dilemma
Engineering teams constantly struggle with outdated architecture diagrams that don't reflect runtime reality. Traditional static analysis fails to capture actual service interactions, while manual documentation becomes obsolete quickly. OpenTelemetry's runtime traces provide a solution by recording real service communications. The Service Map feature leverages these traces to generate accurate, up-to-date visualizations automatically. This eliminates the guesswork from understanding complex microservice architectures.
2Traces as architectural DNA
OpenTelemetry traces capture the complete journey of requests through a system via standardized spans. HTTP Client and Server spans reveal service boundaries and dependencies. Unlike logs or metrics, traces preserve the contextual relationships between services. The plugin processes these spans to reconstruct the actual communication patterns. By relying on the OpenTelemetry standard, the solution works across any technology stack that implements proper instrumentation.
3Real-time reconstruction engine
The plugin runs a lightweight local OpenTelemetry backend that processes telemetry data during execution. As applications emit spans, the backend asynchronously builds an architectural model. The system handles spans arriving out of order and deals with incomplete trace data. When viewing the Service Map, the IDE fetches the latest model rather than a static snapshot. This provides developers with a living representation of their system's structure.
4Span classification system
The algorithm inspects span attributes to determine interaction types. HTTP calls are identified by request methods and status codes. Database operations show up as client spans with specific semantic conventions. Message queue interactions use either parent-child relationships or span links. Each span type follows OpenTelemetry's semantic conventions, allowing the system to interpret them consistently across different frameworks and languages.
5Dynamic dependency mapping
The system matches related spans to establish service connections. HTTP Client spans are paired with their corresponding Server spans using trace context. Database nodes are inferred from client span attributes. Messaging patterns are reconstructed based on instrumentation specifics. The algorithm maintains partial connections while waiting for missing spans, continuously refining the model as new data arrives.
6Handling telemetry chaos
Real-world telemetry data presents multiple challenges: spans arrive asynchronously, trace completion is indeterminable, and payloads are untyped. The solution processes each span immediately rather than waiting for complete traces. It uses semantic attributes to classify operations and maintains state to handle out-of-order arrival. This stream processing approach enables accurate reconstruction despite network unpredictability.
7Language-agnostic visualization
Because it relies on OpenTelemetry standards, the feature works across JVM, .NET, Python, and Go applications. The same reconstruction logic applies regardless of implementation language. Developers can use the visualization in their preferred JetBrains IDE, including IntelliJ IDEA, GoLand, and PyCharm. The solution requires only that applications emit standard spans and propagate context correctly.
8From observation to action
Real-time architecture visualization helps teams identify unexpected service interactions during development. Discovering unintended HTTP calls or database queries early prevents production issues. The Service Map turns observability data into architectural insights, bridging the gap between how systems are designed and how they actually operate. This represents a significant advancement in maintaining accurate system documentation.
Original article: The JetBrains Blog — Real-Time Microservice Mapping with OpenTelemetry