From b45a5d96d46e1df9b627a9d0ba2c41160bcbbe97 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 5 May 2026 14:56:08 +0000
Subject: [PATCH 01/11] docs: update usage reporting docs for dynamic
 exclusions via VRL expressions (router#932)

Agent-Logs-Url: https://github.com/graphql-hive/docs/sessions/4fb074ac-500c-4a50-89d4-003a1192ea8b

Co-authored-by: ardatan <20847995+ardatan@users.noreply.github.com>
---
 .../docs/router/configuration/expressions.mdx |  2 +
 .../docs/router/configuration/telemetry.mdx   | 43 +++++++++++----
 .../router/observability/usage_reporting.mdx  | 55 +++++++++++++++++++
 3 files changed, 88 insertions(+), 12 deletions(-)

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 dc604b56..82742add 100644
--- a/packages/documentation/content/docs/router/configuration/telemetry.mdx
+++ b/packages/documentation/content/docs/router/configuration/telemetry.mdx
@@ -61,26 +61,45 @@ 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[] \| ExcludeObject` | -                                    | 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"'
+```
+
+Expressions can use any fields available under `.request` (see [Expressions](/docs/router/configuration/expressions#request) for the full list of variables).
+
 </details>
 </div>
 
diff --git a/packages/documentation/content/docs/router/observability/usage_reporting.mdx b/packages/documentation/content/docs/router/observability/usage_reporting.mdx
index 96302f33..d35a2c57 100644
--- a/packages/documentation/content/docs/router/observability/usage_reporting.mdx
+++ b/packages/documentation/content/docs/router/observability/usage_reporting.mdx
@@ -46,6 +46,61 @@ 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.).
+
+```yaml title="router.config.yaml"
+telemetry:
+  hive:
+    usage_reporting:
+      enabled: true
+      exclude:
+        expression: '.request.operation.name == "IntrospectionQuery"'
+```
+
+Multi-condition example:
+
+```yaml title="router.config.yaml"
+telemetry:
+  hive:
+    usage_reporting:
+      enabled: true
+      exclude:
+        expression: |
+          if (.request.operation.name == "IntrospectionQuery" ||
+              .request.operation.name == "HealthCheck") {
+            true
+          } else {
+            false
+          }
+```
+
+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

From 24a1dca245c1337770df86ea2812eb29256297d2 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 5 May 2026 14:56:50 +0000
Subject: [PATCH 02/11] docs: clarify exclude field type in telemetry config
 table

Agent-Logs-Url: https://github.com/graphql-hive/docs/sessions/4fb074ac-500c-4a50-89d4-003a1192ea8b

Co-authored-by: ardatan <20847995+ardatan@users.noreply.github.com>
---
 .../content/docs/router/configuration/telemetry.mdx             | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/documentation/content/docs/router/configuration/telemetry.mdx b/packages/documentation/content/docs/router/configuration/telemetry.mdx
index 82742add..134dff91 100644
--- a/packages/documentation/content/docs/router/configuration/telemetry.mdx
+++ b/packages/documentation/content/docs/router/configuration/telemetry.mdx
@@ -66,7 +66,7 @@ Allows you to control how the Hive Router does
 | `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[] \| ExcludeObject` | -                                    | Operations to exclude. Accepts a list of operation names or a VRL expression object. See details below. |
+| `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.                                                                          |

From 9502ac8fac8717b81408b444521a348dc374220a Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 5 May 2026 15:00:42 +0000
Subject: [PATCH 03/11] docs: add header-based exclusion examples to usage
 reporting docs

Agent-Logs-Url: https://github.com/graphql-hive/docs/sessions/a6cb60f4-651b-440f-9765-b594a24e1e5d

Co-authored-by: ardatan <20847995+ardatan@users.noreply.github.com>
---
 .../docs/router/configuration/telemetry.mdx   | 13 ++++++++-
 .../router/observability/usage_reporting.mdx  | 29 ++++++++++++++-----
 2 files changed, 34 insertions(+), 8 deletions(-)

diff --git a/packages/documentation/content/docs/router/configuration/telemetry.mdx b/packages/documentation/content/docs/router/configuration/telemetry.mdx
index 134dff91..1a6dd951 100644
--- a/packages/documentation/content/docs/router/configuration/telemetry.mdx
+++ b/packages/documentation/content/docs/router/configuration/telemetry.mdx
@@ -98,7 +98,18 @@ telemetry:
         expression: '.request.operation.name == "IntrospectionQuery"'
 ```
 
-Expressions can use any fields available under `.request` (see [Expressions](/docs/router/configuration/expressions#request) for the full list of variables).
+You can also exclude based on request headers — for example, to skip reporting for a specific client identified by the `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).
 
 </details>
 </div>
diff --git a/packages/documentation/content/docs/router/observability/usage_reporting.mdx b/packages/documentation/content/docs/router/observability/usage_reporting.mdx
index d35a2c57..d89a8642 100644
--- a/packages/documentation/content/docs/router/observability/usage_reporting.mdx
+++ b/packages/documentation/content/docs/router/observability/usage_reporting.mdx
@@ -72,6 +72,8 @@ evaluates at runtime. Return `true` to exclude the operation or `false` to inclu
 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:
@@ -81,7 +83,23 @@ telemetry:
         expression: '.request.operation.name == "IntrospectionQuery"'
 ```
 
-Multi-condition example:
+**Exclude traffic from a specific client identified via a request header:**
+
+Hive Router reads the client name from the `graphql-client-name` header by default (configurable via
+[`client_identification`](/docs/router/configuration/telemetry#client_identification)). You can use
+that same header to skip reporting for internal tooling, health-check clients, or any other client
+you don't want tracked:
+
+```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:
@@ -90,12 +108,9 @@ telemetry:
       enabled: true
       exclude:
         expression: |
-          if (.request.operation.name == "IntrospectionQuery" ||
-              .request.operation.name == "HealthCheck") {
-            true
-          } else {
-            false
-          }
+          .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

From 2b9b274bdbb0ab4d4c0c6659be3b08660b657d4d Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 5 May 2026 15:02:39 +0000
Subject: [PATCH 04/11] docs: simplify header exclusion example, use
 x-graphql-client-name

Agent-Logs-Url: https://github.com/graphql-hive/docs/sessions/d62a398b-b3f5-4e11-b6a9-0f7fc08f94e3

Co-authored-by: ardatan <20847995+ardatan@users.noreply.github.com>
---
 .../content/docs/router/configuration/telemetry.mdx      | 4 ++--
 .../docs/router/observability/usage_reporting.mdx        | 9 +++------
 2 files changed, 5 insertions(+), 8 deletions(-)

diff --git a/packages/documentation/content/docs/router/configuration/telemetry.mdx b/packages/documentation/content/docs/router/configuration/telemetry.mdx
index 1a6dd951..0cb9058d 100644
--- a/packages/documentation/content/docs/router/configuration/telemetry.mdx
+++ b/packages/documentation/content/docs/router/configuration/telemetry.mdx
@@ -98,7 +98,7 @@ telemetry:
         expression: '.request.operation.name == "IntrospectionQuery"'
 ```
 
-You can also exclude based on request headers — for example, to skip reporting for a specific client identified by the `graphql-client-name` header:
+You can also exclude based on request headers — for example, checking a custom `x-graphql-client-name` header:
 
 ```yaml title="router.config.yaml"
 telemetry:
@@ -106,7 +106,7 @@ telemetry:
     usage_reporting:
       enabled: true
       exclude:
-        expression: '.request.headers."graphql-client-name" == "my-internal-tool"'
+        expression: '.request.headers."x-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 d89a8642..ddae088e 100644
--- a/packages/documentation/content/docs/router/observability/usage_reporting.mdx
+++ b/packages/documentation/content/docs/router/observability/usage_reporting.mdx
@@ -85,10 +85,7 @@ telemetry:
 
 **Exclude traffic from a specific client identified via a request header:**
 
-Hive Router reads the client name from the `graphql-client-name` header by default (configurable via
-[`client_identification`](/docs/router/configuration/telemetry#client_identification)). You can use
-that same header to skip reporting for internal tooling, health-check clients, or any other client
-you don't want tracked:
+You can check any request header — for example, a custom `x-graphql-client-name` header sent by your clients:
 
 ```yaml title="router.config.yaml"
 telemetry:
@@ -96,7 +93,7 @@ telemetry:
     usage_reporting:
       enabled: true
       exclude:
-        expression: '.request.headers."graphql-client-name" == "my-internal-tool"'
+        expression: '.request.headers."x-graphql-client-name" == "my-internal-tool"'
 ```
 
 **Combine multiple conditions:**
@@ -110,7 +107,7 @@ telemetry:
         expression: |
           .request.operation.name == "IntrospectionQuery" ||
           .request.operation.name == "HealthCheck" ||
-          .request.headers."graphql-client-name" == "my-internal-tool"
+          .request.headers."x-graphql-client-name" == "my-internal-tool"
 ```
 
 See [Expressions](/docs/router/configuration/expressions) for the full list of available variables

From 305abc37ae5047abffacaa56ec4f8aeff8f6ebe1 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 5 May 2026 15:06:36 +0000
Subject: [PATCH 05/11] docs: update apollo-router default header names to
 x-graphql-client-name/version

Agent-Logs-Url: https://github.com/graphql-hive/docs/sessions/9a63a64f-3527-485e-9e0e-34614a366dcb

Co-authored-by: ardatan <20847995+ardatan@users.noreply.github.com>
---
 .../content/docs/other-integrations/apollo-router.mdx     | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/packages/documentation/content/docs/other-integrations/apollo-router.mdx b/packages/documentation/content/docs/other-integrations/apollo-router.mdx
index 154d1f82..815973f5 100644
--- a/packages/documentation/content/docs/other-integrations/apollo-router.mdx
+++ b/packages/documentation/content/docs/other-integrations/apollo-router.mdx
@@ -310,10 +310,10 @@ plugins:
     #  A list of operations (by name) to be ignored by Hive.
     # exclude: ["IntrospectionQuery", "MeQuery"],
     #
-    #  Uses graphql-client-name by default
-    # client_name_header: "x-client-name",
-    #  Uses graphql-client-version by default
-    # client_version_header: "x-client-version",
+    #  Uses x-graphql-client-name by default
+    # client_name_header: "x-graphql-client-name",
+    #  Uses x-graphql-client-version by default
+    # client_version_header: "x-graphql-client-version",
     #
     #  A maximum number of operations to hold in a buffer before sending to GraphQL Hive
     #  Default: 1000

From e0748d32421f3dc7391e8b4a79ae8f318e3736be Mon Sep 17 00:00:00 2001
From: Arda TANRIKULU <ardatanrikulu@gmail.com>
Date: Tue, 5 May 2026 18:23:02 +0300
Subject: [PATCH 06/11] Update apollo-router.mdx

---
 .../content/docs/other-integrations/apollo-router.mdx     | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/packages/documentation/content/docs/other-integrations/apollo-router.mdx b/packages/documentation/content/docs/other-integrations/apollo-router.mdx
index 815973f5..154d1f82 100644
--- a/packages/documentation/content/docs/other-integrations/apollo-router.mdx
+++ b/packages/documentation/content/docs/other-integrations/apollo-router.mdx
@@ -310,10 +310,10 @@ plugins:
     #  A list of operations (by name) to be ignored by Hive.
     # exclude: ["IntrospectionQuery", "MeQuery"],
     #
-    #  Uses x-graphql-client-name by default
-    # client_name_header: "x-graphql-client-name",
-    #  Uses x-graphql-client-version by default
-    # client_version_header: "x-graphql-client-version",
+    #  Uses graphql-client-name by default
+    # client_name_header: "x-client-name",
+    #  Uses graphql-client-version by default
+    # client_version_header: "x-client-version",
     #
     #  A maximum number of operations to hold in a buffer before sending to GraphQL Hive
     #  Default: 1000

From 10075efa5932a58362fb14f19152d0b466eb6aac Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 5 May 2026 16:09:35 +0000
Subject: [PATCH 07/11] fix: update client_identification headers and table
 alignment in telemetry/usage_reporting docs

Agent-Logs-Url: https://github.com/graphql-hive/docs/sessions/be1c26d6-1f65-4536-bd88-a13dd4ea6c54

Co-authored-by: ardatan <20847995+ardatan@users.noreply.github.com>
---
 .../docs/router/configuration/telemetry.mdx   | 26 +++++++++----------
 .../router/observability/usage_reporting.mdx  |  4 +--
 2 files changed, 15 insertions(+), 15 deletions(-)

diff --git a/packages/documentation/content/docs/router/configuration/telemetry.mdx b/packages/documentation/content/docs/router/configuration/telemetry.mdx
index 0cb9058d..72f8aa45 100644
--- a/packages/documentation/content/docs/router/configuration/telemetry.mdx
+++ b/packages/documentation/content/docs/router/configuration/telemetry.mdx
@@ -17,8 +17,8 @@ Configure how Hive Router identifies calling clients in telemetry, based on requ
 ```yaml title="router.config.yaml"
 telemetry:
   client_identification:
-    name_header: graphql-client-name # default
-    version_header: graphql-client-version # default
+    name_header: x-graphql-client-name # default
+    version_header: x-graphql-client-version # default
 ```
 
 ## resource
@@ -61,17 +61,17 @@ 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[] \| { 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.                                                                                   |
+| 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:
 
diff --git a/packages/documentation/content/docs/router/observability/usage_reporting.mdx b/packages/documentation/content/docs/router/observability/usage_reporting.mdx
index ddae088e..4d1432a3 100644
--- a/packages/documentation/content/docs/router/observability/usage_reporting.mdx
+++ b/packages/documentation/content/docs/router/observability/usage_reporting.mdx
@@ -42,8 +42,8 @@ client in Hive Console, set up client identification in `router.config.yaml`.
 ```yaml title="router.config.yaml"
 telemetry:
   client_identification:
-    name_header: "graphql-client-name" # default value
-    version_header: "graphql-client-version" # default value
+    name_header: "x-graphql-client-name" # default value
+    version_header: "x-graphql-client-version" # default value
 ```
 
 ## Excluding Operations

From df5c747d96c530d1082c08a00448c6855dd0f17f Mon Sep 17 00:00:00 2001
From: Arda TANRIKULU <ardatanrikulu@gmail.com>
Date: Wed, 6 May 2026 14:48:39 +0300
Subject: [PATCH 08/11] Update telemetry headers in router configuration

---
 .../content/docs/router/configuration/telemetry.mdx           | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/documentation/content/docs/router/configuration/telemetry.mdx b/packages/documentation/content/docs/router/configuration/telemetry.mdx
index 4447c66b..08261b12 100644
--- a/packages/documentation/content/docs/router/configuration/telemetry.mdx
+++ b/packages/documentation/content/docs/router/configuration/telemetry.mdx
@@ -18,8 +18,8 @@ Configure how Hive Router identifies calling clients for usage reporting and tra
 ```yaml title="router.config.yaml"
 telemetry:
   client_identification:
-    name_header: x-graphql-client-name # default
-    version_header: x-graphql-client-version # default
+    name_header: graphql-client-name # default
+    version_header: graphql-client-version # default
     ip_header: null # default
 ```
 

From 69ce9ebcaa23215fc109d48fb637512929d00dd3 Mon Sep 17 00:00:00 2001
From: Arda TANRIKULU <ardatanrikulu@gmail.com>
Date: Wed, 6 May 2026 14:49:20 +0300
Subject: [PATCH 09/11] Update usage_reporting.mdx

---
 .../docs/router/observability/usage_reporting.mdx      | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/packages/documentation/content/docs/router/observability/usage_reporting.mdx b/packages/documentation/content/docs/router/observability/usage_reporting.mdx
index 4d1432a3..b7836434 100644
--- a/packages/documentation/content/docs/router/observability/usage_reporting.mdx
+++ b/packages/documentation/content/docs/router/observability/usage_reporting.mdx
@@ -42,8 +42,8 @@ client in Hive Console, set up client identification in `router.config.yaml`.
 ```yaml title="router.config.yaml"
 telemetry:
   client_identification:
-    name_header: "x-graphql-client-name" # default value
-    version_header: "x-graphql-client-version" # default value
+    name_header: "graphql-client-name" # default value
+    version_header: "graphql-client-version" # default value
 ```
 
 ## Excluding Operations
@@ -85,7 +85,7 @@ telemetry:
 
 **Exclude traffic from a specific client identified via a request header:**
 
-You can check any request header — for example, a custom `x-graphql-client-name` header sent by your clients:
+You can check any request header — for example, a custom `graphql-client-name` header sent by your clients:
 
 ```yaml title="router.config.yaml"
 telemetry:
@@ -93,7 +93,7 @@ telemetry:
     usage_reporting:
       enabled: true
       exclude:
-        expression: '.request.headers."x-graphql-client-name" == "my-internal-tool"'
+        expression: '.request.headers."graphql-client-name" == "my-internal-tool"'
 ```
 
 **Combine multiple conditions:**
@@ -107,7 +107,7 @@ telemetry:
         expression: |
           .request.operation.name == "IntrospectionQuery" ||
           .request.operation.name == "HealthCheck" ||
-          .request.headers."x-graphql-client-name" == "my-internal-tool"
+          .request.headers."graphql-client-name" == "my-internal-tool"
 ```
 
 See [Expressions](/docs/router/configuration/expressions) for the full list of available variables

From efa69ad9ce0387fa2223b669dfa7ddd39bbf2a43 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 6 May 2026 11:51:32 +0000
Subject: [PATCH 10/11] fix: revert x-graphql-client-name to
 graphql-client-name in telemetry exclude example

Agent-Logs-Url: https://github.com/graphql-hive/docs/sessions/261dd532-74f5-4d19-939b-eaf83497ca2b

Co-authored-by: ardatan <20847995+ardatan@users.noreply.github.com>
---
 .../content/docs/router/configuration/telemetry.mdx           | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/documentation/content/docs/router/configuration/telemetry.mdx b/packages/documentation/content/docs/router/configuration/telemetry.mdx
index 08261b12..b9a17da0 100644
--- a/packages/documentation/content/docs/router/configuration/telemetry.mdx
+++ b/packages/documentation/content/docs/router/configuration/telemetry.mdx
@@ -162,7 +162,7 @@ telemetry:
         expression: '.request.operation.name == "IntrospectionQuery"'
 ```
 
-You can also exclude based on request headers — for example, checking a custom `x-graphql-client-name` header:
+You can also exclude based on request headers — for example, checking a custom `graphql-client-name` header:
 
 ```yaml title="router.config.yaml"
 telemetry:
@@ -170,7 +170,7 @@ telemetry:
     usage_reporting:
       enabled: true
       exclude:
-        expression: '.request.headers."x-graphql-client-name" == "my-internal-tool"'
+        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).

From cdbea6ce4b9b5b455b3e9571707104878599c9c2 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 6 May 2026 12:18:01 +0000
Subject: [PATCH 11/11] fix: auto-format telemetry.mdx with oxfmt

Agent-Logs-Url: https://github.com/graphql-hive/docs/sessions/6721615f-e464-4ce1-84f6-2be5cf3d01f0

Co-authored-by: ardatan <20847995+ardatan@users.noreply.github.com>
---
 .../docs/router/configuration/telemetry.mdx   | 20 +++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/packages/documentation/content/docs/router/configuration/telemetry.mdx b/packages/documentation/content/docs/router/configuration/telemetry.mdx
index b9a17da0..fbf86944 100644
--- a/packages/documentation/content/docs/router/configuration/telemetry.mdx
+++ b/packages/documentation/content/docs/router/configuration/telemetry.mdx
@@ -125,17 +125,17 @@ 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%`.                                                                      |
+| 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.                                                                                   |
+| `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: