From 74150c2c1dbfbbe4afd92321ab5cd34f5edfc462 Mon Sep 17 00:00:00 2001 From: Arda TANRIKULU Date: Sun, 26 Oct 2025 12:58:35 +0300 Subject: [PATCH 1/3] docs(router): usage reporting --- .../content/router/configuration/index.mdx | 1 + .../router/configuration/usage_reporting.mdx | 110 ++++++++++++++++++ .../src/content/router/observability/_meta.ts | 1 + .../router/observability/usage_reporting.mdx | 72 ++++++++++++ 4 files changed, 184 insertions(+) create mode 100644 packages/web/docs/src/content/router/configuration/usage_reporting.mdx create mode 100644 packages/web/docs/src/content/router/observability/usage_reporting.mdx diff --git a/packages/web/docs/src/content/router/configuration/index.mdx b/packages/web/docs/src/content/router/configuration/index.mdx index dbbb625d434..6d0e0b3504e 100644 --- a/packages/web/docs/src/content/router/configuration/index.mdx +++ b/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. diff --git a/packages/web/docs/src/content/router/configuration/usage_reporting.mdx b/packages/web/docs/src/content/router/configuration/usage_reporting.mdx new file mode 100644 index 00000000000..c6c52b74de7 --- /dev/null +++ b/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). diff --git a/packages/web/docs/src/content/router/observability/_meta.ts b/packages/web/docs/src/content/router/observability/_meta.ts index adfd24e4b1a..9058b19aa87 100644 --- a/packages/web/docs/src/content/router/observability/_meta.ts +++ b/packages/web/docs/src/content/router/observability/_meta.ts @@ -1,3 +1,4 @@ export default { probes: 'Probes', + usage_reporting: 'Usage Reporting', }; diff --git a/packages/web/docs/src/content/router/observability/usage_reporting.mdx b/packages/web/docs/src/content/router/observability/usage_reporting.mdx new file mode 100644 index 00000000000..a128b0bb210 --- /dev/null +++ b/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. + + + +{/* Environment Variables */} + + + +- `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_TARGET="" \ + hive-router +``` + + + +{/* Configuration File */} + + + +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: '' + # 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: '' + + # Endpoint override for self-hosting + # endpoint: 'https://my-hive-instance.com/usage' +``` + + + + + +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). From 7bdc0e3220975d7c6b9a7dd1cca4850ab6794ce4 Mon Sep 17 00:00:00 2001 From: Kamil Kisiela Date: Fri, 28 Nov 2025 14:46:02 +0100 Subject: [PATCH 2/3] product update --- .../page.mdx | 56 +++++++++++++++++++ 1 file changed, 56 insertions(+) create mode 100644 packages/web/docs/src/app/product-updates/(posts)/2025-11-28-hive-router-usage-reporting/page.mdx diff --git a/packages/web/docs/src/app/product-updates/(posts)/2025-11-28-hive-router-usage-reporting/page.mdx b/packages/web/docs/src/app/product-updates/(posts)/2025-11-28-hive-router-usage-reporting/page.mdx new file mode 100644 index 00000000000..0632e9bbead --- /dev/null +++ b/packages/web/docs/src/app/product-updates/(posts)/2025-11-28-hive-router-usage-reporting/page.mdx @@ -0,0 +1,56 @@ +--- +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` & `flush_interval`**: Optimize network usage by batching reports. +- **`exclude`**: Filter out specific operations (like introspection) from being reported. +- **`client_name_header` & `client_version_header`**: Customize how clients are identified in your + metrics. +- **`endpoint` & `accept_invalid_certs`**: Support for self-hosted Hive instances. + +For a complete reference of all available options, please see the +[Usage Reporting documentation](/docs/router/configuration/usage_reporting). From 84855d1502350f1283a48dc9f3df6c6bcf5ae5ec Mon Sep 17 00:00:00 2001 From: Kamil Kisiela Date: Fri, 28 Nov 2025 14:47:12 +0100 Subject: [PATCH 3/3] fix --- .../(posts)/2025-11-28-hive-router-usage-reporting/page.mdx | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/packages/web/docs/src/app/product-updates/(posts)/2025-11-28-hive-router-usage-reporting/page.mdx b/packages/web/docs/src/app/product-updates/(posts)/2025-11-28-hive-router-usage-reporting/page.mdx index 0632e9bbead..47481f7efc0 100644 --- a/packages/web/docs/src/app/product-updates/(posts)/2025-11-28-hive-router-usage-reporting/page.mdx +++ b/packages/web/docs/src/app/product-updates/(posts)/2025-11-28-hive-router-usage-reporting/page.mdx @@ -46,11 +46,10 @@ usage_reporting: - **`sample_rate`**: Control the percentage of requests to report (e.g., `100%` for all traffic, or `10%` for sampling). -- **`buffer_size` & `flush_interval`**: Optimize network usage by batching reports. +- **`buffer_size` and `flush_interval`**: Optimize network usage by batching reports. - **`exclude`**: Filter out specific operations (like introspection) from being reported. -- **`client_name_header` & `client_version_header`**: Customize how clients are identified in your +- **`client_name_header` and `client_version_header`**: Customize how clients are identified in your metrics. -- **`endpoint` & `accept_invalid_certs`**: Support for self-hosted Hive instances. For a complete reference of all available options, please see the [Usage Reporting documentation](/docs/router/configuration/usage_reporting).