Docs
Launch GraphOS Studio

Field usage in GraphOS

Understand field usage metrics including which clients and operations request which fields and how often


NOTE

The retention period for usage metrics depends on your plan. Refer to the pricing page for details.

You can analyze the field metrics sent by your graph to from any 's Insights page in GraphOS Studio:

The Insights page in GraphOS Studio

The Insights page presents and metrics. It has two main sections:

  • The collapsible left sidebar, where you can search, filter, and sort and s
  • The main insights view, which displays overall operations metrics by default, or information and usage metrics for a single field once you select it from the left sidebar

This guide focuses on metrics and information. Refer to Operation metrics in GraphOS for more information on the other metrics on this page, including resolver-level traces.

Field navigation

By default, the left sidebar shows a paginated list of all .

To hone in on certain :

  • Search for a particular by its name or parent type
  • Filter by whether they are unused or deprecated
The Insights page in GraphOS Studio
  • Sort (descending or ascending):

    • Alphabetically
    • By total requests (count)
    • By request rate in requests per minute (rpm)
    • By executions (count)
    • By total errors, error %, or error rate
    • By p50, p90, p95, and p99 latency in milliseconds, seconds, or minutes (ms, s, min)
The Insights page in GraphOS Studio

Click a name in the sidebar to learn more about its usage.

Field details

When you click a name, you open detailed information for that field in the main insights view. This includes when the field first and last received traffic, any applied tags, and the that provide the .

Below that, you can view the definitions within your .

Field Insights page

Next, you see which clients and contribute to the 's usage. Each row in the Clients & Operations table shows a client that requested the , the number of that used the field the client made, and the total number of requests the client made. Selecting a client shows more details about the operations that requested and executed the field.

Below Clients & , you can view visualizations for the 's request rate, latency distribution, and error metrics.

Field requests and executions

Each row in the Clients & Operations table displays some combination of the following metrics for each , depending on which data you report to :

MetricDescription
Client versionsHow many different client versions have sent the operation
RequestsHow many operations sent by clients over a given time period included the field, according to metrics provided by your servers
ExecutionsHow many times your servers have executed the resolver for the field over a given time period

For each of these columns to appear on the Insights page, your must report the associated metrics to GraphOS. If some but not all your report this data, the Insights page presents an incomplete picture of your graph's usage.

Take a look at the Requests and Executions for an example :

Insights page in Studio

As you can see, they can differ significantly. There are many possible reasons for this, described below.

Objects in lists

Let's say a client executes the following one time:

query GetBooks {
books {
title
}
}

If Query.books returns a list of ten Book objects, then Book.title is resolved ten times. This , therefore contributes just one request but ten executions to the Book.title .

Multiple references to a field

Let's say a client executes the following one time:

query GetTwoBooks {
firstBook: book(id: "123") {
title
}
secondBook: book(id: "345") {
title
}
}

This includes two references to the Query.book and Book.title. Therefore, the for these each execute twice (assuming Query.book doesn't return null). However, these multiple references are all part of a single .

Therefore, this contributes just one request but two executions for each of the Query.book and Book.title .

Fields that return interfaces

Let's say our 's schema defines the following interface and :

interface Media {
title: String!
}
type Book implements Media {
title: String!
author: String!
}
type Query {
favoriteMedia: Media!
}

Now, let's say a client executes the following :

query GetFavoriteMedia {
favoriteMedia {
title
}
}

If Query.favoriteMedia returns a Book object here, then Book.title is resolved one time. However, the original does not reference Book.title. Instead, it references Media.title, because Query.favoriteMedia has a return type of Media.

Therefore, this contributes zero requests and one execution for Book.title. It also contributes one request for Media.title. Note that interface always have zero executions.

Requested fields that aren't resolved

Let's say a client executes the following one time:

query GetLoggedInUser {
loggedInUser {
name
}
}

Now, let's say Query.loggedInUser returns null because no user is logged in. In this case, the for User.name never executes, because its parent returns null. Therefore, this contributes one request and zero executions for User.name.

A requested might not be resolved for any of these reasons:

  • The is nested under a field that returns null, as shown above.
  • The is nested under a field that returns a list, but the list is empty.
  • The is part of a that doesn't apply to a particular object.
  • The is skipped due to a @skip or @include .

@key and @requires fields in a federated graph

NOTE

This case applies only to that use Apollo Federation.

Let's say our federated includes these two :

Products subgraph
type Product @key(fields: "id") {
id: ID!
name: String!
}
Reviews subgraph
extend type Product @key(fields: "id") {
id: ID! @external
}
type Review {
id: ID!
score: Int!
product: Product!
}
type Query {
reviews: [Review!]!
}

Now, let's say a client executes the following :

query GetAllReviews {
reviews {
score
product {
name
}
}
}

This 's execution starts in the Reviews , but it needs to obtain each Product's name from the Products . As part of this process, the Products subgraph must resolve references to Products provided by the Reviews .

To help resolve these references, the Reviews must return each Product's id , even though that field isn't included in the original . This is because id is a @key for Product.

Therefore, this contributes zero requests and one execution for Product.id. Similar logic applies to that use the @requires directive.

Previous
Operation metrics
Next
Segmenting by client
Edit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc.

Privacy Policy

Company