---
title: GraphQL Schema Usage
---

import NextImage from 'next/image'
import { Callout } from '@theguild/components'
import monitoringViewImage from '../../../../public/docs/pages/features/monitoring-view.png'
import usageClientsImage from '../../../../public/docs/pages/features/usage-clients.png'
import usageLatencyImage from '../../../../public/docs/pages/features/usage-latency-over-time.png'
import usageOperationsOverTimeImage from '../../../../public/docs/pages/features/usage-operations-over-time.png'
import usageRpmImage from '../../../../public/docs/pages/features/usage-rpm-over-time.png'
import usageStatsImage from '../../../../public/docs/pages/features/usage-stats.png'

# Usage Reporting and Monitoring

Hive allow you to collect usage data from your GraphQL operations and use the data collected for the
following purposes:

1. **Monitoring and Observability**: view a list of all your GraphQL operations and their
   performance, error-rate, and other metrics.
2. **Schema Usage and Coverage**: understand how your consumers are using your GraphQL schema, and
   what parts of the schema are not being used at all (see
   [Schema Usage and Coverage](/docs/schema-registry#schema-explorer)).
3. **Schema Evolution**: with the knowledge of what GraphQL fields are being used, you can
   confidently evolve your schema without breaking your consumers (see
   [Conditional Breaking Changes](/docs/management/targets#conditional-breaking-changes)).

## How it works

To collect and report usage information from your GraphQL gateway, you'll need to setup
[Hive Client](/docs/api-reference/client) within your GraphQL gateway, and have the metadata of your
traffic reported to Hive.

<Callout type="info">
  Hive does not collect, process or store any data from your GraphQL operations or responses. Hive
  Client only transmits the metadata of your GraphQL operations to Hive: what fields were used, if
  there were any errors, etc.
</Callout>

The following information is included in usage reporting:

1. **Operation Name**: the name of the operation, if it exists.
2. **Operation Type**: the type of the operation (`query`, `mutation`, or `subscription`).
3. **Coordinated**: a simple array-based strcuture that represents what fields, arguments, and types
   were used in the operation (for example: `Query.user`, `Query.user.id` `User`).
4. **Client Identifier**: the identifier of the client that sent the operation. This is useful to
   understand the distribution of your consumers.
5. **Date**: the date and time when the operation was executed.

For additional reading, please refer to the following resources:

- [Usage Reporting with Hive Client](/docs/api-reference/client)
- [Hive Usage Reporting specification](/docs/specs/usage-reports)

## Monitoring and Observability

Once you have usage reporting enabled, and shipped your usage reports to Hive, you can view the
usage data in the **Monitoring** view of the target.

<NextImage
  alt="Monitoring View"
  src={monitoringViewImage}
  className="mt-10 max-w-3xl rounded-lg drop-shadow-md"
/>

This view includes the following information:

### Usage Statistics

From the usage statistics view, you'll be able to see the following metrics of your GraphQL API:

1. Total amount of GraphQL executed.
2. Average RPM (Requests Per Minute)
3. Total count of unique GraphQL operations
4. Sucess-rate of the executed operations
5. Error-rate of the executed operations
6. Latency (`p99`, `p95` and `p90`)

<NextImage
  alt="Usage Statistics View"
  src={usageStatsImage}
  className="mt-10 max-w-2xl rounded-lg drop-shadow-md"
/>

### Clients Overview

A breakdown of the clients who are using your GraphQL gateway, and the amount of operations executed
by each client.

<NextImage
  alt="Clients Overview"
  src={usageClientsImage}
  className="mt-10 max-w-2xl rounded-lg drop-shadow-md"
/>

### Monitoring Statistics

A various of the charts and metrics useful for monitoring and having an overview of your GraphQL API
performance:

1. **Operations time**: the amount of GraphQL operations executed over time.

<NextImage
  alt="Operations Over Time"
  src={usageOperationsOverTimeImage}
  className="mt-10 max-w-2xl rounded-lg drop-shadow-md"
/>

2. **RPM over time**: the amount of GraphQL operations executed per minute over time.

<NextImage
  alt="RPM Over Time"
  src={usageRpmImage}
  className="mt-10 max-w-2xl rounded-lg drop-shadow-md"
/>

3. **Latency over time**: the latency of GraphQL operations over time.

<NextImage
  alt="Latency Over Time"
  src={usageLatencyImage}
  className="mt-10 max-w-2xl rounded-lg drop-shadow-md"
/>
