From 5b289e19334459336021d63095c835969be7654d Mon Sep 17 00:00:00 2001 From: Faisal Waseem <918131+faisalwaseem@users.noreply.github.com> Date: Tue, 14 Oct 2025 16:01:06 -0400 Subject: [PATCH 1/9] Adds comprehensive context key reference to docs --- .../customization/coprocessor/reference.mdx | 89 +++++++++++++++++++ 1 file changed, 89 insertions(+) diff --git a/docs/source/routing/customization/coprocessor/reference.mdx b/docs/source/routing/customization/coprocessor/reference.mdx index 277eddcc8b..f5e480b867 100644 --- a/docs/source/routing/customization/coprocessor/reference.mdx +++ b/docs/source/routing/customization/coprocessor/reference.mdx @@ -342,6 +342,95 @@ When `stage` is `ExecutionRequest`, this contains the query plan for the client +## Context key reference + +List of the context keys used in the Apollo Router for passing data through the plugin pipeline. + +--- + +### Core operation + +- **`apollo::supergraph::operation_name`** - Operation name from GraphQL query +- **`apollo::supergraph::operation_kind`** - Operation kind (Query/Mutation/Subscription) +- **`apollo::supergraph::operation_id`** - Apollo operation ID +- **`apollo::supergraph::first_event`** - First event marker for subscriptions +- **`apollo::supergraph_schema_id`** - Supergraph schema ID + +### Authentication & Authorization + +#### Authentication +- **`apollo::authentication::jwt_claims`** - JWT claims data +- **`apollo::authentication::jwt_status`** - JWT validation status (internal only) + +#### Authorization +- **`apollo::authorization::authentication_required`** - Authentication requirement flag +- **`apollo::authorization::required_scopes`** - Required OAuth scopes +- **`apollo::authorization::required_policies`** - Required authorization policies + +### Telemetry + +#### Client Information +- **`apollo::telemetry::client_name`** - Client application name +- **`apollo::telemetry::client_version`** - Client application version +- **`apollo::telemetry::client_library_name`** - Client library name +- **`apollo::telemetry::client_library_version`** - Client library version + +#### Telemetry Control +- **`apollo::telemetry::subgraph_ftv1`** - FTV1 tracing for subgraph +- **`apollo::telemetry::studio_exclude`** - Exclude from Studio reporting +- **`apollo::telemetry::contains_graphql_error`** - Response contains GraphQL errors +- **`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 Control (COST) + +- **`apollo::demand_control::estimated_cost`** - Estimated query cost +- **`apollo::demand_control::actual_cost`** - Actual query cost +- **`apollo::demand_control::result`** - Cost calculation result +- **`apollo::demand_control::strategy`** - 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`** - Entity cache keys status +- **`apollo::router::entity_cache_info_subgraph_{subgraph_name}`** - Entity cache info per subgraph (dynamic key with subgraph name suffix) + +#### APQ (Automatic Persisted Queries) +- **`apollo::apq::cache_hit`** - APQ cache hit indicator +- **`apollo::apq::registered`** - APQ registration indicator + +### Query Plan Exposure + +- **`apollo::expose_query_plan::plan`** - Query plan object +- **`apollo::expose_query_plan::formatted_plan`** - Formatted query plan string +- **`apollo::expose_query_plan::enabled`** - Query plan exposure enabled flag + +### Progressive Override + +- **`apollo::progressive_override::unresolved_labels`** - Unresolved override labels +- **`apollo::progressive_override::labels_to_override`** - Labels to override + +### Subscriptions + +- **`apollo::subscriptions::fatal_error`** - Fatal subscription error flag + +### Persisted Queries + +- **`apollo_persisted_queries::client_name`** - Client name for PQ operations +- **`apollo_persisted_queries::safelist::skip_enforcement`** - Skip safelist enforcement + +### Connectors + +- **`apollo_connectors::sources_in_query_plan`** - List of connector sources in query plan + +--- + ## Example requests by stage ### `RouterRequest` From c3376ca48c8ab0110bf2cb45e6a801b29bdfab36 Mon Sep 17 00:00:00 2001 From: Faisal Waseem <918131+faisalwaseem@users.noreply.github.com> Date: Tue, 14 Oct 2025 16:06:34 -0400 Subject: [PATCH 2/9] docs: Add comprehensive context key reference to documentation --- .changesets/docs_doc_context_keylist.md | 35 +++++++++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 .changesets/docs_doc_context_keylist.md diff --git a/.changesets/docs_doc_context_keylist.md b/.changesets/docs_doc_context_keylist.md new file mode 100644 index 0000000000..773eb1d10f --- /dev/null +++ b/.changesets/docs_doc_context_keylist.md @@ -0,0 +1,35 @@ +### Adds comprehensive context key reference to docs ([PR #8420](https://github.com/apollographql/router/pull/8420)) + + + + +--- + +**Checklist** + +Complete the checklist (and note appropriate exceptions) before the PR is marked ready-for-review. + +- [ ] PR description explains the motivation for the change and relevant context for reviewing +- [ ] PR description links appropriate GitHub/Jira tickets (creating when necessary) +- [ ] Changeset is included for user-facing changes +- [ ] Changes are compatible[^1] +- [x] Documentation[^2] completed +- [ ] Performance impact assessed and acceptable +- [ ] Metrics and logs are added[^3] and documented +- Tests added and passing[^4] + - [ ] Unit tests + - [ ] Integration tests + - [ ] Manual tests, as necessary + +**Exceptions** +This is only a change in documentation +*Note any exceptions here* + +**Notes** + +[^1]: It may be appropriate to bring upcoming changes to the attention of other (impacted) groups. Please endeavour to do this before seeking PR approval. The mechanism for doing this will vary considerably, so use your judgement as to how and when to do this. +[^2]: Configuration is an important part of many changes. Where applicable please try to document configuration examples. +[^3]: A lot of (if not most) features benefit from built-in observability and `debug`-level logs. Please read [this guidance](https://github.com/apollographql/router/blob/dev/dev-docs/metrics.md#adding-new-metrics) on metrics best-practices. +[^4]: Tick whichever testing boxes are applicable. If you are adding Manual Tests, please document the manual testing (extensively) in the Exceptions. + +By [@faisalwaseem](https://github.com/faisalwaseem) in https://github.com/apollographql/router/pull/8420 \ No newline at end of file From 40c64554062ddff4f0f37a05c9b784d640264a8e Mon Sep 17 00:00:00 2001 From: Faisal Waseem <918131+faisalwaseem@users.noreply.github.com> Date: Thu, 16 Oct 2025 09:58:36 -0400 Subject: [PATCH 3/9] Add context key reference to documentation This change documents all the context keys router supports as of submitting this PR. --- .changesets/docs_doc_context_keylist.md | 34 ++----------------------- 1 file changed, 2 insertions(+), 32 deletions(-) diff --git a/.changesets/docs_doc_context_keylist.md b/.changesets/docs_doc_context_keylist.md index 773eb1d10f..1841b65dd6 100644 --- a/.changesets/docs_doc_context_keylist.md +++ b/.changesets/docs_doc_context_keylist.md @@ -1,35 +1,5 @@ ### Adds comprehensive context key reference to docs ([PR #8420](https://github.com/apollographql/router/pull/8420)) - +This change documents all the context keys router supports as of submitting this PR. - ---- - -**Checklist** - -Complete the checklist (and note appropriate exceptions) before the PR is marked ready-for-review. - -- [ ] PR description explains the motivation for the change and relevant context for reviewing -- [ ] PR description links appropriate GitHub/Jira tickets (creating when necessary) -- [ ] Changeset is included for user-facing changes -- [ ] Changes are compatible[^1] -- [x] Documentation[^2] completed -- [ ] Performance impact assessed and acceptable -- [ ] Metrics and logs are added[^3] and documented -- Tests added and passing[^4] - - [ ] Unit tests - - [ ] Integration tests - - [ ] Manual tests, as necessary - -**Exceptions** -This is only a change in documentation -*Note any exceptions here* - -**Notes** - -[^1]: It may be appropriate to bring upcoming changes to the attention of other (impacted) groups. Please endeavour to do this before seeking PR approval. The mechanism for doing this will vary considerably, so use your judgement as to how and when to do this. -[^2]: Configuration is an important part of many changes. Where applicable please try to document configuration examples. -[^3]: A lot of (if not most) features benefit from built-in observability and `debug`-level logs. Please read [this guidance](https://github.com/apollographql/router/blob/dev/dev-docs/metrics.md#adding-new-metrics) on metrics best-practices. -[^4]: Tick whichever testing boxes are applicable. If you are adding Manual Tests, please document the manual testing (extensively) in the Exceptions. - -By [@faisalwaseem](https://github.com/faisalwaseem) in https://github.com/apollographql/router/pull/8420 \ No newline at end of file +By [@faisalwaseem](https://github.com/faisalwaseem) in https://github.com/apollographql/router/pull/8420 From 48b5b26de913d721e1ca0158cda7e149269880c1 Mon Sep 17 00:00:00 2001 From: Michelle Mabuyo Date: Thu, 16 Oct 2025 10:16:23 -0400 Subject: [PATCH 4/9] style: remove bold from codefont --- .../customization/coprocessor/reference.mdx | 80 +++++++++---------- 1 file changed, 40 insertions(+), 40 deletions(-) diff --git a/docs/source/routing/customization/coprocessor/reference.mdx b/docs/source/routing/customization/coprocessor/reference.mdx index f5e480b867..f386f7a31e 100644 --- a/docs/source/routing/customization/coprocessor/reference.mdx +++ b/docs/source/routing/customization/coprocessor/reference.mdx @@ -350,84 +350,84 @@ List of the context keys used in the Apollo Router for passing data through the ### Core operation -- **`apollo::supergraph::operation_name`** - Operation name from GraphQL query -- **`apollo::supergraph::operation_kind`** - Operation kind (Query/Mutation/Subscription) -- **`apollo::supergraph::operation_id`** - Apollo operation ID -- **`apollo::supergraph::first_event`** - First event marker for subscriptions -- **`apollo::supergraph_schema_id`** - Supergraph schema ID +- `apollo::supergraph::operation_name` - Operation name from GraphQL query +- `apollo::supergraph::operation_kind` - Operation kind (Query/Mutation/Subscription) +- `apollo::supergraph::operation_id` - Apollo operation ID +- `apollo::supergraph::first_event` - First event marker for subscriptions +- `apollo::supergraph_schema_id` - Supergraph schema ID ### Authentication & Authorization #### Authentication -- **`apollo::authentication::jwt_claims`** - JWT claims data -- **`apollo::authentication::jwt_status`** - JWT validation status (internal only) +- `apollo::authentication::jwt_claims` - JWT claims data +- `apollo::authentication::jwt_status` - JWT validation status (internal only) #### Authorization -- **`apollo::authorization::authentication_required`** - Authentication requirement flag -- **`apollo::authorization::required_scopes`** - Required OAuth scopes -- **`apollo::authorization::required_policies`** - Required authorization policies +- `apollo::authorization::authentication_required` - Authentication requirement flag +- `apollo::authorization::required_scopes` - Required OAuth scopes +- `apollo::authorization::required_policies` - Required authorization policies ### Telemetry #### Client Information -- **`apollo::telemetry::client_name`** - Client application name -- **`apollo::telemetry::client_version`** - Client application version -- **`apollo::telemetry::client_library_name`** - Client library name -- **`apollo::telemetry::client_library_version`** - Client library version +- `apollo::telemetry::client_name` - Client application name +- `apollo::telemetry::client_version` - Client application version +- `apollo::telemetry::client_library_name` - Client library name +- `apollo::telemetry::client_library_version` - Client library version #### Telemetry Control -- **`apollo::telemetry::subgraph_ftv1`** - FTV1 tracing for subgraph -- **`apollo::telemetry::studio_exclude`** - Exclude from Studio reporting -- **`apollo::telemetry::contains_graphql_error`** - Response contains GraphQL errors -- **`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) +- `apollo::telemetry::subgraph_ftv1` - FTV1 tracing for subgraph +- `apollo::telemetry::studio_exclude` - Exclude from Studio reporting +- `apollo::telemetry::contains_graphql_error` - Response contains GraphQL errors +- `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 Control (COST) -- **`apollo::demand_control::estimated_cost`** - Estimated query cost -- **`apollo::demand_control::actual_cost`** - Actual query cost -- **`apollo::demand_control::result`** - Cost calculation result -- **`apollo::demand_control::strategy`** - Cost calculation strategy used +- `apollo::demand_control::estimated_cost` - Estimated query cost +- `apollo::demand_control::actual_cost` - Actual query cost +- `apollo::demand_control::result` - Cost calculation result +- `apollo::demand_control::strategy` - 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) +- `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`** - Entity cache keys status -- **`apollo::router::entity_cache_info_subgraph_{subgraph_name}`** - Entity cache info per subgraph (dynamic key with subgraph name suffix) +- `apollo_entity_cache::key` - Entity cache key +- `apollo::entity_cache::cached_keys_status` - Entity cache keys status +- `apollo::router::entity_cache_info_subgraph_{subgraph_name}` - Entity cache info per subgraph (dynamic key with subgraph name suffix) #### APQ (Automatic Persisted Queries) -- **`apollo::apq::cache_hit`** - APQ cache hit indicator -- **`apollo::apq::registered`** - APQ registration indicator +- `apollo::apq::cache_hit` - APQ cache hit indicator +- `apollo::apq::registered` - APQ registration indicator ### Query Plan Exposure -- **`apollo::expose_query_plan::plan`** - Query plan object -- **`apollo::expose_query_plan::formatted_plan`** - Formatted query plan string -- **`apollo::expose_query_plan::enabled`** - Query plan exposure enabled flag +- `apollo::expose_query_plan::plan` - Query plan object +- `apollo::expose_query_plan::formatted_plan` - Formatted query plan string +- `apollo::expose_query_plan::enabled` - Query plan exposure enabled flag ### Progressive Override -- **`apollo::progressive_override::unresolved_labels`** - Unresolved override labels -- **`apollo::progressive_override::labels_to_override`** - Labels to override +- `apollo::progressive_override::unresolved_labels` - Unresolved override labels +- `apollo::progressive_override::labels_to_override` - Labels to override ### Subscriptions -- **`apollo::subscriptions::fatal_error`** - Fatal subscription error flag +- `apollo::subscriptions::fatal_error` - Fatal subscription error flag ### Persisted Queries -- **`apollo_persisted_queries::client_name`** - Client name for PQ operations -- **`apollo_persisted_queries::safelist::skip_enforcement`** - Skip safelist enforcement +- `apollo_persisted_queries::client_name` - Client name for PQ operations +- `apollo_persisted_queries::safelist::skip_enforcement` - Skip safelist enforcement ### Connectors -- **`apollo_connectors::sources_in_query_plan`** - List of connector sources in query plan +- `apollo_connectors::sources_in_query_plan` - List of connector sources in query plan --- From 19856045f193cfe0d5498dbdb5fcecae3bd07c24 Mon Sep 17 00:00:00 2001 From: Michelle Mabuyo Date: Thu, 16 Oct 2025 10:19:59 -0400 Subject: [PATCH 5/9] minor clarification edits --- .../routing/customization/coprocessor/reference.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/source/routing/customization/coprocessor/reference.mdx b/docs/source/routing/customization/coprocessor/reference.mdx index f386f7a31e..19fa2109a9 100644 --- a/docs/source/routing/customization/coprocessor/reference.mdx +++ b/docs/source/routing/customization/coprocessor/reference.mdx @@ -350,8 +350,8 @@ List of the context keys used in the Apollo Router for passing data through the ### Core operation -- `apollo::supergraph::operation_name` - Operation name from GraphQL query -- `apollo::supergraph::operation_kind` - Operation kind (Query/Mutation/Subscription) +- `apollo::supergraph::operation_name` - Operation name +- `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 - `apollo::supergraph_schema_id` - Supergraph schema ID @@ -382,7 +382,7 @@ List of the context keys used in the Apollo Router for passing data through the - `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 Control (COST) +### Demand / Cost Control - `apollo::demand_control::estimated_cost` - Estimated query cost - `apollo::demand_control::actual_cost` - Actual query cost @@ -401,7 +401,7 @@ List of the context keys used in the Apollo Router for passing data through the - `apollo::entity_cache::cached_keys_status` - Entity cache keys status - `apollo::router::entity_cache_info_subgraph_{subgraph_name}` - Entity cache info per subgraph (dynamic key with subgraph name suffix) -#### APQ (Automatic Persisted Queries) +#### Automatic Persisted Queries (APQ) - `apollo::apq::cache_hit` - APQ cache hit indicator - `apollo::apq::registered` - APQ registration indicator From 64636e6d71affa815fe27e0303fd6696812573a5 Mon Sep 17 00:00:00 2001 From: Michelle Mabuyo Date: Thu, 16 Oct 2025 10:24:37 -0400 Subject: [PATCH 6/9] style: sentence-case headings, remove trailing spaces --- .../customization/coprocessor/reference.mdx | 24 +++++++++---------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/source/routing/customization/coprocessor/reference.mdx b/docs/source/routing/customization/coprocessor/reference.mdx index 19fa2109a9..10baca9ca0 100644 --- a/docs/source/routing/customization/coprocessor/reference.mdx +++ b/docs/source/routing/customization/coprocessor/reference.mdx @@ -348,7 +348,7 @@ List of the context keys used in the Apollo Router for passing data through the --- -### Core operation +### Core operation - `apollo::supergraph::operation_name` - Operation name - `apollo::supergraph::operation_kind` - Operation kind (`Query`, `Mutation`, or `Subscription`) @@ -356,7 +356,7 @@ List of the context keys used in the Apollo Router for passing data through the - `apollo::supergraph::first_event` - First event marker for subscriptions - `apollo::supergraph_schema_id` - Supergraph schema ID -### Authentication & Authorization +### Authentication and authorization #### Authentication - `apollo::authentication::jwt_claims` - JWT claims data @@ -369,20 +369,20 @@ List of the context keys used in the Apollo Router for passing data through the ### Telemetry -#### Client Information +#### Client information - `apollo::telemetry::client_name` - Client application name - `apollo::telemetry::client_version` - Client application version - `apollo::telemetry::client_library_name` - Client library name - `apollo::telemetry::client_library_version` - Client library version -#### Telemetry Control +#### Telemetry control - `apollo::telemetry::subgraph_ftv1` - FTV1 tracing for subgraph - `apollo::telemetry::studio_exclude` - Exclude from Studio reporting - `apollo::telemetry::contains_graphql_error` - Response contains GraphQL errors - `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 / Cost Control +### Demand and cost control - `apollo::demand_control::estimated_cost` - Estimated query cost - `apollo::demand_control::actual_cost` - Actual query cost @@ -391,27 +391,27 @@ List of the context keys used in the Apollo Router for passing data through the ### Caching -#### Response Cache +#### 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 +#### Entity cache - `apollo_entity_cache::key` - Entity cache key - `apollo::entity_cache::cached_keys_status` - Entity cache keys status - `apollo::router::entity_cache_info_subgraph_{subgraph_name}` - Entity cache info per subgraph (dynamic key with subgraph name suffix) -#### Automatic Persisted Queries (APQ) +#### Automatic persisted queries (APQ) - `apollo::apq::cache_hit` - APQ cache hit indicator - `apollo::apq::registered` - APQ registration indicator -### Query Plan Exposure +### Query plan exposure - `apollo::expose_query_plan::plan` - Query plan object - `apollo::expose_query_plan::formatted_plan` - Formatted query plan string - `apollo::expose_query_plan::enabled` - Query plan exposure enabled flag -### Progressive Override +### Progressive override - `apollo::progressive_override::unresolved_labels` - Unresolved override labels - `apollo::progressive_override::labels_to_override` - Labels to override @@ -420,7 +420,7 @@ List of the context keys used in the Apollo Router for passing data through the - `apollo::subscriptions::fatal_error` - Fatal subscription error flag -### Persisted Queries +### Persisted queries - `apollo_persisted_queries::client_name` - Client name for PQ operations - `apollo_persisted_queries::safelist::skip_enforcement` - Skip safelist enforcement @@ -429,7 +429,7 @@ List of the context keys used in the Apollo Router for passing data through the - `apollo_connectors::sources_in_query_plan` - List of connector sources in query plan ---- +--- ## Example requests by stage From c6a281cc4579629d71bee4170b474d6e8c305733 Mon Sep 17 00:00:00 2001 From: Michelle Mabuyo Date: Thu, 16 Oct 2025 10:39:26 -0400 Subject: [PATCH 7/9] move duplicate info on context keys to reference page --- .../customization/coprocessor/reference.mdx | 50 ++++++++++--------- .../source/routing/customization/overview.mdx | 26 +--------- 2 files changed, 27 insertions(+), 49 deletions(-) diff --git a/docs/source/routing/customization/coprocessor/reference.mdx b/docs/source/routing/customization/coprocessor/reference.mdx index 10baca9ca0..73b168ba4b 100644 --- a/docs/source/routing/customization/coprocessor/reference.mdx +++ b/docs/source/routing/customization/coprocessor/reference.mdx @@ -350,44 +350,46 @@ List of the context keys used in the Apollo Router for passing data through the ### Core operation -- `apollo::supergraph::operation_name` - Operation name -- `apollo::supergraph::operation_kind` - Operation kind (`Query`, `Mutation`, or `Subscription`) +- `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 +- `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` - JWT claims data +- `apollo::authentication::jwt_claims` - Claims extracted from a JWT if present in the request - `apollo::authentication::jwt_status` - JWT validation status (internal only) #### Authorization -- `apollo::authorization::authentication_required` - Authentication requirement flag -- `apollo::authorization::required_scopes` - Required OAuth scopes -- `apollo::authorization::required_policies` - Required authorization policies +- `apollo::authorization::authentication_required` - True if the operation contains type of fields marked with `@authenticated` +- `apollo::authorization::required_scopes` - If the operation contains type of fields marked with `@requiresScopes`, it contains the list of scopes used +- `apollo::authorization::required_policies` - If the query contains type of fields marked with `@policy`, it contains a map of `policy name -> Option`. 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 application name -- `apollo::telemetry::client_version` - Client application version +- `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` - FTV1 tracing for subgraph -- `apollo::telemetry::studio_exclude` - Exclude from Studio reporting -- `apollo::telemetry::contains_graphql_error` - Response contains GraphQL errors +- `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 -- `apollo::demand_control::estimated_cost` - Estimated query cost -- `apollo::demand_control::actual_cost` - Actual query cost -- `apollo::demand_control::result` - Cost calculation result -- `apollo::demand_control::strategy` - Cost calculation strategy used +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 @@ -398,23 +400,23 @@ List of the context keys used in the Apollo Router for passing data through the #### Entity cache - `apollo_entity_cache::key` - Entity cache key -- `apollo::entity_cache::cached_keys_status` - Entity cache keys status +- `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` - APQ cache hit indicator -- `apollo::apq::registered` - APQ registration indicator +- `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 ### Query plan exposure -- `apollo::expose_query_plan::plan` - Query plan object -- `apollo::expose_query_plan::formatted_plan` - Formatted query plan string -- `apollo::expose_query_plan::enabled` - Query plan exposure enabled flag +- `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` - Unresolved override labels -- `apollo::progressive_override::labels_to_override` - Labels to 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 diff --git a/docs/source/routing/customization/overview.mdx b/docs/source/routing/customization/overview.mdx index b803854463..cdfca1cb82 100644 --- a/docs/source/routing/customization/overview.mdx +++ b/docs/source/routing/customization/overview.mdx @@ -94,31 +94,7 @@ In general, it's best to avoid buffering where possible. If necessary, it is ok 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`. 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. ## Creating customizations From 06786ad455b56ae35fce048e460e647cb14bcb18 Mon Sep 17 00:00:00 2001 From: Michelle Mabuyo Date: Thu, 16 Oct 2025 10:40:42 -0400 Subject: [PATCH 8/9] edit description --- docs/source/routing/customization/coprocessor/reference.mdx | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/source/routing/customization/coprocessor/reference.mdx b/docs/source/routing/customization/coprocessor/reference.mdx index 73b168ba4b..faa4910ac0 100644 --- a/docs/source/routing/customization/coprocessor/reference.mdx +++ b/docs/source/routing/customization/coprocessor/reference.mdx @@ -344,9 +344,7 @@ When `stage` is `ExecutionRequest`, this contains the query plan for the client ## Context key reference -List of the context keys used in the Apollo Router for passing data through the plugin pipeline. - ---- +List of context keys available from the router's request context, which is shared across stages of the processing pipeline. ### Core operation From e43791acb839f5a2e2139c2b303bc91c0e82eeb4 Mon Sep 17 00:00:00 2001 From: Michelle Mabuyo Date: Thu, 16 Oct 2025 10:47:22 -0400 Subject: [PATCH 9/9] librarian edits: codefont booleans, edit awkward phrasing --- .../routing/customization/coprocessor/reference.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/source/routing/customization/coprocessor/reference.mdx b/docs/source/routing/customization/coprocessor/reference.mdx index faa4910ac0..cb0d89f224 100644 --- a/docs/source/routing/customization/coprocessor/reference.mdx +++ b/docs/source/routing/customization/coprocessor/reference.mdx @@ -361,9 +361,9 @@ List of context keys available from the router's request context, which is share - `apollo::authentication::jwt_status` - JWT validation status (internal only) #### Authorization -- `apollo::authorization::authentication_required` - True if the operation contains type of fields marked with `@authenticated` -- `apollo::authorization::required_scopes` - If the operation contains type of fields marked with `@requiresScopes`, it contains the list of scopes used -- `apollo::authorization::required_policies` - If the query contains type of fields marked with `@policy`, it contains a map of `policy name -> Option`. 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::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`. A coprocessor or Rhai script can edit this map to mark `true` on authorization policies that succeed or `false` on ones that fail ### Telemetry @@ -403,7 +403,7 @@ The following keys are populated by the demand control plugin: #### 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 -- `apollo::apq::registered` - True if the request registered a query in APQ +- `apollo::apq::registered` - `true` if the request registered a query in APQ ### Query plan exposure