Usage Reporting

Hive Gateway can send usage reports to a schema registry such as the Hive schema registry, but also other providers such Apollo GraphOS.

The Hive Gateway 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. Usage reporting works for both Apollo Federation and Proxy gateways.

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

Run Hive Gateway with Usage Reporting enabled.

hive-gateway supergraph \
  http://cdn.graphql-hive.com/artifacts/v1/12713322-4f6a-459b-9d7c-8aa3cf039c2e/supergraph \
  --hive-cdn-key "<hive_cdn_access_key>" \
  --hive-target "<hive_usage_target>" \
  --hive-access-token "<hive_usage_access_token>"

Run Hive Gateway with Usage Reporting enabled.

docker run --rm --name hive-gateway -p 4000:4000 \
  ghcr.io/graphql-hive/gateway supergraph \
  http://cdn.graphql-hive.com/artifacts/v1/12713322-4f6a-459b-9d7c-8aa3cf039c2e/supergraph \
  --hive-cdn-key "<hive_cdn_access_key>" \
  --hive-target "<hive_usage_target>" \
  --hive-access-token "<hive_usage_access_token>"

Run Hive Gateway with Usage Reporting enabled.

npx hive-gateway supergraph \
  http://cdn.graphql-hive.com/artifacts/v1/12713322-4f6a-459b-9d7c-8aa3cf039c2e/supergraph \
  --hive-cdn-key "<hive_cdn_access_key>" \
  --hive-target "<hive_usage_target>" \
  --hive-access-token "<hive_usage_access_token>"

Alternatively, you can also provide the usage reporting configuration via the gateway.config.ts file.

gateway.config.ts

import { defineConfig } from '@graphql-hive/gateway'

export const gatewayConfig = defineConfig({
  reporting: {
    type: 'hive',
    // The registry token provided by Hive Registry, defaulting to process.env.HIVE_USAGE_ACCESS_TOKEN
    token: '<token>'
    // The registry target which the usage data should be reported to defaulting to process.env.HIVE_USAGE_TARGET
    // This can either be a slug following the format `$organizationSlug/$projectSlug/$targetSlug` (e.g `the-guild/graphql-hive/staging`)
    // or an UUID (e.g. `a0f4c605-6541-4350-8cfe-b31f21a4bf80`).
    target: '<target>'
    /**
     * Other options
     *
     * selfHosting: { ... },
     * clientInfo(context) { ... },
     *
     * See more in Hive Client reference
     */
  }
})

If you want to control the usage reporting to the Hive Console like selfHosting, clientInfo etc, please look at the Hive Client documentation to learn more about other options. See more in Hive Client reference

Experimental: gateway-plugin-console-sdk

If using Hive Gateway and you want to track the executions for your schema coordinates, then you may enable a new experimental feature, "Field Level Metrics". This new feature requires a bit more processing power to parse through your execution result, so scale accordingly, but it allows tracking the exact number of times each schema coordinate has been executed. It also tracks GraphQLErrors by coordinate along with any error codes (from the error's extensions.code field). This means much deeper and more accurate insights into how your API is performing.

gateway.config.ts

import { defineConfig } from "@graphql-hive/gateway";
import { useHive } from "@graphql-hive/gateway-plugin-console-sdk";

export const gatewayConfig = defineConfig({
  // Disable default reporter and usage provider, "@graphql-hive/yoga"
  reporting: {
    enabled: false,
    type: "hive",
    usage: false,
  },
  plugins: (ctx) => [
    // Enable gateway plugin as the hive reporter and usage tracker
    useHive({
      token: "<token>",
      usage: {
        fieldLevelMetricsEnabled: true,
      },
      enabled: true,
    }),
  ],
});

If you want to report usage metrics to a Apollo GraphOS, configure your gateway.config.ts file as following.

gateway.config.ts

import { defineConfig } from "@graphql-hive/gateway";

export const gatewayConfig = defineConfig({
  reporting: {
    type: "graphos",
    /**
     * The graph ref of the managed federation graph.
     * It is composed of the graph ID and the variant (`<YOUR_GRAPH_ID>@<VARIANT>`).
     *
     * If not provided, `APOLLO_GRAPH_REF` environment variable is used.
     *
     * You can find a a graph's ref at the top of its Schema Reference page in Apollo Studio.
     */
    graphRef: "<graph_id>[@<variant>]",
    /**
     * The API key to use to authenticate with the managed federation up link.
     * It needs at least the `service:read` permission.
     *
     * If not provided, `APOLLO_KEY` environment variable will be used instead.
     *
     * [Learn how to create an API key](https://www.apollographql.com/docs/federation/v1/managed-federation/setup#4-connect-the-gateway-to-studio)
     */
    apiKey: "<api_key>",
    /**
     * Usage report endpoint
     *
     * Defaults to GraphOS endpoint (https://usage-reporting.api.apollographql.com/api/ingress/traces)
     */
    endpoint:
      "https://usage-reporting.api.apollographql.com/api/ingress/traces",
    /**
     * Agent Version to report to the usage reporting API
     *
     * Defaults to the Hive Gateway's version
     */
    agentVersion: "hive-gateway@1.0.0",
    /**
     * Client name to report to the usage reporting API
     *
     * Defaults to incoming `apollo-graphql-client-name` HTTP header
     */
    clientName: (req) => req.headers.get("apollo-graphql-client-name"),
    /**
     * Client version to report to the usage reporting API
     *
     * Defaults to incoming `apollo-graphql-client-version` HTTP header
     */
    clientVersion: (req) => req.headers.get("apollo-graphql-client-version"),
  },
});

Edit on GitHub

Experimental: gateway-plugin-console-sdk

On this page