diff --git a/.changesets/docs_doc_context_keylist.md b/.changesets/docs_doc_context_keylist.md new file mode 100644 index 0000000000..1841b65dd6 --- /dev/null +++ b/.changesets/docs_doc_context_keylist.md @@ -0,0 +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. + +By [@faisalwaseem](https://github.com/faisalwaseem) in https://github.com/apollographql/router/pull/8420 diff --git a/docs/source/routing/customization/coprocessor/reference.mdx b/docs/source/routing/customization/coprocessor/reference.mdx index 277eddcc8b..cb0d89f224 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 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) + +#### 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`. 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 +- `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 +- `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` 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