Instana’s GraphQL Monitoring Support

GraphQL, originally designed by Facebook back in 2012, is an open-source data query and manipulation language, built for APIs. These days the development of the GraphQL specification is driven by the GraphQL Foundation, which itself is a project under the Linux Foundation, and adoption is growing rapidly.

GraphQL provides an efficient and flexible approach to query or mutate data off of a Web API. It is commonly compared to REST API architectures, similarly providing those features. GraphQL, however, uses a simple query language and a single API endpoint to achieve its goal.

GraphQL query:

  {
    hero {
      name
      friends {
        name
      }
    }
  }
Query result:

  {
    "data": {
      "hero": {
        "name": "R2-D2",
        "friends": [
          {
            "name": "Luke Skywalker"
          },
          {
            "name": "Han Solo"
          },
          {
            "name": "Leia Organa"
          }
        ]
      }
    }
  }

Example 1: Simple GraphQL query with structure request and the respective server response

The main purpose of GraphQL is to minimize the data being queried and transferred from a server, to optimize traffic usage. For that reason, clients define the structure of the required data and the server sends the matching data in a response of the same structure. This is especially useful for objects that inherently have a lot of properties that are rarely used. A great example of such objects comes with the Github API. Objects returned by Github contain all information stored for any object in Git or the platform. In many use cases, most properties are unnecessary though.


Figure 1: Github GraphQL API provides a single endpoint in contrast to the old REST API.

Multi vs. Single Endpoint

The single endpoint design of GraphQL based services comes bundled with a few new challenges. GraphQL, being a Web API, still builds on the foundation of HTTP transport, however, the single endpoint transports all kinds of queries and mutations. For that reason, monitoring of the endpoint itself is not enough.

When gathering information and performance metrics on REST APIs, it is simple to see every API endpoint grouped by HTTP method and URI. Performance metrics are easy to grasp and understand.

With a single endpoint design though, the queries have to be parsed and split into their respective components (such as operation type, object type, arguments, etc.). Only after that step it is be possible map out performance metrics per operation type, queried object, number of properties, or similar common questions. Despite the complexity of the task, gathering insight into the usage and performance of specific objects is important.

Instana’s GraphQL Support

Instana, is the first monitoring system in the world to provide this level of integration for GraphQL. Not only does Instana capture the HTTP traffic and present the query being executed as text, Instana goes two steps ahead of the competition and parses the GraphQL query to deliver a full understanding of what is actually going on.



Figure 2: GraphQL query presented in Instana as an independent call inside the distributed trace.

Furthermore Instana makes GraphQL fully groupable and searchable. As a result, users are free to slice and dice queries the way they see fit and gather a deep insight unseen so far.



Figure 3: Instana also parses the query or mutation and provides insight into the provided arguments.

I said two steps ahead though.

The second feature, probably even more important, is subscriber support. With GraphQL, clients can subscribe themselves to change events on objects. If an object property is changed or an object instance is deleted, the server automatically informs all subscribed clients using their respective WebSocket connection.

To deliver insight into the cost, work, and performance of subscriptions to specific object types, Instana shows when a client subscribes or unsubscribes. However, it also captures every single event being sent out to every single subscriber, delivering a level of understanding of the cost of subscriptions of an unseen degree.



Figure 4: Instana provides the user with insight into the subscription messages and subscribers.

Nodejs, Apollo and GraphQL

As a first step Instana brings full support with the above presented features to Nodejs. Our AutoTrace technology therefore deeply integrates the automatic traces into the Apollo GraphQL framework. That said, writing a fully traced GraphQL server is as simple as just writing a standard Apollo service, Instana does the rest automatically.



Figure 5: The Apollo framework offers an easy foundation to build GraphQL services.

A quick example application using Nodejs, Apollo and GraphQL, Instana provides a demo application presenting the integration capabilities. It can be found on the Instana Github account.

Nodejs application support is provided by Instana using a Nodejs runtime plugin which is automatically built as part of the application’s build cycle. Further information on the Nodejs and GraphQL integration are available from the documentation.

Getting Started

To get started with Instana’s GraphQL support, or any of the other amazing supported technologies, Instana offers a free 14 days trial. Sign up right now and see how quickly Instana discovers your technology stack and automatically provides insight never imagined possible.

Start your FREE TRIAL today!

Full Stack Visibility in 5 minutes! Instana makes it easy to
manage the performance of your applications.

Free Trial

See how Instana's technology works!

Maximum Understanding, Minimum Effort! Check out
how Instana can help you managing your applications.

How Instana Works