docs(router): usage reporting (#7171)

Co-authored-by: Kamil Kisiela <[email protected]>

Author: ardatan

packages/web/docs/src/app/product-updates/(posts)/2025-11-28-hive-router-usage-reporting/page.mdx

@@ -0,0 +1,55 @@
+---
+title: Usage Reporting in Hive Router
+description:
+  Hive Router (Rust) now supports Usage Reporting, allowing you to send operation metrics to Hive
+  Console
+date: 2025-11-28
+authors: [kamil]
+---
+
+[Hive Router (Rust)](/docs/router) now supports
+[Usage Reporting](/docs/schema-registry/usage-reporting), enabling you to send metrics about your
+GraphQL operations directly to Hive Console. This integration allows you to monitor performance,
+track schema usage, and analyze client activity for traffic handled by Router.
+
+## Configuration
+
+We've added a `usage_reporting` configuration object that gives you full control over how usage data
+is reported. You can configure sampling rates, buffer sizes, timeouts, and more to ensure reporting
+doesn't impact your router's performance.
+
+Here is an example configuration:
+
+```yaml filename="router.config.yaml"
+usage_reporting:
+  # Enable reporting by providing your access token
+  access_token: 'your-secret-token' # or set HIVE_ACCESS_TOKEN env var
+  target_id: 'your-target-id' # or set HIVE_TARGET env var
+
+  # Report 50% of requests
+  sample_rate: 50%
+
+  # Buffer settings
+  flush_interval: 10s
+  buffer_size: 500
+
+  # Exclude specific operations
+  exclude:
+    - IntrospectionQuery
+
+  # Custom client identification headers
+  client_name_header: 'x-client-name'
+  client_version_header: 'x-client-version'
+```
+
+## Key Options
+
+- **`sample_rate`**: Control the percentage of requests to report (e.g., `100%` for all traffic, or
+  `10%` for sampling).
+- **`buffer_size` and `flush_interval`**: Optimize network usage by batching reports.
+- **`exclude`**: Filter out specific operations (like introspection) from being reported.
+- **`client_name_header` and `client_version_header`**: Customize how clients are identified in your
+  metrics.
+
+For a complete reference of all available options, please see the
+[Usage Reporting documentation](/docs/router/configuration/usage_reporting).

packages/web/docs/src/content/router/configuration/index.mdx

@@ -30,3 +30,4 @@ that explains how to use that feature.
 - [`supergraph`](./configuration/supergraph): Tell the router where to find your supergraph schema.
 - [`traffic_shaping`](./configuration/traffic_shaping): Manage connection pooling and request
   handling to subgraphs.
+- [`usage_reporting`](./configuration/usage_reporting): Configure usage reporting to Hive Console.

packages/web/docs/src/content/router/configuration/usage_reporting.mdx

@@ -0,0 +1,110 @@
+---
+title: 'usage_reporting'
+---
+
+# usage_reporting
+
+The `usage_reporting` configuration object allows you to control over how the Hive Router does
+[usage reporting](../../schema-registry/usage-reporting) to Hive Console.
+
+## Options
+
+### `access_token`
+
+- **Type:** `string`
+
+Your
+[Registry Access Token](https://the-guild.dev/graphql/hive/docs/management/targets#registry-access-tokens)
+with write permission.
+
+Alternatively, you can set the `HIVE_ACCESS_TOKEN` environment variable to provide the token.
+
+### `target_id`
+
+- **Type:** `string`
+
+A target ID, 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`). To be used when the token is configured with an
+organization access token.
+
+Alternatively, you can set the `HIVE_TARGET` environment variable to provide the target ID.
+
+### `endpoint`
+
+- **Type:** `string`
+- **Default:** `https://app.graphql-hive.com/usage`
+
+For self-hosting, you can override `/usage` endpoint of your Hive instance.
+
+### `sample_rate`
+
+- **Type:** `string`
+- **Default:** `100%`
+
+A percentage value between `0%` and `100%` that indicates the percentage of requests to be reported.
+For example, a value of `10%` means that approximately 10% of requests will be reported, while a
+value of `100%` means that all requests will be reported.
+
+### `exclude`
+
+- **Type:** `string[]`
+- **Default:** `[]`
+
+A list of operations (by name) to be ignored by Hive. For example, if you want to exclude
+introspection queries, you can add `IntrospectionQuery` to this list.
+
+### `client_name_header`
+
+- **Type:** `string`
+- **Default:** `graphql-client-name`
+
+The name of the HTTP header from which to read the client name for usage reporting. This is useful
+if you want to identify different clients consuming your GraphQL API.
+
+### `client_version_header`
+
+- **Type:** `string`
+- **Default:** `graphql-client-version`
+
+The name of the HTTP header from which to read the client version for usage reporting. This is
+useful if you want to identify different versions of clients consuming your GraphQL API.
+
+### `buffer_size`
+
+- **Type:** `integer`
+- **Default:** `1000`
+
+A maximum number of operations to hold in a buffer before sending to Hive Console. When the buffer
+reaches this size, it will be flushed and sent to Hive Console.
+
+### `accept_invalid_certs`
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+If set to `true`, the Hive Router will accept invalid SSL certificates when sending usage reports.
+This can be useful for self-hosted Hive instances using self-signed certificates.
+
+### `connect_timeout`
+
+- **Type:** `string`
+- **Default:** `5s`
+
+A timeout for only the connect phase of a request to Hive Console, in duration format (e.g., `5s`
+for 5 seconds).
+
+### `request_timeout`
+
+- **Type:** `string`
+- **Default:** `15s`
+
+A timeout for the entire request to Hive Console, in duration format (e.g., `15s` for 15 seconds).
+
+### `flush_interval`
+
+- **Type:** `string`
+- **Default:** `5s`
+
+The interval in seconds at which the usage report buffer is flushed and sent to Hive Console. In
+duration format (e.g., `5s` for 5 seconds).

packages/web/docs/src/content/router/observability/_meta.ts

@@ -1,3 +1,4 @@
 export default {
   probes: 'Probes',
+  usage_reporting: 'Usage Reporting',
 };

packages/web/docs/src/content/router/observability/usage_reporting.mdx

@@ -0,0 +1,72 @@
+import { Callout, Cards, Tabs } from '@theguild/components'
+
+# Usage Reporting
+
+Hive Router can send usage reports to Hive Console to provide insights into the operations being
+executed against your GraphQL API. This includes details such as operation names, client
+information, and field-level usage statistics.
+
+The Hive Router can report usage metrics to the Hive schema registry, giving you
+[insights for executed GraphQL operations](/docs/dashboard/insights), and
+[field level usage information](/docs/dashboard/explorer), but also enabling
+[conditional breaking changes](/docs/management/targets#conditional-breaking-changes).
+
+> For additional information about the usage reporting process in Hive Router, see
+> [Usage Reporting page](../observability/usage_reporting).
+
+Before proceeding, make sure you have
+[created a registry token with write permissions on the Hive dashboard](/docs/management/targets#registry-access-tokens).
+
+You can either provide the usage reporting configuration via environment variables or the
+`router.config.yaml` file.
+
+<Tabs items={["Environment Variables", "Configuration File"]}>
+
+{/* Environment Variables */}
+
+<Tabs.Tab>
+
+- `HIVE_TARGET`: The target ID, 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`). To be used when the token is configured with an
+  organization access token.
+
+- `HIVE_ACCESS_TOKEN`: Your
+  [Registry Access Token](https://the-guild.dev/graphql/hive/docs/management/targets#registry-access-tokens)
+  with write permission.
+
+```sh filename="Run Hive Router with Usage Reporting enabled."
+HIVE_ACCESS_TOKEN="<hive_usage_access_token>" \
+  HIVE_TARGET="<hive_usage_target>" \
+  hive-router
+```
+
+</Tabs.Tab>
+
+{/* Configuration File */}
+
+<Tabs.Tab>
+
+Alternatively, you can provide the usage reporting configuration via the `router.config.yaml` file.
+
+```yaml filename="router.config.yaml"
+usage_reporting:
+  # The registry token provided by Hive Registry
+  token: '<hive_usage_access_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_id: '<hive_usage_target>'
+
+  # Endpoint override for self-hosting
+  # endpoint: 'https://my-hive-instance.com/usage'
+```
+
+</Tabs.Tab>
+
+</Tabs>
+
+If you want to control the usage reporting to the Hive Console like `client_name_header`,
+`client_version_header` or `sample_rate` etc, please look at the configuration documentation to
+learn more about other options.
+[See more in the configuration reference](/docs/router/configuration/usage_reporting).