docs: update usage reporting docs for dynamic exclusions via VRL expressions by Copilot · Pull Request #104 · graphql-hive/docs

Copilot · 2026-05-05T14:57:00Z

Documents the changes from graphql-hive/router#932, which adds dynamic exclusions to the exclude field in telemetry.hive.usage_reporting.

…essions (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>

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>

github-actions · 2026-05-05T14:59:42Z

Deployment	URL
🌐 Website	https://c456aa3f-hive-platform-docs.theguild.workers.dev
📚 Storybook	https://pr-104.the-guild-docs-storybook.pages.dev

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>

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>

…ame/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>

Copilot

Pull request overview

This PR updates the Hive Router documentation to describe excluding operations from usage reporting, including a new dynamic exclusion mechanism via VRL expressions, and refreshes related telemetry/expression references.

Changes:

Added an “Excluding Operations” section to usage reporting docs, documenting both legacy operation-name lists and a VRL expression-based format.
Expanded the telemetry configuration reference to document the exclude field’s supported formats, with examples (operation name and header-based exclusions).
Updated the Expressions overview page to include usage-reporting exclusion as a documented use case.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
packages/documentation/content/docs/router/observability/usage_reporting.mdx	Adds a new section explaining how to exclude operations (legacy list vs VRL expression) with examples.
packages/documentation/content/docs/router/configuration/telemetry.mdx	Updates the `usage_reporting` reference to describe/exemplify the new `exclude` formats.
packages/documentation/content/docs/router/configuration/expressions.mdx	Adds a new bullet linking expressions to usage-reporting exclusions.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

ardatan · 2026-05-06T11:49:55Z

+| `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. |


@copilot addressed

ardatan · 2026-05-06T11:49:41Z

+You can also exclude based on request headers — for example, checking a custom `x-graphql-client-name` header:
+
+```yaml title="router.config.yaml"
+telemetry:
+  hive:
+    usage_reporting:
+      enabled: true
+      exclude:
+        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).


@copilot addressed

ardatan · 2026-05-06T11:49:43Z

