Usage Reporting

Hive Router can report usage metrics to the Hive schema registry, giving you insights for executed GraphQL operations, and field level usage information, but also enabling conditional breaking changes.

Getting Started

Before proceeding, make sure you have created a registry token with write permissions on the Hive dashboard.

Next, set both environment variables:

• HIVE_ACCESS_TOKEN: Your Registry Access Token with write permission.
• HIVE_TARGET: Target reference, either:
  • slug: $organizationSlug/$projectSlug/$targetSlug (for example the-guild/graphql-hive/staging)
  • UUID: a0f4c605-6541-4350-8cfe-b31f21a4bf80

To send usage reports, set telemetry.hive.usage_reporting.enabled: true in router.config.yaml.

Example configuration:

telemetry:
  hive:
    usage_reporting:
      enabled: true
      # Optional: override endpoint for self-hosted Hive
      # endpoint: "https://my-hive/usage"

Client identification

To identify who's calling your GraphQL API and view traffic distribution and operation volume per client in Hive Console, set up client identification in router.config.yaml.

telemetry:
  client_identification:
    name_header: "graphql-client-name" # default value
    version_header: "graphql-client-version" # default value

Excluding Operations

You can prevent specific operations from being reported to Hive Console using the exclude option. It supports two formats that can be used interchangeably.

List of operation names (legacy)

Pass an array of operation names to skip those operations:

telemetry:
  hive:
    usage_reporting:
      enabled: true
      exclude:
        - IntrospectionQuery
        - HealthCheck

Dynamic VRL expression

For more fine-grained control, use a VRL expression that evaluates at runtime. Return true to exclude the operation or false to include it. The expression has full access to the request context (.request, .request.headers, .request.operation.name, .request.operation.type, etc.).

Exclude by operation name:

telemetry:
  hive:
    usage_reporting:
      enabled: true
      exclude:
        expression: '.request.operation.name == "IntrospectionQuery"'

Exclude traffic from a specific client identified via a request header:

You can check any request header — for example, a custom x-graphql-client-name header sent by your clients:

telemetry:
  hive:
    usage_reporting:
      enabled: true
      exclude:
        expression: '.request.headers."x-graphql-client-name" == "my-internal-tool"'

Combine multiple conditions:

telemetry:
  hive:
    usage_reporting:
      enabled: true
      exclude:
        expression: |
          .request.operation.name == "IntrospectionQuery" ||
          .request.operation.name == "HealthCheck" ||
          .request.headers."x-graphql-client-name" == "my-internal-tool"

See Expressions for the full list of available variables and functions.

Configuration reference

See the telemetry configuration reference for all options and defaults under telemetry.hive.