Skip to content

Adds comprehensive context key reference to docs #8420

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mabuyo merged 11 commits into from
Oct 16, 2025
Merged

Adds comprehensive context key reference to docs #8420

Show file tree
Hide file tree
Changes from 10 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
5b289e1
Adds comprehensive context key reference to docs
faisalwaseem Oct 14, 2025
c3376ca
docs: Add comprehensive context key reference to documentation
faisalwaseem Oct 14, 2025
40c6455
Add context key reference to documentation
faisalwaseem Oct 16, 2025
19b8735
Merge branch 'dev' into doc-context-keylist
faisalwaseem Oct 16, 2025
48b5b26
style: remove bold from codefont
mabuyo Oct 16, 2025
1985604
minor clarification edits
mabuyo Oct 16, 2025
64636e6
style: sentence-case headings, remove trailing spaces
mabuyo Oct 16, 2025
c6a281c
move duplicate info on context keys to reference page
mabuyo Oct 16, 2025
06786ad
edit description
mabuyo Oct 16, 2025
e43791a
librarian edits: codefont booleans, edit awkward phrasing
mabuyo Oct 16, 2025
6513053
Merge branch 'dev' into doc-context-keylist
faisalwaseem Oct 16, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changesets/docs_doc_context_keylist.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
### Adds comprehensive context key reference to docs ([PR #8420](https://github.com/apollographql/router/pull/8420))

@mabuyo mabuyo Oct 15, 2025

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think something went wrong in the changeset here? I'm seeing a checklist that should only be in the PR description.

We can also remove this changeset because docs-only PRs typically don't need one.

@abernix abernix Oct 16, 2025

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Generally speaking, it's true that docs stuff doesn't need them, but I like to highlight really valuable documentation additions in our changesets, and I feel like this is one of them.

The changesets tooling defaults to the PR description that appears above the <!-- start metadata --> line in the PR template, but since this PR had no description, it just defaulted to the entire PR contents.

@faisalwaseem If you don't have time to fix the changeset, I can take a shot at it. Alternatively, agree to just delete it.

@faisalwaseem faisalwaseem Oct 16, 2025

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am ok with removing the changeset since the change is so minor

@faisalwaseem faisalwaseem Oct 16, 2025

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FYI I did take a crack and fixing the changeset file lets see if that works

@mabuyo mabuyo Oct 16, 2025

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ahh thanks for clarifying Jesse! and looks like the changeset looks better now 🙌🏽 I'll go ahead and review the meat of the PR 👀


This change documents all the context keys router supports as of submitting this PR.

