Visualizing GraphQL Traces in Microservices

Written by


Subscribe to our Blog

Get the Latest News and Content

One of the things that most excites me about what we at Helios are doing differently than anyone else is trace visualizations. While there are many ways to troubleshoot microservice architectures, a good visual overview goes a really long way to speeding up understanding and therefore accelerating time to a resolution. When your manager asks, “Why did that break down?” with Helios you can answer quickly with accurate data—this is the value of the Helios platform.

The first thing I did when I started here was show friends what we were building and get feedback on it. So just a few weeks in I was excited to be sitting with a senior engineer friend of mine and showing him something like this:

graphql visualization, distributed tracing

The Peculiarities of GraphQL Traces Visualized

While my friend was impressed with what he saw, (and the fact that we’re collecting the payloads for every span in this trace), he asked me how we handle GraphQL given that his company’s architecture leans on it so heavily. We did have support for GraphQL but he spent a while talking me through the ways a company like his would need something slightly different for a complex use case like theirs.

If you’re unfamiliar with GraphQL, here’s another way to look at it: before GraphQL, when you wanted to know about a single house in a city and everything in it you had to reach out to and query an end-point for dogs, cars, houses, streets, neighborhoods, buildings etc…. GraphQL changes the game in that it gives you one endpoint to query in the city and then as long as you know what you’re looking for (what to include in the query), you can find details about everything in the city, including everything in one specific house.

In visualizing what is happening behind the scenes with tracing, this makes a meaningful difference. In RESTful APIs, each API is exposed as a different HTTP endpoint (e.g., GET /api/users, POST /api/organizations), and so browsing through the list of endpoints can usually clearly tell the story of what the API does. GraphQL, however, has a single HTTP endpoint (typically, POST /api/graphql) – and so if the GraphQL endpoint is visualized the same as the HTTP endpoint, it won’t show the depth of what’s happening under the hood.

Implementing GraphQL Query Visualization

The Helios engineering team was able to take this feedback and quickly implement a more granular visualization of GraphQL queries.

graphql visualization, distributed tracing

To build this out and group API calls by their endpoint, as shown in the screenshots above and below, we had to make some changes. The Helios backend usually uses a combination of the HTTP method (GET / POST / etc.) and route (e.g., /api/v1/users) but this approach is clearly not helpful in the GraphQL case, since every query will be mapped to the same endpoint (POST /api/graphql) – and distinguishing between totally different queries requires manually going through the HTTP payload.

We found a solution by adding an OpenTelemetry processor to the ingestion pipeline which parses the GraphQL payload and classifies the request according to the query itself. 

And today that looks something like this:

graphql visualization, distributed tracing

graphql, distributed tracing

Now when you visualize a GraphQL query in Helios, we will show each type of query with an individual node to make wrapping your head around what’s happening even easier.

We Built Helios to Accelerate Troubleshooting in Microservice Environments

Helios solves the problem every microservices developer will encounter when they execute something and find an error—but aren’t sure where to look for what broke down. The granularity of this kind of visualization means a quick glance at Helios can show them the request that failed, and where in the complex system the error actually arose.

Every day we’re looking for ways to make Helios better, and we’re happy with the feedback we’ve received leading to this change—new GraphQL support will help a wider set of organizations. That said, we’re always looking for ways to improve it (reach out if you have ideas!).

graphql visualization, distributed tracing

Ready to get started visualizing your own GraphQL architecture with Helios? Sign up and get started today.

Subscribe to our Blog

Get the Latest News and Content

About Helios

Helios is a developer platform that helps you increase dev velocity when building cloud-native applications. With Helios, dev teams can easily and quickly perform tasks such as getting a full view of their API inventory, reproducing failures, and automatically generating tests, from local to production environments. Helios accelerates R&D work, streamlining activities from troubleshooting and testing to design and collaboration.

The Author

Related Content

Golang blog (1)
Golang Distributed Tracing - OpenTelemetry Based Observability
OpenTelemetry (OTel in short) is an open-source observability framework that provides a standard set of vendor-agonistic SDKs, APIs, and tools to connect...
Read More
Distributed tracing visualization - Get advanced visibility into your app flows using Jaeger tracing
Jaeger distributed tracing: Advanced visibility into your app flows
Helios’ OpenTelemetry trace visualization tool provides visibility like never before into how data flows through your entire application, across any environment....
Read More
Testing Microservices - Trace Based Integration Testing Example
Microservices architectures require a new type of testing. Here’s why traditional testing types fail and which new automated testing solutions can help.
Read More