diff --git a/packages/web/docs/src/content/router/configuration/index.mdx b/packages/web/docs/src/content/router/configuration/index.mdx index 63cca13b01..c39398793a 100644 --- a/packages/web/docs/src/content/router/configuration/index.mdx +++ b/packages/web/docs/src/content/router/configuration/index.mdx @@ -23,3 +23,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 0000000000..c6c52b74de --- /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 adfd24e4b1..9058b19aa8 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 0000000000..a128b0bb21 --- /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).