By [@faisalwaseem](https://github.com/faisalwaseem) in https://github.com/apollographql/router/pull/8420
89 changes: 89 additions & 0 deletions docs/source/routing/customization/coprocessor/reference.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -342,6 +342,95 @@
</tbody>
</table>

## Context key reference

List of context keys available from the router's request context, which is shared across stages of the processing pipeline.

### Core operation

- `apollo::supergraph::operation_name` - Name of the operation
- `apollo::supergraph::operation_kind` - Operation kind: `query`, `mutation`, or `subscription`
- `apollo::supergraph::operation_id` - Apollo operation ID
- `apollo::supergraph::first_event` - First event marker for subscriptions. `false` if the current response chunk is not the first response in the stream, `none` otherwise
- `apollo::supergraph_schema_id` - Supergraph schema ID

### Authentication and authorization

#### Authentication
- `apollo::authentication::jwt_claims` - Claims extracted from a JWT if present in the request
- `apollo::authentication::jwt_status` - JWT validation status (internal only)
Comment thread
faisalwaseem marked this conversation as resolved.

#### Authorization
- `apollo::authorization::authentication_required` - `true` if the operation contains fields marked with `@authenticated`
- `apollo::authorization::required_scopes` - If the operation contains fields marked with `@requiresScopes`, it contains the list of scopes used
- `apollo::authorization::required_policies` - If the query contains fields marked with `@policy`, it contains a map of `policy name -> Option<bool>`. A coprocessor or Rhai script can edit this map to mark `true` on authorization policies that succeed or `false` on ones that fail

### Telemetry

#### Client information
- `apollo::telemetry::client_name` - Client name extracted from the client name header
- `apollo::telemetry::client_version` - Client version extracted from the client version header
- `apollo::telemetry::client_library_name` - Client library name
- `apollo::telemetry::client_library_version` - Client library version

#### Telemetry control
- `apollo::telemetry::subgraph_ftv1` - JSON-serialized trace data returned by the subgraph when FTV1 is enabled
- `apollo::telemetry::studio_exclude` - `true` if the current request's trace details should be excluded from Studio
- `apollo::telemetry::contains_graphql_error` - `true` if the response contains at least one error
- `apollo::telemetry::counted_errors` - Map of already-counted errors (internal)
- `apollo::telemetry::http_request_resend_count_{subgraph_req_id}` - HTTP retry count (dynamic key with subgraph request ID suffix)

### Demand and cost control

The following keys are populated by the demand control plugin:

- `apollo::demand_control::estimated_cost` - Estimated cost of the requests to be sent to the subgraphs
- `apollo::demand_control::actual_cost` - Actual calculated cost of the responses returned by the subgraphs
- `apollo::demand_control::result` - `COST_OK` if allowed, and `COST_TOO_EXPENSIVE` if rejected due to cost limits
- `apollo::demand_control::strategy` - Name of the cost calculation strategy used

### Caching

#### Response cache
- `apollo::response_cache::key` - Response cache key
- `apollo::response_cache::debug_cached_keys` - Debug info for cached keys
- `apollo::router::response_cache::cache_info_subgraph_{subgraph_name}` - Response cache info per subgraph (dynamic key with subgraph name suffix)

#### Entity cache
- `apollo_entity_cache::key` - Entity cache key
- `apollo::entity_cache::cached_keys_status` - A map of cache control statuses for cached entities, keyed by subgraph request ID; populated by the entity caching plugin when `expose_keys_in_context` is enabled
- `apollo::router::entity_cache_info_subgraph_{subgraph_name}` - Entity cache info per subgraph (dynamic key with subgraph name suffix)

#### Automatic persisted queries (APQ)
- `apollo::apq::cache_hit` - Present if the request used APQ; true if we got a cache hit for the query ID, false otherwise

Check warning on line 405 in docs/source/routing/customization/coprocessor/reference.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/routing/customization/coprocessor/reference.mdx#L405 

Avoid using 'we' to prevent ambiguity. Also, use code font for boolean values like `true` and `false`.

```suggestion
- <code>apollo::apq::cache_hit</code> - Present if the request used APQ; <code>true</code> if a cache hit occurred for the query ID, <code>false</code> otherwise
```
- `apollo::apq::registered` - `true` if the request registered a query in APQ

### Query plan exposure

- `apollo::expose_query_plan::plan` - Contains the query plan serialized as JSON (editing it has no effect on execution)
- `apollo::expose_query_plan::formatted_plan` - Query plan formatted as text string
- `apollo::expose_query_plan::enabled` - `true` if query plan exposure is enabled

### Progressive override

- `apollo::progressive_override::unresolved_labels` - List of unresolved labels
- `apollo::progressive_override::labels_to_override` - List of labels for which overrides are needed

### Subscriptions

- `apollo::subscriptions::fatal_error` - Fatal subscription error flag

### Persisted queries

- `apollo_persisted_queries::client_name` - Client name for PQ operations
Comment thread
faisalwaseem marked this conversation as resolved.
- `apollo_persisted_queries::safelist::skip_enforcement` - Skip safelist enforcement

### Connectors

- `apollo_connectors::sources_in_query_plan` - List of connector sources in query plan
Comment thread
faisalwaseem marked this conversation as resolved.

---

## Example requests by stage

### `RouterRequest`
Expand Down
26 changes: 1 addition & 25 deletions docs/source/routing/customization/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -94,31 +94,7 @@

The router makes several values available in the request context, which is shared across stages of the processing pipeline.

- `apollo::apq::cache_hit`: present if the request used APQ, true if we got a cache hit for the query id, false otherwise
- `apollo::apq::registered`: true if the request registered a query in APQ
- `apollo::authentication::jwt_claims`: claims extracted from a JWT if present in the request
- `apollo::authorization::authenticated_required`: true if the query covers type of fields marked with `@authenticated`
- `apollo::authorization::required_policies`: if the query covers type of fields marked with `@policy`, it contains a map of `policy name -> Option<bool>`. A coprocessor or rhai script can edit this map to mark `true` on authorization policies that succeed or `false` on ones that fail
- `apollo::authorization::required_scopes`: if the query covers type of fields marked with `@requiresScopes`, it contains the list of scopes used by those directive applications
- `apollo::demand_control::actual_cost`: calculated cost of the responses returned by the subgraphs; populated by the demand control plugin
- `apollo::demand_control::estimated_cost`: estimated cost of the requests to be sent to the subgraphs; populated by the demand control plugin
- `apollo::demand_control::result`: `COST_OK` if allowed, and `COST_TOO_EXPENSIVE` if rejected due to cost limits; populated by the demand control plugin
- `apollo::demand_control::strategy`: the name of the cost calculation strategy used by the demand control plugin
- `apollo::entity_cache::cached_keys_status`: a map of cache control statuses for cached entities, keyed by subgraph request id; populated by the entity caching plugin when `expose_keys_in_context` is turned on in the router configuration
- `apollo::expose_query_plan::enabled`: true if experimental query plan exposure is enabled
- `apollo::expose_query_plan::formatted_plan`: query plan formatted as text
- `apollo::expose_query_plan::plan`: contains the query plan serialized as JSON (editing it has no effect on execution)
- `apollo::progressive_override::labels_to_override`: used in progressive override, list of labels for which we need an override
- `apollo::progressive_override::unresolved_labels`: used in progressive override, contains the list of unresolved labels
- `apollo::supergraph::first_event`: false if the current response chunk is not the first response in the stream, nonexistent otherwise
- `apollo::supergraph::operation_id`: contains the usage reporting stats report key
- `apollo::supergraph::operation_kind`: can be `query`, `mutation` or `subscription`
- `apollo::supergraph::operation_name`: name of the operation being executed (according to the query and the `operation_name` field in the request)
- `apollo::telemetry::client_name`: client name extracted from the client name header
- `apollo::telemetry::client_version`: client version extracted from the client version header
- `apollo::telemetry::contains_graphql_error`: true if the response contains at least one error
- `apollo::telemetry::studio_exclude`: true if the current request's trace details should be excluded from Studio
- `apollo::telemetry::subgraph_ftv1`: JSON-serialized trace data returned by the subgraph when FTV1 is enabled
See the [Coprocessor Reference documentation](/graphos/routing/customization/coprocessor/reference#context-key-reference) for a complete list of available context keys.

Check notice on line 97 in docs/source/routing/customization/overview.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/routing/customization/overview.mdx#L97 

Rephrase the sentence to better align with linking best practices, which recommend placing links at the end of a sentence when possible.

```suggestion
For a complete list of available context keys, see the [Coprocessor Reference documentation](/graphos/routing/customization/coprocessor/reference#context-key-reference).
```
Comment thread
faisalwaseem marked this conversation as resolved.

## Creating customizations

Expand Down