diff --git a/packages/documentation/content/docs/router/configuration/expressions.mdx b/packages/documentation/content/docs/router/configuration/expressions.mdx index 66f0db31..9d04b0d3 100644 --- a/packages/documentation/content/docs/router/configuration/expressions.mdx +++ b/packages/documentation/content/docs/router/configuration/expressions.mdx @@ -14,6 +14,8 @@ structured data. In Hive Router, expressions let you: headers, geographic region or other request metadata. - [Insert, modify or remove HTTP headers](/docs/router/guides/header-manipulation) before forwarding a request to a subgraph or before sending a response back to the client. +- [Exclude specific operations from usage reporting](/docs/router/observability/usage_reporting#excluding-operations) + based on operation name, type, or any request property. Although the concept of "expressions" appears in several parts of the configuration, the syntax and available APIs are consistent. This page explains **what variables and functions are available, when diff --git a/packages/documentation/content/docs/router/configuration/telemetry.mdx b/packages/documentation/content/docs/router/configuration/telemetry.mdx index 8306f4c5..fbf86944 100644 --- a/packages/documentation/content/docs/router/configuration/telemetry.mdx +++ b/packages/documentation/content/docs/router/configuration/telemetry.mdx @@ -125,26 +125,56 @@ Allows you to control how the Hive Router does > For additional information about the usage reporting process in Hive Router, see the > [Usage Reporting page](/docs/router/observability/usage_reporting). -| Field | Type | Default | Notes | -| ---------------------- | ---------- | ------------------------------------ | ------------------------------------------------------------- | -| `enabled` | `boolean` | `false` | Explicitly enable or disable usage reporting. | -| `endpoint` | `string` | `https://app.graphql-hive.com/usage` | Override for self-hosted Hive. | -| `sample_rate` | `string` | `100%` | Percentage between `0%` and `100%`. | -| `exclude` | `string[]` | `[]` | Operation names to ignore (for example `IntrospectionQuery`). | -| `buffer_size` | `integer` | `1000` | Buffer size before flush. | -| `accept_invalid_certs` | `boolean` | `false` | Accept invalid SSL certificates for usage reporting. | -| `connect_timeout` | `string` | `5s` | Timeout for connect phase only. | -| `request_timeout` | `string` | `15s` | Timeout for the full request. | -| `flush_interval` | `string` | `5s` | Buffer flush interval. | +| Field | Type | Default | Notes | +| ---------------------- | ------------------------------------ | ------------------------------------ | ------------------------------------------------------------------------------------------------------- | +| `enabled` | `boolean` | `false` | Explicitly enable or disable usage reporting. | +| `endpoint` | `string` | `https://app.graphql-hive.com/usage` | Override for self-hosted Hive. | +| `sample_rate` | `string` | `100%` | Percentage between `0%` and `100%`. | +| `exclude` | `string[] \| { expression: string }` | `[]` | Operations to exclude. Accepts a list of operation names or a VRL expression object. See details below. | +| `buffer_size` | `integer` | `1000` | Buffer size before flush. | +| `accept_invalid_certs` | `boolean` | `false` | Accept invalid SSL certificates for usage reporting. | +| `connect_timeout` | `string` | `5s` | Timeout for connect phase only. | +| `request_timeout` | `string` | `15s` | Timeout for the full request. | +| `flush_interval` | `string` | `5s` | Buffer flush interval. | + +The `exclude` field accepts two formats: + +**Legacy format** — a list of operation names to skip: ```yaml title="router.config.yaml" telemetry: hive: usage_reporting: enabled: true - exclude: ["IntrospectionQuery"] + exclude: + - IntrospectionQuery + - HealthCheck ``` +**Dynamic expression format** — a [VRL expression](/docs/router/configuration/expressions) that has access to the full request context. Return `true` to exclude the operation or `false` to include it: + +```yaml title="router.config.yaml" +telemetry: + hive: + usage_reporting: + enabled: true + exclude: + expression: '.request.operation.name == "IntrospectionQuery"' +``` + +You can also exclude based on request headers — for example, checking a custom `graphql-client-name` header: + +```yaml title="router.config.yaml" +telemetry: + hive: + usage_reporting: + enabled: true + exclude: + expression: '.request.headers."graphql-client-name" == "my-internal-tool"' +``` + +Expressions can use any fields available under `.request` (see [Expressions](/docs/router/configuration/expressions#request) for the full list of variables). For more examples, see [Excluding Operations](/docs/router/observability/usage_reporting#excluding-operations). + diff --git a/packages/documentation/content/docs/router/observability/usage_reporting.mdx b/packages/documentation/content/docs/router/observability/usage_reporting.mdx index 96302f33..b7836434 100644 --- a/packages/documentation/content/docs/router/observability/usage_reporting.mdx +++ b/packages/documentation/content/docs/router/observability/usage_reporting.mdx @@ -46,6 +46,73 @@ telemetry: 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: + +```yaml title="router.config.yaml" +telemetry: + hive: + usage_reporting: + enabled: true + exclude: + - IntrospectionQuery + - HealthCheck +``` + +### Dynamic VRL expression + +For more fine-grained control, use a [VRL expression](/docs/router/configuration/expressions) 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:** + +```yaml title="router.config.yaml" +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 `graphql-client-name` header sent by your clients: + +```yaml title="router.config.yaml" +telemetry: + hive: + usage_reporting: + enabled: true + exclude: + expression: '.request.headers."graphql-client-name" == "my-internal-tool"' +``` + +**Combine multiple conditions:** + +```yaml title="router.config.yaml" +telemetry: + hive: + usage_reporting: + enabled: true + exclude: + expression: | + .request.operation.name == "IntrospectionQuery" || + .request.operation.name == "HealthCheck" || + .request.headers."graphql-client-name" == "my-internal-tool" +``` + +See [Expressions](/docs/router/configuration/expressions) for the full list of available variables +and functions. + ## Configuration reference See the [telemetry configuration reference](/docs/router/configuration/telemetry#hive) for all