6. GraphOS metrics & client awareness


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

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 (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 URL and sends requests to it over a period of time. We'll use it to send fake traffic to our .

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

Note: Right now, our Poetic Plates API does not have any protection against malicious queries or denial-of-service (DoS) attacks. In a future course, we'll cover more techniques to secure your . In the meantime, you can check out the Apollo technote about the topic to learn more about rate limiting, setting timeouts, pagination and more.

Now we're ready to dive into our metrics!

Operation metrics

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

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


Operations page in Studio

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


Operations page filter for a specific operation in Studio

When we select a particular , we can see more specific details about this '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.


Operations page details for a specific operation in Studio

Field metrics

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


Fields page in Studio

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

Note: There's another type of metric called field executions. To see this metric, you'll need a higher volume of requests being sent to your . You can learn more about the difference between executions and requesting s in the Apollo documentation.

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


Fields page details for a specific field in Studio

We can use both and metrics to monitor the health and usage of our 's types and s 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 in which metrics can be segmented by client. It enables us to understand how each of our clients is using our , such as which s they're requesting the most, any issues they're running into and which s they're using. Having access to client-specific metrics also allows us to take into consideration when to deprecate or discontinue support for certain s.

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

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.


Clients page in Studio

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

So far, we've only been sending s to our through Code Sandbox and (unless you shared your 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 queries.

Setting headers for client awareness

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

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

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

Note: Client version metrics are only available on Enterprise plans.

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

  1. Back in , 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 .

    apollographql-client-name: graphos-explorer

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


    Explorer Headers tab with apollographql-client-name set

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

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


    Clients page in Studio with new client graphos-explorer showing

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

Note: If you're using Apollo Client, you can add the name and version properties when you instantiate the ApolloClient class. You can read the Apollo documentation for a code snippet example.

We're now equipped with observability tools to monitor the health of our on ! 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.


Which of the following headers could be included with every request to set up GraphOS client awareness?
Which of the following operation metrics does GraphOS provide?

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 has a cool feature up its sleeve we (and our clients!) should take advantage of, especially for slower queries!


Share your questions and comments about this lesson

This course is currently in

. Your feedback helps us improve! If you're stuck or confused, let us know and we'll help you out. All comments are public and must follow the Apollo Code of Conduct. Note that comments that have been resolved or addressed may be removed.

You'll need a GitHub account to post below. Don't have one? Post in our Odyssey forum instead.