Overview

GraphOS provides us with observability tools to monitor the health and performance of our supergraph. These tools help surface patterns in how our supergraph gets used, which helps us identify ways to continue improving our supergraph.

In this lesson, we will:

• Explore the operation and field metrics provided by GraphOS
• Set up client awareness to indicate which operations were sent by which client

Sending (fake) traffic to the supergraph

We're still in tutorial-land, so there isn't much real production traffic going to our supergraph (unless you actually went ahead and shared your API with others, in which case, good for you!).

Let's go ahead and get some numbers in here so we can walk through what it might look like if we did have more traffic.

The Code Sandbox below contains a script that takes a supergraph URL and sends requests to it over a period of time. We'll use it to send fake traffic to our supergraph.

Go ahead and enter your URL (you can find that at the top of your supergraph's README page). Then press the button to trigger the script!

Now we're ready to dive into our supergraph metrics!

Operation metrics

We can observe the performance of our operations through the Operations page, which gives us an overview of operation request rates, service time, and error percentages, including specific operations for each of these that might be worth drilling deeper into.

We can navigate to the Operations page of our supergraph using the left-hand sidebar in Studio.

We recommend that clients clearly name each GraphQL operation they send to the supergraph, because these are the operation names you'll see in your metrics. We can also filter to select a particular operation.

When we select a particular operation, we can see more specific details about this operation's usage, as well as its signature (which is the shape of the query). We can see the request rate (the number of requests that have been made), and the latency of the request (how long each request takes) over time.

Field metrics

GraphOS also gives us insight into the usage metrics of our supergraph's fields. We can navigate to this page by clicking Fields in the left-hand sidebar.

We can use the dropdowns on the top-right side of the page to filter metrics based on a custom time range or on a subset of clients.

Beside each field, we'll see a column called "Requested by operations in the last day". These are also known as requesting operations, which is the number of operations in a given period that have included that particular field. You can change this time range using the filters on the page. This metric helps us see how frequently this particular field is being used.

Similar to operations metrics, we can dive deeper into a particular field to view more specific metrics about it. Click the metrics button on the right of the field to navigate to that field's detailed metrics.

We can use both operation and field metrics to monitor the health and usage of our supergraph's types and fields and determine where we can start to improve, based on how our clients are using them.

Client awareness

Client awareness is another powerful feature of GraphOS in which metrics can be segmented by client. It enables us to understand how each of our clients is using our supergraph, such as which operations they're requesting the most, any issues they're running into and which fields they're using. Having access to client-specific metrics also allows us to take into consideration when to deprecate or discontinue support for certain fields.

For both operations and fields metrics from the sections above, you'll see the clients usage information when you dig into a specific operation or field.

You'll also see a complete list of clients using the API by heading over to the Clients page using the left-hand sidebar navigation.

The operations sent through the Code Sandbox script earlier in the lesson will show up as codesandbox. But you'll notice that we also have operations coming from "Unidentified client". That's not very helpful!

So far, we've only been sending operations to our supergraph through Code Sandbox and Explorer (unless you shared your supergraph URL to someone else and they're sending it queries!). We would expect the client metrics to show Explorer, or something similar. Definitely not an "Unidentified client'!

So how can we get it to show the correct client name? We have to send the appropriate headers with our request! The Code Sandbox is already doing this behind the scenes (dig into the code if you want to find how it's doing that!), but we haven't set up our Explorer queries.

Setting headers for client awareness

To set up client awareness, the router checks for two specific HTTP headers in every incoming operation request:

• apollographql-client-name
• apollographql-client-version

If one or both of these headers are present in the request, the router will extract the values and include them in the metrics it sends to GraphOS. And we'll be able to see these helpful values in Studio!

Let's take a look at how to send these headers.

1. Back in Explorer, in the Operation panel, in the bottom section, click on the Headers tab.

2. Let's add the header for apollographql-client-name. We'll set the value to graphos-explorer, but you can pass in whatever value you want! It depends on the client sending the operation.

   apollographql-client-name: graphos-explorer

   Copy

   We can omit the version header since we don't want to keep track of versions of Explorer.

   https://studio.apollographql.com

   

3. Send a few operations to the supergraph. Try using one of the operations saved in your collection!

4. Head over to the Clients page again. It should now show Explorer! Much more useful!

   https://studio.apollographql.com

   

We recommend encouraging any downstream clients using your supergraph to include those client-specific HTTP headers with every request.

We're now equipped with observability tools to monitor the health of our supergraph on GraphOS! These tools are going to be incredibly helpful as clients use the graph to power their app experiences and as we build new features on top of Poetic Plates.

Practice

Key takeaways

• Operation metrics provide an overview of operation request rates, service time, and error percentages within a given time period or for a specific operation.
• Field metrics include the requesting operations metric, which lists the number of operations in a given period that have included the particular field.
• To set up client-aware metrics in GraphOS, incoming requests should include one of these headers: apollographql-client-name and apollographql-client-version.

Up next

One more thing... the Apollo Router has a cool feature up its sleeve we (and our clients!) should take advantage of, especially for slower queries!