+**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:
+
+```yaml title="router.config.yaml"


@copilot addressed

ardatan · 2026-05-05T15:59:37Z

@copilot apply changes based on the comments in this thread and fix lint errors

…metry/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>

Copilot · 2026-05-05T16:09:46Z

@copilot apply changes based on the comments in this thread and fix lint errors

Done in 10075ef. Applied all three reviewer suggestions:

exclude Default: restored from - to [] to clearly indicate opt-in behavior.
telemetry.mdx client_identification example: updated graphql-client-name/version → x-graphql-client-name/version.
usage_reporting.mdx client_identification section: same header rename.

Also fixed the oxfmt lint failure — the Type column separator was 27 dashes but the string[] \| { expression: string } content is 36 chars, so all Type column cells have been re-padded to 36 chars.

ardatan · 2026-05-05T18:48:57Z

@copilot resolve the merge conflicts in this pull request

…n, add ip_header Co-authored-by: ardatan <20847995+ardatan@users.noreply.github.com>

Copilot · 2026-05-05T18:50:51Z

@copilot resolve the merge conflicts in this pull request

Resolved in a432e08. The only conflict was in telemetry.mdx — main added ip_header: null # default to the client_identification YAML example while our branch renamed the headers. The resolution keeps both: x-graphql-client-name/version headers and the new ip_header: null # default line.

kamilkisiela · 2026-05-06T09:25:11Z

  client_identification:
-    name_header: "graphql-client-name" # default value
-    version_header: "graphql-client-version" # default value
+    name_header: "x-graphql-client-name" # default value


it's graphql-client-name and not x-*

@kamilkisiela fixed!

Fixed in efa69ad — reverted the header-based exclude example in telemetry.mdx from x-graphql-client-name back to graphql-client-name.

… 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>

Copilot AI and others added 2 commits May 5, 2026 14:56

docs: update usage reporting docs for dynamic exclusions via VRL expr…

b45a5d9

…essions (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: clarify exclude field type in telemetry config table

24a1dca

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>

Copilot AI assigned Copilot and ardatan May 5, 2026

Copilot created this pull request from a session on behalf of ardatan May 5, 2026 14:57 View session

Copilot AI requested a review from ardatan May 5, 2026 14:57

Copilot finished work on behalf of ardatan May 5, 2026 14:57

Copilot AI had a problem deploying to preview May 5, 2026 14:58 Error

Copilot AI temporarily deployed to storybook-preview May 5, 2026 14:58 Inactive

Copilot started work on behalf of ardatan May 5, 2026 14:59 View session

docs: add header-based exclusion examples to usage reporting docs

9502ac8

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>

Copilot finished work on behalf of ardatan May 5, 2026 15:01

Copilot started work on behalf of ardatan May 5, 2026 15:01 View session

docs: simplify header exclusion example, use x-graphql-client-name

2b9b274

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>

Copilot finished work on behalf of ardatan May 5, 2026 15:03

Copilot started work on behalf of ardatan May 5, 2026 15:05 View session

docs: update apollo-router default header names to x-graphql-client-n…

305abc3

…ame/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>

Copilot finished work on behalf of ardatan May 5, 2026 15:07

Copilot AI temporarily deployed to storybook-preview May 5, 2026 15:21 Inactive

Copilot AI had a problem deploying to preview May 5, 2026 15:21 Error

ardatan approved these changes May 5, 2026

View reviewed changes

Update apollo-router.mdx

e0748d3

ardatan marked this pull request as ready for review May 5, 2026 15:23

ardatan requested review from Copilot and kamilkisiela May 5, 2026 15:23

Copilot started reviewing on behalf of ardatan May 5, 2026 15:24 View session

ardatan temporarily deployed to storybook-preview May 5, 2026 15:24 — with GitHub Actions Inactive

ardatan deployed to preview May 5, 2026 15:24 — with GitHub Actions View deployment

Copilot AI reviewed May 5, 2026

View reviewed changes

Copilot started work on behalf of ardatan May 5, 2026 15:59 View session

fix: update client_identification headers and table alignment in tele…

10075ef

…metry/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>

Copilot finished work on behalf of ardatan May 5, 2026 16:10

Copilot AI requested a review from ardatan May 5, 2026 16:10

Copilot started work on behalf of ardatan May 5, 2026 18:49 View session

merge: resolve conflict with main - keep x-graphql-client-name/versio…

a432e08

…n, add ip_header Co-authored-by: ardatan <20847995+ardatan@users.noreply.github.com>

Copilot finished work on behalf of ardatan May 5, 2026 18:51

Copilot AI deployed to preview May 5, 2026 19:00 View deployment

Copilot AI temporarily deployed to storybook-preview May 5, 2026 19:00 Inactive

kamilkisiela reviewed May 6, 2026

View reviewed changes

Update telemetry headers in router configuration

df5c747

ardatan had a problem deploying to storybook-preview May 6, 2026 11:48 — with GitHub Actions Error

ardatan had a problem deploying to preview May 6, 2026 11:48 — with GitHub Actions Error

Update usage_reporting.mdx

69ce9eb

Copilot started work on behalf of ardatan May 6, 2026 11:49 View session

ardatan deployed to preview May 6, 2026 11:50 — with GitHub Actions View deployment

ardatan deployed to storybook-preview May 6, 2026 11:50 — with GitHub Actions View deployment

fix: revert x-graphql-client-name to graphql-client-name in telemetry…

efa69ad

… 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>

Copilot finished work on behalf of ardatan May 6, 2026 11:52

Copilot started work on behalf of ardatan May 6, 2026 11:52 View session

Copilot finished work on behalf of ardatan May 6, 2026 11:53

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: update usage reporting docs for dynamic exclusions via VRL expressions#104

docs: update usage reporting docs for dynamic exclusions via VRL expressions#104
Copilot wants to merge 11 commits intomainfrom
copilot/update-documentation-for-changes

Copilot AI commented May 5, 2026 •

edited by ardatan

Loading

Uh oh!

github-actions Bot commented May 5, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

ardatan May 6, 2026

Uh oh!

ardatan May 6, 2026

Uh oh!

ardatan May 6, 2026

Uh oh!

ardatan commented May 5, 2026

Uh oh!

Copilot AI commented May 5, 2026

Uh oh!

ardatan commented May 5, 2026

Uh oh!

Copilot AI commented May 5, 2026

Uh oh!

kamilkisiela May 6, 2026

Uh oh!

ardatan May 6, 2026

Uh oh!

Copilot AI May 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

Copilot AI commented May 5, 2026 • edited by ardatan Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

ardatan May 6, 2026

Choose a reason for hiding this comment

Uh oh!

ardatan May 6, 2026

Choose a reason for hiding this comment

Uh oh!

ardatan May 6, 2026

Choose a reason for hiding this comment

Uh oh!

ardatan commented May 5, 2026

Uh oh!

Copilot AI commented May 5, 2026

Uh oh!

ardatan commented May 5, 2026

Uh oh!

Copilot AI commented May 5, 2026

Uh oh!

kamilkisiela May 6, 2026

Choose a reason for hiding this comment

Uh oh!

ardatan May 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI May 6, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Copilot AI commented May 5, 2026 •

edited by ardatan

Loading

github-actions Bot commented May 5, 2026 •

edited

Loading