User Tracking

When events like errors or slow response times occur on your service, it’s important to know the event scope - how many users are impacted, not just the overall event volume. Your response to an error impacting 10% of users is much different than responding to an error impacting .1% of users.

Benefits

User tracking enables you to view the user impact of an aggregated event

• Errors: understand what % of users have encountered an error
• Operations: understand what % of users have performed a query or mutation
• Types and Fields: understand what % of users have request a type or field

Each insight can be viewed within the context of Stellate’s other dimensions, such as client, timeframe, and country. This allows you to answer questions like “how many iOS users on the latest client version are experiencing this error”.

What is a user

We use the term “user” to represent the primary entity in your service. It doesn’t have to be an actual human, it could also be an organization, team, etc.

Identifying users

In your Stellate config, you can configure how users are represented in requests. Most often, this is an ID in a header value or JWT claim. The configured value doesn’t need to be one you use internally. The only requirement is that it’s consistent; across all requests a user generates, the ID needs to be the same.

Identifying Users Via A Header

To extract the userId from a header whose value is a string, supply a dictionary with a key of header and the header’s name as the value. In the example below, the header x-user-id contains the value to identify unique users.

import { Config } from 'stellate'

const config: Config = {
  config: {
	  userId : { header: 'x-user-id' }
    rules: [
      {
        ...
      },
    ],
  },
}
export default config

Identifying Users Via A Cookie

To extract the userId from a cookie, supply a dictionary with a key of cookie and the cookie's name as the value. In the example below, the cookie user-id contains the value to identify unique users.

import { Config } from 'stellate'

const config: Config = {
  config: {
	  userId : { cookie: 'user-id' }
    rules: [
      {
        ...
      },
    ],
  },
}
export default config

Using a JWT Claim

If you're using a header with a JWT value, you can extract the value like the example below.

import { Config } from 'stellate'

const config: Config = {
  config: {
    name: 'my-app',
      userId: {
        header: 'x-user-id',
        jwt: {
          // Instruct Stellate to take the value of this claim from the JWT payload
          claim: 'sub',

          // Pass the algorithm you use to sign your JWTs
          algorithm: 'HS256',

          // Pass the secret you use for signing (or the public key when using
          // an asymmetric algorithm)
          secret: ':a_very_secret_passphrase',
        },
    },
    rules: [
      {
        ...
      },
  },
}
export default config

Viewing User Impact

When viewing an error, operation, type, or field, the user impact will be displayed along with the client usage

Overall user impact

In the header of each modal, the total number of users impacted and what % of overall users that represents is displayed

Distribution of user impact

Within the contents of the modal, the distribution of users across clients is shown