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