Segmenting metrics by client

Apollo Studio enables you to view operation metrics for each of your application's different clients (such as web and iOS) and client versions (such as 1.0 and 1.1), helping you understand how each one interacts with your graph:

This feature (called client awareness) is especially useful as your number of clients grows, and as you consider when to deprecate or discontinue support for older client versions. See other common use cases.

Setup

First, make sure that your GraphQL server is already pushing analytics to Studio.

Using Apollo Server and Apollo Client

By default, Apollo Server checks for the presence of the following HTTP headers in every incoming operation request:

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

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

1
import { ApolloClient } from 'apollo-client';
2
import { HttpLink } from 'apollo-link-http';
3

4
const client = new ApolloClient({
5
  link: new HttpLink({
6
    uri: 'http://localhost:4000/graphql'
7
  }),
8
  name: 'web',
9
  version: '1.0'
10
});

If one or both of these headers are present, Apollo Server automatically extracts their values and includes them in the trace report that it sends to Apollo Studio. You can override this default behavior.

Advanced Apollo Server configuration

You can configure Apollo Server to use a different method to determine the name and version of the client associated with a request. To do so, install the usage reporting plugin explicitly and provide it with a generateClientInfo function.

In the following example, the generateClientInfo function calls a userSuppliedLogic function, which can return values for the client's name and version based on the details of the request.

1
const { ApolloServer } = require("apollo-server");
2
const { ApolloServerPluginUsageReporting } = require("apollo-server-core");
3

4
const server = new ApolloServer({
5
  typeDefs,
6
  resolvers,
7
  plugins: [
8
    ApolloServerPluginUsageReporting({
9
      generateClientInfo: ({ request }) => {
10
        const { clientName, clientVersion } = userSuppliedLogic(request);
11
        return {
12
          clientName,
13
          clientVersion
14
        };
15
      }
16
    })
17
  ],
18
});
19

20
server.listen().then(({ url }) => {
21
  console.log(`🚀  Server ready at ${url}`);
22
});

Using another GraphQL server

Please reach out to opensource [at] apollographql.com to work with us to add client awareness support to your preferred GraphQL server.

Common use cases

Diagnose client-specific issues

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

Deprecate, change, and remove fields safely

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

Backend cutover

Changes to your schema often accompany changes to your backend, such as the addition of a new resolver, or even an entirely new data source. When you deploy a new version of your client that executes operations 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.

The following shows a cutover from one back-end service to another: