Join us for GraphQL Summit, October 10-12 in San Diego. Use promo code ODYSSEY for $400 off your pass.
Launch GraphOS Studio

Segmenting metrics by client

Understand how different clients use your graph

In Studio, you can view GraphQL metrics broken down by the different clients that execute those s (such as your web, iOS, and Android apps). This feature (called client awareness) becomes more and more useful as you create additional clients that consume your .

To enable client awareness, your clients must identify themselves in their requests to your . Learn how.

GraphOS Enterprise organizations can segment metrics even further, by individual client versions (1.0, 1.1, etc.). This helps you track adoption of new versions and identify older versions you can safely deprecate or discontinue.

You view client-segmented metrics from a 's Clients page in Studio:

Client awareness overview

If a particular client doesn't identify itself in its requests, its metrics are included in an Unidentified clients category.


Your 's checks for the presence of the following HTTP headers in every incoming request:

  • apollographql-client-name
  • apollographql-client-version
    • Segmenting metrics by client version in Studio requires a GraphOS Enterprise plan. You can safely include this header in requests regardless of your plan type.

If one or both of these headers are present, your automatically extracts their values and includes them in the metrics data that it sends to .

If you're using Apollo Client, you can populate these headers automatically for every request by providing the name and version options to the ApolloClient constructor, like so:

import { ApolloClient } from 'apollo-client';
import { HttpLink } from 'apollo-link-http';
const client = new ApolloClient({
link: new HttpLink({
uri: 'http://localhost:4000/graphql'
name: 'web',
version: '1.0'

If you're using another GraphQL client, consult its documentation to learn how to add custom HTTP headers to every outgoing request.

Common use cases

Diagnose client-specific issues

By filtering your graph's metrics by client (and client version with Enterprise), you can identify when a high failure rate for an is tied to a particular client. This helps you isolate the underlying cause and push an update for the affected client.

Deprecate, change, and remove fields safely

Modifying or removing an existing in your is often a breaking change for the clients that use that . Client awareness gives you a breakdown of which clients use which fields in your , enabling you to determine the impact of such a change:

Table of client field usage

Backend cutover

Changes to your often accompany changes to your backend, such as the addition of a new , or even an entirely new . When you deploy a new version of your client that executes s against these new resources, it's important to monitor operations to detect issues. Viewing metrics specific to the new client version helps you identify and resolve these issues quickly.

Field usage
Sending metrics to GraphOS
Edit on GitHubEditForumsDiscord