Field Analytics

Introduction

Field analytics is a crucial component in understanding the granular usage patterns of your API fields. This feature allows API producers to gain detailed insights into how specific fields within their models are being accessed and utilized. For example, consider a model GetUserWithNotificationsAndReviews with fields notificationsMsg and reviews. Field-level analytics enable you to determine how often GetUserWithNotificationsAndReviews.review was queried over the last month and identify the operations involved in these queries.

By tracking the frequency and context of field queries, you can make informed decisions about API evolution, performance optimization, and data governance.

In the Insights page on the Analytics tab , you can view field analytics for either an entire project or a single build.

Use Cases

• API Evolution and Deprecation: Field analytics helps in tracking the usage of deprecated fields. By understanding which deprecated fields are still in use, API producers can plan the sunsetting of these fields more effectively, ensuring minimal disruption to consumers.
• Operational Insights and Incident Response: In the event of an incident, field analytics can help identify correlations between specific fields and operational issues. By analyzing field usage patterns, support teams can quickly pinpoint potential problem areas and address them efficiently.
• Resource Optimization and Decision Making: Understanding which fields are most and least used helps in optimizing data fetching strategies. API producers can allocate resources more efficiently, reduce unnecessary data processing, and enhance the overall performance of their APIs.

Field analytics provides API producers with the detailed insights necessary to manage and optimize their API offerings effectively. By leveraging these insights, organizations can make informed decisions that enhance API performance, ensure compliance, and deliver better value to their users.

Field Summary

Field Summary provides a quick glance at the most and least accessed fields within your API. This feature categorizes field usage into three distinct types: direct queries, usage via relationships, and usage as arguments. These access modes help understand the operations calling fields across subgraphs and show the power of a rich federated architecture.

Access Mode

The Access Mode provides a breakdown of the different ways in which fields are accessed within your API. This provides a very unique insight into the kind of access of your fields: direct queries, usage via relationships, and usage as arguments.

query ProductHomePage {
  topTShirtsInUS: products( #1 Select list
    where: {
      countryOfOrigin: { _eq: "US" }
      category: { name: { _eq: "T-Shirts" } }
    } # 2 Filtering and 7 Nested Filtering
    # order_by: {price: Asc} # 3 Sorting
    order_by: { category: { name: Asc } } # 8 Nested Sorting Same Database
    offset: 1 # 4 Pagination
    limit: 5 # 4 Pagination
  ) {
    id
    name
    price
    description
    manufacturedBy: manufacturer {
      name # 5 Same Database Join
    }
    latestOrders: orders {
      # Two level nested join across database
      createdAt
      userActivity: user {
        name # 6 Three Level Nested Join across database
      }
    }
    # 9 Nested paginate (top n)
    topReviews: reviews(
      where: { createdAt: { _gt: "2023-10-15" } } # Filtering
      order_by: { rating: Desc } # Sorting
      limit: 3 # Pagination
    ) {
      rating
      text
    }
  }
}

• Direct Queries: Fields accessed directly in the query without nesting. For example, in the query above, price and description are accessed directly.
• Usage via Relationships: Fields accessed in a query via relationship within a subgraph or across subgraphs. For example, in the query above, orders.createdAt is accessed via the relationship from source products and relationship orders.
• Usage as Arguments: Fields used as a argument to filter data in a query. For example, in the query above, productId is used as an argument to filter data.

Field accessed as arguments via relatioships

Some fields are accessed as both as arguments and via relationships.

In the query above, category.name is accessed as argument via relationship name category.

Field List

The Field List section provides a detailed breakdown of all fields within a model, their access modes, and the number of requests made.

Table columns

• Field Name: The name of the field within the model.
• Access Mode: The mode in which the field is accessed, such as direct queries, usage via relationships, or usage as arguments.
• Number of Requests: The total number of requests made for this field.

Field details

Clicking on the field name in the table opens a sidebar modal that provides in-depth details about the selected field. The Field Detail section provides a comprehensive analysis of a specific field within a model. This section is designed to offer in-depth insights into field usage, including request patterns, the operations accessing the field, and the context of these accesses. Such detailed visibility aids in understanding the behavior and importance of individual fields in your API.

• Field Requests Graph: The Field Requests Graph provides a visual representation of the number of requests made on a particular field in a day over a month. This information is crucial for understanding the load on your field and can aid in performance tuning and resource allocation.
• Field Operations List: The Field Operations List provides a detailed table of all operations that access a particular field. This table includes the operation name, access mode, relationship source, and the number of requests made from a particular query to that field. This comprehensive view helps in identifying and analyzing the usage patterns and complexities of different operations that access the field.

Clicking on the operation name in the table opens a sidebar modal that provides in-depth details about the selected operation.