Client Tracking

A client is what interacts with your GraphQL API. It could be a web browser, mobile app, or even another API. One of the powers of GraphQL is that all clients can get what they need from a single endpoint.

Benefits

Client tracking allows you to associate a specific client, such as iOS v12, with a request, including those that result in errors. This enables you to understand API usage across clients.

Common use cases include:

• Which clients are still requesting a field
• Which clients are impacted by an error
• Which clients are experiencing performance problems

Before You Begin

To configure client tracking, you will need access to where each client is instantiated in the code base.

Configuring Your Client

Stellate infers the client from headers that you should include in every request:

• x-graphql-client-name
• x-graphql-client-version

For example, when instantiating an urql client, headers can be set so they’re passed with every request

const client = createClient({
  url: 'your-graphql-url',
  fetchOptions: {
    headers: {
      'x-graphql-client-name': `${CLIENT_NAME}`,
      'x-graphql-client-version': `${CLIENT_VERSION}`,
    },
  },
})

Viewing Client Usage

Client Overview

From the Clients page, you can view aggregated client information

1. In the Stellate dashboard, navigate to Insights → Clients
2. The tabbed table provides insights by client, or if you select Versions, specific client versions

Operations

For a given operation, you can view the API request distribution across clients.

1. In the Stellate dashboard, navigate to Insights → Operations
2. Select an operation
3. In the resulting modal, scroll down to see the client distribution table

Errors

For a given aggregated error or error event, you can view the API request distribution across clients.

1. In the Stellate dashboard, navigate to Insights → Errors
2. Select an error
3. In the resulting modal, you’ll find the client distribution for the aggregated error. You will also find the client for each error event

Types and Fields

For a given type or field, you can view the request distribution across clients.

1. In the Stellate dashboard, navigate to Schema → Explorer
2. Search for and select a type or field
3. Scroll to usage to view usage across clients