Apollo Router
2.8.2Schema URL
The configuration for the router.
Can be created through serde::Deserialize from various formats,
or inline in Rust code with serde_json::json! and serde_json::from_value.
Properties
Configuration options pertaining to the health component.
4 nested properties
The socket address and port to listen on Defaults to 127.0.0.1:8088
Set to false to disable the health check
Optionally set a custom healthcheck path Defaults to /health
Optionally specify readiness configuration
{
"interval": {
"sampling": "5s",
"unready": null
},
"allowed": 100
}Configuration for the server
{
"http": {
"header_read_timeout": {
"secs": 10,
"nanos": 0
}
}
}Configuration for the supergraph
{
"listen": "127.0.0.1:4000",
"connection_shutdown_timeout": {
"secs": 60,
"nanos": 0
},
"path": "/",
"introspection": false,
"generate_query_fragments": true,
"defer_support": true,
"query_planning": {
"cache": {
"in_memory": {
"limit": 512
},
"redis": null
},
"warmed_up_queries": null,
"experimental_plans_limit": null,
"experimental_paths_limit": null,
"experimental_reuse_query_plans": false,
"experimental_cooperative_cancellation": {
"enabled": true,
"mode": "measure",
"timeout": null
}
},
"early_cancel": false,
"enable_result_coercion_errors": false,
"experimental_log_on_broken_pipe": false
}Cross origin request headers.
{
"allow_any_origin": false,
"allow_credentials": false,
"allow_headers": [],
"expose_headers": null,
"methods": [
"GET",
"POST",
"OPTIONS"
],
"max_age": null,
"policies": [
{
"allow_credentials": null,
"allow_headers": [],
"expose_headers": [],
"match_origins": [],
"max_age": null,
"methods": [
"GET",
"POST",
"OPTIONS"
],
"origins": [
"https://studio.apollographql.com"
]
}
]
}{
"supergraph": null,
"subgraph": {
"all": {
"certificate_authorities": null,
"client_authentication": null
},
"subgraphs": {}
},
"connector": {
"sources": {},
"all": {
"certificate_authorities": null,
"client_authentication": null
}
}
}Configures automatic persisted queries
{
"enabled": true,
"router": {
"cache": {
"in_memory": {
"limit": 512
},
"redis": null
}
},
"subgraph": {
"all": {
"enabled": false
},
"subgraphs": {}
}
}Configures managed persisted queries
{
"enabled": false,
"log_unknown": false,
"safelist": {
"enabled": false,
"require_id": false
},
"experimental_prewarm_query_plan_cache": {
"on_startup": false,
"on_reload": true
},
"local_manifests": null,
"hot_reload": false
}Configuration for operation limits, parser limits, HTTP limits, etc.
11 nested properties
If set, requests with operations deeper than this maximum
are rejected with a HTTP 400 Bad Request response and GraphQL error with
"extensions": {"code": "MAX_DEPTH_LIMIT"}
Counts depth of an operation, looking at its selection sets,˛ including fields in fragments and inline fragments. The following example has a depth of 3.
query getProduct {
book { # 1
...bookDetails
}
}
fragment bookDetails on Book {
details { # 2
... on ProductDetailsBook {
country # 3
}
}
}
If set, requests with operations higher than this maximum
are rejected with a HTTP 400 Bad Request response and GraphQL error with
"extensions": {"code": "MAX_DEPTH_LIMIT"}
Height is based on simple merging of fields using the same name or alias,
but only within the same selection set.
For example name here is only counted once and the query has height 3, not 4:
query {
name { first }
name { last }
}
This may change in a future version of Apollo Router to do full field merging across fragments instead.
If set, requests with operations with more root fields than this maximum
are rejected with a HTTP 400 Bad Request response and GraphQL error with
"extensions": {"code": "MAX_ROOT_FIELDS_LIMIT"}
This limit counts only the top level fields in a selection set, including fragments and inline fragments.
If set, requests with operations with more aliases than this maximum
are rejected with a HTTP 400 Bad Request response and GraphQL error with
"extensions": {"code": "MAX_ALIASES_LIMIT"}
If set to true (which is the default is dev mode),
requests that exceed a max_* limit are not rejected.
Instead they are executed normally, and a warning is logged.
Limit recursion in the GraphQL parser to protect against stack overflow. default: 500
Limit the number of tokens the GraphQL parser processes before aborting.
Limit the size of incoming HTTP requests read from the network, to protect against running out of memory. Default: 2000000 (2 MB)
Limit the maximum number of headers of incoming HTTP1 requests. Default is 100.
If router receives more headers than the buffer size, it responds to the client with "431 Request Header Fields Too Large".
Limit the maximum buffer size for the HTTP1 connection.
Default is ~400kib.
Limit the depth of nested list fields in introspection queries
to protect avoid generating huge responses. Returns a GraphQL
error with { message: "Maximum introspection depth exceeded" }
when nested fields exceed the limit.
Default: true
Configuration for chaos testing, trying to reproduce bugs that require uncommon conditions. You probably don’t want this in production!
{
"force_schema_reload": null,
"force_config_reload": null
}Authentication
3 nested properties
Router configuration
Subgraph configuration
Connector configuration
Authorization plugin
2 nested properties
Reject unauthenticated requests
@authenticated, @requiresScopes and @policy directives
Configuration for Apollo Connectors.
https://www.apollographql.com/docs/graphos/routing/configuration/yaml#connectors
8 nested properties
Map of subgraph_name.connector_source_name to source configuration
{}Enables connector debugging information on response extensions if the feature is enabled
The maximum number of requests for a connector source
When enabled, adds an entry to the context for use in coprocessors
{
"context": {
"entries": {
"apollo_connectors::sources_in_query_plan": [
{ "subgraph_name": "subgraph", "source_name": "source" }
]
}
}
}
Enables Connect spec v0.2 during the preview.
Feature gate for Connect spec v0.3. Set to true to enable the using
the v0.3 spec during the preview phase.
Feature gate for Connect spec v0.3. Set to true to enable the using
the v0.3 spec during the preview phase.
Configures the externalization plugin
8 nested properties
The url you'd like to offload processing to (can be overridden per-stage)
The timeout for external requests
{
"secs": 1,
"nanos": 0
}Response validation defaults to true
CSRF protection configuration.
See https://owasp.org/www-community/attacks/csrf for an explanation on CSRF attacks.
2 nested properties
The CSRF plugin is enabled by default.
Setting unsafe_disabled: true disables CSRF protection.
Override the headers to check for by setting
custom_headers
Note that if you set required_headers here,
you may also want to have a look at your CORS configuration,
and make sure you either:
- did not set any
allow_headerslist (so it defaults tomirror_request) - added your required headers to the allow_headers list, as shown in the
examples/cors-and-csrf/custom-headers.router.yamlfiles.
[
"x-apollo-operation-name",
"apollo-require-preflight"
]Demand control configuration
3 nested properties
Enable demand control
The mode that the demand control plugin should operate in.
- Measure: The plugin will measure the cost of incoming requests but not reject them.
- Enforce: The plugin will enforce the cost of incoming requests and reject them if the algorithm indicates that they should be rejected.
The enhanced client-awareness plugin has no configuration.
Configuration for the diagnostics plugin
Platform Requirements: This plugin is supported on all platforms. Heap dump functionality is only available on Linux platforms due to jemalloc requirements. Other diagnostic features work across platforms.
3 nested properties
Enable the diagnostics plugin
The socket address and port to listen on Defaults to 127.0.0.1:8089 Do not expose this endpoint to the internet as it exposes sensitive information.
Directory path for memory dump files Defaults to "/tmp/router-diagnostics" on Unix, or temp directory on other platforms
This directory will be created automatically if it doesn't exist. Note: Memory dumps are only generated on Linux platforms.
The fleet detector plugin has no configuration.
Forbid mutations configuration
Configuration for header propagation
3 nested properties
Rules to apply to all subgraphs
Rules to specific subgraphs
Configuration for exposing errors that originate from subgraphs
2 nested properties
Global configuration for error redaction. Applies to all subgraphs.
Overrides global configuration on a per-subgraph basis
{}The license enforcement plugin has no configuration.
Subgraph URL mappings
Configuration for entity caching
5 nested properties
Enable or disable the entity caching feature
Expose cache keys in context
Global invalidation configuration
Configuration for File Uploads plugin
2 nested properties
Whether the file upload plugin should be enabled (default: false)
Configuration for the progressive override plugin
Configuration for the Rhai Plugin
2 nested properties
The directory where Rhai scripts can be found
The main entry point for Rhai script evaluation
Subscriptions configuration
5 nested properties
Enable subscription
Select a subscription mode (callback or passthrough)
{
"callback": null,
"passthrough": null
}Configure subgraph subscription deduplication
{
"enabled": true,
"ignored_headers": []
}This is a limit to only have maximum X opened subscriptions at the same time. By default if it's not set there is no limit.
It represent the capacity of the in memory queue to know how many events we can keep in a buffer
Configuration for the traffic shaping plugin
5 nested properties
Applied at the router level
Applied on all subgraphs
Applied on specific subgraphs
DEPRECATED, now always enabled: Enable variable deduplication optimization when sending requests to subgraphs (https://github.com/apollographql/router/issues/87)
Batching configuration.
{
"enabled": false,
"mode": "batch_http_link",
"subgraph": null,
"maximum_size": null
}Type conditioned fetching configuration.
Definitions
Configuration options pertaining to the health component.
The socket address and port to listen on Defaults to 127.0.0.1:8088
Set to false to disable the health check
Optionally set a custom healthcheck path Defaults to /health
Optionally specify readiness configuration
{
"interval": {
"sampling": "5s",
"unready": null
},
"allowed": 100
}Listening address.
Configuration options pertaining to the readiness health sub-component.
The readiness interval configuration
{
"sampling": "5s",
"unready": null
}How many rejections are allowed in an interval (default: 100) If this number is exceeded, the router will start to report unready.
Configuration options pertaining to the readiness health interval sub-component.
The sampling interval (default: 5s)
The unready interval (default: 2 * sampling interval)
Configuration options pertaining to the sandbox page.
Set to true to enable sandbox
Configuration options pertaining to the home page.
Set to false to disable the homepage
Graph reference This will allow you to redirect from the Apollo Router landing page back to Apollo Studio Explorer
The server http configuration
{
"header_read_timeout": {
"secs": 10,
"nanos": 0
}
}Configuration for HTTP
Header read timeout in human-readable format; defaults to 10s
{
"secs": 10,
"nanos": 0
}Configuration options pertaining to the supergraph server component.
The socket address and port to listen on Defaults to 127.0.0.1:4000
The timeout for shutting down connections during a router shutdown or a schema reload.
{
"secs": 60,
"nanos": 0
}The HTTP path on which GraphQL requests will be served. default: "/"
Enable introspection Default: false
Enable QP generation of fragments for subgraph requests Default: true
Set to false to disable defer support
Query planning options
{
"cache": {
"in_memory": {
"limit": 512
},
"redis": null
},
"warmed_up_queries": null,
"experimental_plans_limit": null,
"experimental_paths_limit": null,
"experimental_reuse_query_plans": false,
"experimental_cooperative_cancellation": {
"enabled": true,
"mode": "measure",
"timeout": null
}
}abort request handling when the client drops the connection. Default: false. When set to true, some parts of the request pipeline like telemetry will not work properly, but request handling will stop immediately when the client connection is closed.
Enable errors generated during response reformatting and result coercion to be returned in responses. Default: false All subgraph responses are checked and corrected to ensure alignment with the schema and query. When enabled, misaligned values will generate errors which are included in errors array in the response.
Log a message if the client closes the connection before the response is sent. Default: false.
Query planning cache configuration
Warms up the cache on reloads by running the query plan over a list of the most used queries (from the in memory cache) Configures the number of queries warmed up. Defaults to 1/3 of the in memory cache
Sets a limit to the number of generated query plans. The planning process generates many different query plans as it explores the graph, and the list can grow large. By using this limit, we prevent that growth and still get a valid query plan, but it may not be the optimal one.
The default limit is set to 10000, but it may change in the future
Before creating query plans, for each path of fields in the query we compute all the possible options to traverse that path via the subgraphs. Multiple options can arise because fields in the path can be provided by multiple subgraphs, and abstract types (i.e. unions and interfaces) returned by fields sometimes require the query planner to traverse through each constituent object type. The number of options generated in this computation can grow large if the schema or query are sufficiently complex, and that will increase the time spent planning.
This config allows specifying a per-path limit to the number of options considered. If any path's options exceeds this limit, query planning will abort and the operation will fail.
The default value is None, which specifies no limit.
If cache warm up is configured, this will allow the router to keep a query plan created with the old schema, if it determines that the schema update does not affect the corresponding query
Configures cooperative cancellation of query planning
See [CooperativeCancellation] for more details.
{
"enabled": true,
"mode": "measure",
"timeout": null
}Cache configuration
Configures and activates the Redis cache
In memory cache configuration
Number of entries in the Least Recently Used cache
Redis cache configuration
List of URLs to the Redis cluster
Redis username if not provided in the URLs. This field takes precedence over the username in the URL
Redis password if not provided in the URLs. This field takes precedence over the password in the URL
Redis request timeout (default: 500ms)
{
"secs": 0,
"nanos": 0
}TTL for entries
{
"secs": 2592000,
"nanos": 0
}namespace used to prefix Redis keys
TLS client configuration
Prevents the router from starting if it cannot connect to Redis
When a TTL is set on a key, reset it when reading the data from that key
The size of the Redis connection pool
Configuration options pertaining to the subgraph server component.
list of certificate authorities in PEM format
client certificate authentication
TLS client authentication
list of certificates in PEM format
key in PEM format
When true, cooperative cancellation is enabled.
When enabled, this sets whether the router will cancel query planning or merely emit a metric when it would have happened.
Enable timeout for query planning.
Cross origin request configuration.
Set to true to allow any origin. Defaults to false. This is the only way to allow Origin: null.
Set to true to add the Access-Control-Allow-Credentials header.
The headers to allow.
If this value is not set, the router will mirror client's Access-Control-Request-Headers.
Note that if you set headers here,
you also want to have a look at your CSRF plugins configuration,
and make sure you either:
- accept
x-apollo-operation-nameAND / ORapollo-require-preflight - defined
csrfrequired headers in your yml configuration, as shown in theexamples/cors-and-csrf/custom-headers.router.yamlfiles.
[]Which response headers should be made available to scripts running in the browser, in response to a cross-origin request.
Allowed request methods. See module documentation for default behavior.
[
"GET",
"POST",
"OPTIONS"
]The Access-Control-Max-Age header value in time units
The origin(s) to allow requests from. The router matches request origins against policies in order, first by exact match, then by regex. See module documentation for default behavior.
[
{
"allow_credentials": null,
"allow_headers": [],
"expose_headers": [],
"match_origins": [],
"max_age": null,
"methods": [
"GET",
"POST",
"OPTIONS"
],
"origins": [
"https://studio.apollographql.com"
]
}
]Configuration for a specific set of origins
Set to true to add the Access-Control-Allow-Credentials header for these origins
The headers to allow for these origins
[]Which response headers should be made available to scripts running in the browser
[]Regex patterns to match origins against.
[]The Access-Control-Max-Age header value in time units
Allowed request methods for these origins.
The origins to allow requests from.
[
"https://studio.apollographql.com"
]TLS related configuration options.
TLS server configuration
This will affect the GraphQL endpoint and any other endpoint targeting the same listen address.
Outgoing TLS configuration to subgraphs.
{
"all": {
"certificate_authorities": null,
"client_authentication": null
},
"subgraphs": {}
}Outgoing TLS configuration to Apollo Connectors.
{
"sources": {},
"all": {
"certificate_authorities": null,
"client_authentication": null
}
}Configuration options pertaining to the supergraph server component.
server certificate in PEM format
server key in PEM format
list of certificate authorities in PEM format
Automatic Persisted Queries (APQ) configuration
Activates Automatic Persisted Queries (enabled by default)
Router level (APQ) configuration
Cache configuration
Configures and activates the Redis cache
Redis cache configuration
List of URLs to the Redis cluster
Redis username if not provided in the URLs. This field takes precedence over the username in the URL
Redis password if not provided in the URLs. This field takes precedence over the password in the URL
Redis request timeout (default: 500ms)
{
"secs": 0,
"nanos": 0
}TTL for entries
namespace used to prefix Redis keys
TLS client configuration
Prevents the router from starting if it cannot connect to Redis
When a TTL is set on a key, reset it when reading the data from that key
The size of the Redis connection pool
Interval for collecting Redis metrics (default: 1s)
{
"secs": 0,
"nanos": 0
}Configuration options pertaining to the subgraph server component.
Subgraph level Automatic Persisted Queries (APQ) configuration
Enable
Persisted Queries (PQ) configuration
Activates Persisted Queries (disabled by default)
Enabling this field configures the router to log any freeform GraphQL request that is not in the persisted query list
Restricts execution of operations that are not found in the Persisted Query List
{
"enabled": false,
"require_id": false
}Experimental feature to prewarm the query plan cache with persisted queries
{
"on_startup": false,
"on_reload": true
}Enables using a local copy of the persisted query manifest to safelist operations
Enables hot reloading of the local persisted query manifests
Persisted Queries (PQ) Safelisting configuration
Enables using the persisted query list as a safelist (disabled by default)
Enabling this field configures the router to reject any request that does not include the persisted query ID
Persisted Queries (PQ) query plan cache prewarm configuration
Enabling this field uses the persisted query list to pre-warm the query planner cache on startup (disabled by default)
Enabling this field uses the persisted query list to pre-warm the query planner cache on schema and config changes (enabled by default)
Configuration for operation limits, parser limits, HTTP limits, etc.
If set, requests with operations deeper than this maximum
are rejected with a HTTP 400 Bad Request response and GraphQL error with
"extensions": {"code": "MAX_DEPTH_LIMIT"}
Counts depth of an operation, looking at its selection sets,˛ including fields in fragments and inline fragments. The following example has a depth of 3.
query getProduct {
book { # 1
...bookDetails
}
}
fragment bookDetails on Book {
details { # 2
... on ProductDetailsBook {
country # 3
}
}
}
If set, requests with operations higher than this maximum
are rejected with a HTTP 400 Bad Request response and GraphQL error with
"extensions": {"code": "MAX_DEPTH_LIMIT"}
Height is based on simple merging of fields using the same name or alias,
but only within the same selection set.
For example name here is only counted once and the query has height 3, not 4:
query {
name { first }
name { last }
}
This may change in a future version of Apollo Router to do full field merging across fragments instead.
If set, requests with operations with more root fields than this maximum
are rejected with a HTTP 400 Bad Request response and GraphQL error with
"extensions": {"code": "MAX_ROOT_FIELDS_LIMIT"}
This limit counts only the top level fields in a selection set, including fragments and inline fragments.
If set, requests with operations with more aliases than this maximum
are rejected with a HTTP 400 Bad Request response and GraphQL error with
"extensions": {"code": "MAX_ALIASES_LIMIT"}
If set to true (which is the default is dev mode),
requests that exceed a max_* limit are not rejected.
Instead they are executed normally, and a warning is logged.
Limit recursion in the GraphQL parser to protect against stack overflow. default: 500
Limit the number of tokens the GraphQL parser processes before aborting.
Limit the size of incoming HTTP requests read from the network, to protect against running out of memory. Default: 2000000 (2 MB)
Limit the maximum number of headers of incoming HTTP1 requests. Default is 100.
If router receives more headers than the buffer size, it responds to the client with "431 Request Header Fields Too Large".
Limit the maximum buffer size for the HTTP1 connection.
Default is ~400kib.
Limit the depth of nested list fields in introspection queries
to protect avoid generating huge responses. Returns a GraphQL
error with { message: "Maximum introspection depth exceeded" }
when nested fields exceed the limit.
Default: true
Configuration for chaos testing, trying to reproduce bugs that require uncommon conditions. You probably don't want this in production!
How Chaos Reloading Works
The chaos system automatically captures and replays the last known schema and configuration events to force hot reloads even when the underlying content hasn't actually changed. This is particularly useful for memory leak detection during hot reload scenarios. If configured, it will activate upon the first config event that is encountered.
Schema Reloading (force_schema_reload)
When enabled, the router will periodically replay the last schema event with a timestamp
comment injected into the SDL (e.g., # Chaos reload timestamp: 1234567890). This ensures
the schema is seen as "different" and triggers a full hot reload, even though the functional
schema content is identical.
Configuration Reloading (force_config_reload)
When enabled, the router will periodically replay the last configuration event. The configuration is cloned and re-emitted, which triggers the router's configuration change detection and reload logic.
Example Usage
experimental_chaos:
force_schema_reload: "30s" # Trigger schema reload every 30 seconds
force_config_reload: "2m" # Trigger config reload every 2 minutes
Force a hot reload of the schema at regular intervals by injecting a timestamp comment into the SDL. This ensures schema reloads occur even when the functional schema content hasn't changed, which is useful for testing memory leaks during schema hot reloads.
The system automatically captures the last schema event and replays it with a timestamp comment added to make it appear "different" to the reload detection logic.
Force a hot reload of the configuration at regular intervals by replaying the last configuration event. This triggers the router's configuration change detection even when the configuration content hasn't actually changed.
The system automatically captures the last configuration event and replays it to force configuration reload processing.
This is a broken plugin for testing purposes only.
1 nested properties
Enable the broken plugin.
Expose query plan
Request recording configuration.
2 nested properties
The recording plugin is disabled by default.
The path to the directory where recordings will be stored. Defaults to the current working directory.
Restricted plugin (for testing purposes only)
1 nested properties
Enable the restricted plugin (for testing purposes only)
This is a broken plugin for testing purposes only.
Enable the broken plugin.
Expose query plan
Request recording configuration.
The recording plugin is disabled by default.
The path to the directory where recordings will be stored. Defaults to the current working directory.
Restricted plugin (for testing purposes only)
Enable the restricted plugin (for testing purposes only)
Authentication
Router configuration
Subgraph configuration
Connector configuration
List of JWKS used to verify tokens
HTTP header expected to contain JWT
Header value prefix
Whether to ignore any mismatched prefixes
Alternative sources to extract the JWT
Control the behavior when an error occurs during the authentication process.
Defaults to Error. When set to Continue, requests that fail JWT authentication will
continue to be processed by the router, but without the JWT claims in the context. When set
to Error, requests that fail JWT authentication will be rejected with a HTTP 403 error.
Retrieve the JWK Set
Polling interval for each JWKS endpoint in human-readable format; defaults to 60s
{
"secs": 60,
"nanos": 0
}Expected issuers for tokens verified by that JWKS
If not specified, the issuer will not be checked.
Expected audiences for tokens verified by that JWKS
If not specified, the audience will not be checked.
List of accepted algorithms. Possible values are HS256, HS384, HS512, ES256, ES384, RS256, RS384, RS512, PS256, PS384, PS512, EdDSA
List of headers to add to the JWKS request
Insert a header
The name of the header
The value for the header
Configure subgraph authentication
Configuration that will apply to all subgraphs.
Create a configuration that will apply only to a specific subgraph.
{}Configure AWS sigv4 auth.
Hardcoded Config using access_key and secret. Prefer using DefaultChain instead.
The ID for this access key.
The secret key used to sign requests.
The AWS region this chain applies to.
The service you're trying to access, eg: "s3", "vpc-lattice-svcs", etc.
Specify assumed role configuration.
Specify assumed role configuration.
Amazon Resource Name (ARN) for the role assumed when making requests
Uniquely identify a session when the same role is assumed by different principals or for different reasons.
Unique identifier that might be required when you assume a role in another account.
Configuration of the DefaultChainProvider
The AWS region this chain applies to.
The service you're trying to access, eg: "s3", "vpc-lattice-svcs", etc.
The profile name used by this provider
Specify assumed role configuration.
Configure connector authentication
Authorization plugin
Reject unauthenticated requests
@authenticated, @requiresScopes and @policy directives
enables the @authenticated and @requiresScopes directives
generates the authorization error messages without modying the query
refuse a query entirely if any part would be filtered
authorization errors behaviour
{
"log": true,
"response": "errors"
}log authorization errors
location of authorization errors in the GraphQL response
Configuration for Apollo Connectors.
https://www.apollographql.com/docs/graphos/routing/configuration/yaml#connectors
Map of subgraph_name.connector_source_name to source configuration
{}Enables connector debugging information on response extensions if the feature is enabled
The maximum number of requests for a connector source
When enabled, adds an entry to the context for use in coprocessors
{
"context": {
"entries": {
"apollo_connectors::sources_in_query_plan": [
{ "subgraph_name": "subgraph", "source_name": "source" }
]
}
}
}
Enables Connect spec v0.2 during the preview.
Feature gate for Connect spec v0.3. Set to true to enable the using
the v0.3 spec during the preview phase.
Feature gate for Connect spec v0.3. Set to true to enable the using
the v0.3 spec during the preview phase.
Configuration for a connector subgraph
Other values that can be used by connectors via {$config.<key>}
{}Configuration for a @source directive
Other values that can be used by connectors via {$config.<key>}
{}Override the @source(http: {baseURL:})
The maximum number of requests for this source
Configures the externalization plugin
The url you'd like to offload processing to (can be overridden per-stage)
The timeout for external requests
{
"secs": 1,
"nanos": 0
}Response validation defaults to true
HTTP client configuration for coprocessors.
Use HTTP/2 to communicate with the coprocessor.
Specify a DNS resolution strategy to use when resolving the coprocessor URL.
What information is passed to a router request/response stage
Condition to trigger this stage
Send the headers
Send the body
Send the SDL
Send the path
Send the method
The coprocessor URL for this stage (overrides the global URL if specified)
Specify a condition for when an instrument should be mutated or an event should be triggered.
Configures the context
Configures the context
What information is passed to a router request/response stage
Condition to trigger this stage
Send the headers
Send the body
Send the SDL
Send the HTTP status
The coprocessor URL for this stage (overrides the global URL if specified)
What information is passed to a router request/response stage
7 nested properties
Condition to trigger this stage
Send the headers
Send the body
Send the SDL
Send the HTTP status
The coprocessor URL for this stage (overrides the global URL if specified)
What information is passed to a router request/response stage
Condition to trigger this stage
Send the headers
Send the body
Send the SDL
Send the method
The coprocessor URL for this stage (overrides the global URL if specified)
Specify a condition for when an instrument should be mutated or an event should be triggered.
What information is passed to a router request/response stage
Condition to trigger this stage
Send the headers
Send the body
Send the SDL
Send the HTTP status
The coprocessor URL for this stage (overrides the global URL if specified)
What information is passed to a router request/response stage
6 nested properties
Send the headers
Send the body
Send the SDL
Send the HTTP status
The coprocessor URL for this stage (overrides the global URL if specified)
What information is passed to a router request/response stage
Send the headers
Send the body
Send the SDL
Send the method
Send the query plan
The coprocessor URL for this stage (overrides the global URL if specified)
What information is passed to a router request/response stage
Send the headers
Send the body
Send the SDL
Send the HTTP status
The coprocessor URL for this stage (overrides the global URL if specified)
What information is passed to a subgraph request/response stage
What information is passed to a subgraph request/response stage
2 nested properties
What information is passed to a subgraph request/response stage
9 nested properties
Condition to trigger this stage
Send the headers
Send the body
Send the subgraph URI
Send the method URI
Send the service name
Send the subgraph request id
The coprocessor URL for this stage (overrides the global URL if specified)
What information is passed to a subgraph request/response stage
8 nested properties
Condition to trigger this stage
Send the headers
Send the body
Send the service name
Send the http status
Send the subgraph request id
The coprocessor URL for this stage (overrides the global URL if specified)
What information is passed to a subgraph request/response stage
What information is passed to a subgraph request/response stage
9 nested properties
Condition to trigger this stage
Send the headers
Send the body
Send the subgraph URI
Send the method URI
Send the service name
Send the subgraph request id
The coprocessor URL for this stage (overrides the global URL if specified)
What information is passed to a subgraph request/response stage
8 nested properties
Condition to trigger this stage
Send the headers
Send the body
Send the service name
Send the http status
Send the subgraph request id
The coprocessor URL for this stage (overrides the global URL if specified)
What information is passed to a subgraph request/response stage
Condition to trigger this stage
Send the headers
Send the body
Send the subgraph URI
Send the method URI
Send the service name
Send the subgraph request id
The coprocessor URL for this stage (overrides the global URL if specified)
Specify a condition for when an instrument should be mutated or an event should be triggered.
What information is passed to a subgraph request/response stage
Condition to trigger this stage
Send the headers
Send the body
Send the service name
Send the http status
Send the subgraph request id
The coprocessor URL for this stage (overrides the global URL if specified)
CSRF protection configuration.
See https://owasp.org/www-community/attacks/csrf for an explanation on CSRF attacks.
The CSRF plugin is enabled by default.
Setting unsafe_disabled: true disables CSRF protection.
Override the headers to check for by setting
custom_headers
Note that if you set required_headers here,
you may also want to have a look at your CORS configuration,
and make sure you either:
- did not set any
allow_headerslist (so it defaults tomirror_request) - added your required headers to the allow_headers list, as shown in the
examples/cors-and-csrf/custom-headers.router.yamlfiles.
[
"x-apollo-operation-name",
"apollo-require-preflight"
]Demand control configuration
Enable demand control
The mode that the demand control plugin should operate in.
- Measure: The plugin will measure the cost of incoming requests but not reject them.
- Enforce: The plugin will enforce the cost of incoming requests and reject them if the algorithm indicates that they should be rejected.
Algorithm for calculating the cost of an incoming query.
The enhanced client-awareness plugin has no configuration.
Configuration for the diagnostics plugin
Platform Requirements: This plugin is supported on all platforms. Heap dump functionality is only available on Linux platforms due to jemalloc requirements. Other diagnostic features work across platforms.
Enable the diagnostics plugin
The socket address and port to listen on Defaults to 127.0.0.1:8089 Do not expose this endpoint to the internet as it exposes sensitive information.
Directory path for memory dump files Defaults to "/tmp/router-diagnostics" on Unix, or temp directory on other platforms
This directory will be created automatically if it doesn't exist. Note: Memory dumps are only generated on Linux platforms.
Configuration for one subgraph for the mock_subgraphs plugin
HTTP headers for the subgraph response
Data for query operations (excluding the special _entities field)
In maps nested in this one (but not at the top level), the __cacheTags key is special.
Instead of representing a field that can be selected, when its parent field is selected
its value is expected to be an array which is appended
to the response.extensions["apolloCacheTags"] array.
{}Data for mutation operations
Entities that can be queried through Federation’s special _entities field
In maps directly in the top-level Vec (but not in other maps nested deeper),
the __cacheTags key is special.
Instead of representing a field that can be selected, when its parent entity is selected
its contents are added to the response.extensions["apolloEntityCacheTags"] array.
[]The fleet detector plugin has no configuration.
Forbid mutations configuration
Configuration for header propagation
Rules to apply to all subgraphs
Rules to specific subgraphs
Propagate/Insert/Remove headers from request
Insert header
Insert static header
The name of the header
The value for the header
Insert header with a value coming from context key
Specify header name
Specify context key to fetch value
Insert header with a value coming from body
The target header name
The path in the request body
The default if the path in the body did not resolve to an element
Remove header
Propagate header
Map of subgraph_name.connector_source_name to configuration
Options applying to all sources across all subgraphs
Configuration for exposing errors that originate from subgraphs
Global configuration for error redaction. Applies to all subgraphs.
Overrides global configuration on a per-subgraph basis
{}The license enforcement plugin has no configuration.
Subgraph URL mappings
Configuration for entity caching
Enable or disable the entity caching feature
Expose cache keys in context
Global invalidation configuration
Per subgraph configuration for entity caching
Redis configuration
expiration for all keys for this subgraph, unless overridden by the Cache-Control header in subgraph responses
activates caching for this subgraph, overrides the global configuration
Context key used to separate cache sections per user
Invalidation configuration
Per subgraph configuration for entity caching
Enable the invalidation
Shared key needed to request the invalidation endpoint
Specify on which path you want to listen for invalidation endpoint.
Listen address on which the invalidation endpoint must listen.
Number of keys to return at once from a redis SCAN command
Number of concurrent invalidation requests
Per subgraph configuration for entity caching
enables metrics evaluating the benefits of entity caching
Metrics counter TTL
Adds the entity type name to attributes. This can greatly increase the cardinality
Configuration for File Uploads plugin
Whether the file upload plugin should be enabled (default: false)
Configuration for the various protocols supported by the file upload plugin
Configuration for multipart requests.
This protocol conforms to jaydenseric's multipart spec
Configuration for a multipart request for file uploads.
This protocol conforms to jaydenseric's multipart spec
Whether to enable the multipart protocol for file uploads (default: true)
The supported mode for the request (default: [MultipartRequestMode::Stream])
Supported mode for a multipart request
Request limits for a multipart request
The maximum amount of files allowed for a single query (default: 4)
The maximum size of each file, in bytes (default: 5MB)
Configuration for response caching
Enable or disable the response caching feature
Enable debug mode for the debugger
Global invalidation configuration
Buffer size for known private queries (default: 2048)
Per subgraph configuration for response caching
Redis configuration
expiration for all keys for this subgraph, unless overridden by the Cache-Control header in subgraph responses
activates caching for this subgraph, overrides the global configuration
Context key used to separate cache sections per user
Invalidation configuration
Redis cache configuration
List of URLs to the Redis cluster
Redis username if not provided in the URLs. This field takes precedence over the username in the URL
Redis password if not provided in the URLs. This field takes precedence over the password in the URL
Timeout for Redis fetch commands (default: 150ms)
{
"secs": 0,
"nanos": 0
}Timeout for Redis insert commands (default: 500ms)
Inserts are processed asynchronously, so this will not affect response duration.
{
"secs": 0,
"nanos": 0
}Timeout for Redis invalidation commands (default: 1s)
{
"secs": 0,
"nanos": 0
}Timeout for Redis maintenance commands (default: 500ms)
Maintenance tasks are processed asynchronously, so this will not affect response duration.
{
"secs": 0,
"nanos": 0
}TTL for entries
namespace used to prefix Redis keys
TLS client configuration
Prevents the router from starting if it cannot connect to Redis
The size of the Redis connection pool (default: 5)
Interval for collecting Redis metrics (default: 1s)
{
"secs": 0,
"nanos": 0
}Per subgraph configuration for response caching
Enable the invalidation
Shared key needed to request the invalidation endpoint
Specify on which path you want to listen for invalidation endpoint.
Listen address on which the invalidation endpoint must listen.
Configuration for the progressive override plugin
Configuration for the Rhai Plugin
The directory where Rhai scripts can be found
The main entry point for Rhai script evaluation
Subscriptions configuration
Enable subscription
Select a subscription mode (callback or passthrough)
{
"callback": null,
"passthrough": null
}Configure subgraph subscription deduplication
{
"enabled": true,
"ignored_headers": []
}This is a limit to only have maximum X opened subscriptions at the same time. By default if it's not set there is no limit.
It represent the capacity of the in memory queue to know how many events we can keep in a buffer
Enable callback mode for subgraph(s)
Enable passthrough mode for subgraph(s)
Using a callback url
URL used to access this router instance, including the path configured on the Router
Listen address on which the callback must listen (default: 127.0.0.1:4000)
Specify on which path you want to listen for callbacks (default: /callback)
Specify on which subgraph we enable the callback mode for subscription If empty it applies to all subgraphs (passthrough mode takes precedence)
[]Configuration for all subgraphs
WebSocket configuration for a specific subgraph
Path on which WebSockets are listening
Which WebSocket GraphQL protocol to use for this subgraph possible values are: 'graphql_ws' | 'graphql_transport_ws' (default: graphql_ws)
Heartbeat interval for graphql-ws protocol (default: disabled)
Subscription deduplication configuration
Enable subgraph subscription deduplication. When enabled, multiple identical requests to the same subgraph will share one WebSocket connection in passthrough mode. (default: true)
List of headers to ignore for deduplication. Even if these headers are different, the subscription request is considered identical. For example, if you forward the "User-Agent" header, but the subgraph doesn't depend on the value of that header, adding it to this list will let the router dedupe subgraph subscriptions even if the header value is different.
[]Telemetry configuration
The Apollo Studio endpoint for exporting traces and metrics.
The Apollo Studio endpoint for exporting traces and metrics.
The name of the header to extract from requests when populating 'client name' for traces and metrics in Apollo Studio.
The name of the header to extract from requests when populating 'client version' for traces and metrics in Apollo Studio.
The buffer size for sending traces to Apollo. Increase this if you are experiencing lost traces.
Field level instrumentation for subgraphs via ftv1. ftv1 tracing can cause performance issues as it is transmitted in band with subgraph responses.
Percentage of traces to send via the OTel protocol when sending to Apollo Studio.
OTLP protocol used for OTel traces. Note this only applies if OTel traces are enabled and is only intended for use in tests.
OTLP protocol used for OTel metrics. Note this is only intended for use in tests.
To configure which request header names and values are included in trace data that's sent to Apollo Studio.
To configure which GraphQL variable values are included in trace data that's sent to Apollo Studio
Set the signature normalization algorithm to use when sending Apollo usage reports.
Set the Apollo usage report reference reporting mode to use.
Enable field metrics that are generated without FTV1 to be sent to Apollo Studio.
Enable sending additional subgraph metrics to Apollo Studio via OTLP
Forward headers
Forward GraphQL variables
Batch processor configuration
The delay interval in milliseconds between two consecutive processing of batches. The default value is 5 seconds.
{
"secs": 5,
"nanos": 0
}The maximum queue size to buffer spans for delayed processing. If the queue gets full it drops the spans. The default value is 2048.
The maximum number of spans to process in a single batch. If there are more than one batch worth of spans then it processes multiple batches of spans one batch after the other without any delay. The default value is 512.
The maximum duration to export a batch of data. The default value is 30 seconds.
{
"secs": 30,
"nanos": 0
}Maximum number of concurrent exports
Limits the number of spawned tasks for exports and thus memory consumed by an exporter. A value of 1 will cause exports to be performed synchronously on the BatchSpanProcessor task. The default is 1.
Configuration for exporting metrics via Apollo usage reports.
Batch processor config for OTLP metrics.
The delay interval in milliseconds between two consecutive processing of batches. The default value is 5 seconds.
{
"secs": 5,
"nanos": 0
}The maximum duration to export a batch of data. The default value is 30 seconds.
{
"secs": 30,
"nanos": 0
}Batch processor config for Apollo usage report metrics.
The delay interval in milliseconds between two consecutive processing of batches. The default value is 5 seconds.
{
"secs": 5,
"nanos": 0
}The maximum queue size to buffer spans for delayed processing. If the queue gets full it drops the reports. The default value is 2048.
The maximum duration to export a batch of data. The default value is 30 seconds.
{
"secs": 30,
"nanos": 0
}Send error metrics via OTLP with additional dimensions [extensions.service, extensions.code]
Handling of errors coming from specified subgraphs
Send subgraph errors to Apollo Studio
Redact subgraph errors to Apollo Studio
Allows additional dimension extensions.code to be sent with errors
even when redact is set to true. Has no effect when redact is false.
Allow some error fields to be send to Apollo Studio even when redact is true.
Extended Open Telemetry error metrics mode
Apollo usage report signature normalization algorithm
Apollo usage report reference generation modes.
Logging configuration.
Set a service.name resource in your metrics
Set a service.namespace attribute in your metrics
Set to true to log to stdout.
The format to log to stdout when you're running on an interactive terminal. When configured it will automatically use this tty_format`` instead of the original format` when an interactive terminal is detected
Set to true to limit the rate of log messages
Number of log lines allowed in interval per message
Interval for rate limiting
{
"secs": 1,
"nanos": 0
}Metrics configuration
Set a service.name resource in your metrics
Set a service.namespace attribute in your metrics
Custom buckets for all histograms
[
0.001,
0.005,
0.015,
0.05,
0.1,
0.2,
0.3,
0.4,
0.5,
1.0,
5.0,
10.0
]Views applied on metrics
The instrument name you're targeting
Rename the metric to this name
This allows you to customize metric names for both OTLP and Prometheus exporters. Note: Prometheus will apply additional transformations (dots to underscores, unit suffixes). Apollo metrics are not affected by this rename - they will retain original names.
New description to set to the instrument
New unit to set to the instrument
New aggregation settings to set
An allow-list of attribute keys that will be preserved for the instrument.
Any attribute recorded for the instrument with a key not in this set will be
dropped. If the set is empty, all attributes will be dropped, if None all
attributes will be kept.
Enable otlp
The endpoint to send data to
gRPC configuration settings
{
"domain_name": null,
"ca": null,
"cert": null,
"key": null,
"metadata": {}
}Temporality for export (default: Cumulative).
Note that when exporting to Datadog agent use Delta.
The optional domain name for tls config. Note that domain name is will be defaulted to match the endpoint is not explicitly set.
The optional certificate authority (CA) certificate to be used in TLS configuration.
The optional cert for tls config
The optional private key file for TLS configuration.
gRPC metadata
{}Headers to send on report requests
{}Prometheus configuration
Set to true to enable
resource_selector is used to select which resource to export with every metrics.
The path where prometheus will be exposed
Tracing configuration
Expose the trace_id in response headers
Choose the header name to expose trace_id (default: apollo-trace-id)
Format of the trace ID in response headers
Configure propagation of traces. In general you won't have to do this as these are automatically configured along with any exporter you configure.
Select a custom request header to set your own trace_id (header value must be convertible from hexadecimal to set a correct trace_id)
Propagate baggage https://www.w3.org/TR/baggage/
Propagate trace context https://www.w3.org/TR/trace-context/
Propagate Jaeger
Propagate Datadog
Propagate Zipkin
Propagate AWS X-Ray
Choose the header name to expose trace_id (default: apollo-trace-id)
The trace ID format that will be used when propagating to subgraph services.
The trace service name
The trace service namespace
The sampler, always_on, always_off or a decimal between 0.0 and 1.0
Use datadog agent sampling. This means that all spans will be sent to the Datadog agent
and the sampling.priority attribute will be used to control if the span will then be sent to Datadog
Whether to use parent based sampling
The maximum events per span before discarding
The maximum attributes per span before discarding
The maximum links per span before discarding
The maximum attributes per event before discarding
The maximum attributes per link before discarding
Enable zipkin
Enable datadog
Enable datadog span mapping for span name and resource name.
Fixes the span names, this means that the APM view will show the original span names in the operation dropdown.
Custom mapping to be used as the resource field in spans, defaults to: router -> http.route supergraph -> graphql.operation.name query_planning -> graphql.operation.name subgraph -> subgraph.name subgraph_request -> subgraph.name http_request -> http.route
{}Which spans will be eligible for span stats to be collected for viewing in the APM view.
Defaults to true for request, router, query_parsing, supergraph, execution, query_planning, subgraph, subgraph_request, connect, connect_request and http_request.
{
"execution": true,
"request": true,
"parse_query": true,
"connect_request": true,
"router": true,
"http_request": true,
"connect": true,
"supergraph": true,
"subgraph_request": true,
"subgraph": true,
"query_planning": true
}Instrumentation configuration
Events are
An event that can be logged as part of a trace.
The event has an implicit type attribute that matches the name of the event in the yaml
and a message that can be used to provide additional information.
The event message.
The event conditions.
Log level configuration for events. Use "off" to not log the event, or a level name to log the event at that level and above.
When to trigger the event.
Common attributes for http server and client. See https://opentelemetry.io/docs/specs/semconv/http/http-spans/#common-attributes
The datadog trace ID. This can be output in logs and used to correlate traces in Datadog.
The OpenTelemetry trace ID. This can be output in logs.
All key values from trace baggage.
Describes a class of error the operation ended with. Examples:
- timeout
- name_resolution_error
- 500
Requirement level: Conditionally Required: If request has ended with an error.
The size of the request payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the Content-Length header. For requests using transport encoding, this should be the compressed size. Examples:
- 3495
Requirement level: Recommended
HTTP request method. Examples:
- GET
- POST
- HEAD
Requirement level: Required
The size of the response payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the Content-Length header. For requests using transport encoding, this should be the compressed size. Examples:
- 3495
Requirement level: Recommended
HTTP response status code. Examples:
- 200
Requirement level: Conditionally Required: If and only if one was received/sent.
OSI application layer or non-OSI equivalent. Examples:
- http
- spdy
Requirement level: Recommended: if not default (http).
Version of the protocol specified in network.protocol.name. Examples:
- 1.0
- 1.1
- 2
- 3
Requirement level: Recommended
OSI transport layer. Examples:
- tcp
- udp
Requirement level: Conditionally Required
OSI network layer or non-OSI equivalent. Examples:
- ipv4
- ipv6
Requirement level: Recommended
The matched route (path template in the format used by the respective server framework). Examples:
- /graphql
Requirement level: Conditionally Required: If and only if it’s available
Local socket address. Useful in case of a multi-IP host. Examples:
- 10.1.2.80
- /tmp/my.sock
Requirement level: Opt-In
Local socket port. Useful in case of a multi-port host. Examples:
- 65123
Requirement level: Opt-In
Peer address of the network connection - IP address or Unix domain socket name. Examples:
- 10.1.2.80
- /tmp/my.sock
Requirement level: Recommended
Peer port number of the network connection. Examples:
- 65123
Requirement level: Recommended
Name of the local HTTP server that received the request. Examples:
- example.com
- 10.1.2.80
- /tmp/my.sock
Requirement level: Recommended
Port of the local HTTP server that received the request. Examples:
- 80
- 8080
- 443
Requirement level: Recommended
The URI path component Examples:
- /search
Requirement level: Required
The URI query component Examples:
- q=OpenTelemetry
Requirement level: Conditionally Required: If and only if one was received/sent.
The URI scheme component identifying the used protocol. Examples:
- http
- https
Requirement level: Required
Value of the HTTP User-Agent header sent by the client. Examples:
- CERN-LineMode/2.15
- libwww/2.17b3
Requirement level: Recommended
Log the supergraph response
An event that can be logged as part of a trace.
The event has an implicit type attribute that matches the name of the event in the yaml
and a message that can be used to provide additional information.
The event message.
The event conditions.
Attributes for Cost
The GraphQL document being executed. Examples:
query findBookById { bookById(id: ?) { name } }
Requirement level: Recommended
The name of the operation being executed. Examples:
- findBookById
Requirement level: Recommended
The type of the operation being executed. Examples:
- query
- subscription
- mutation
Requirement level: Recommended
The estimated cost of the operation using the currently configured cost model
The actual cost of the operation using the currently configured cost model
The delta (estimated - actual) cost of the operation using the currently configured cost model
The cost result, this is an error code returned by the cost calculation or COST_OK
An event that can be logged as part of a trace.
The event has an implicit type attribute that matches the name of the event in the yaml
and a message that can be used to provide additional information.
The event message.
The event conditions.
The name of the subgraph Examples:
- products
Requirement level: Required
The GraphQL document being executed. Examples:
query findBookById { bookById(id: ?) { name } }
Requirement level: Recommended
The name of the operation being executed. Examples:
- findBookById
Requirement level: Recommended
The type of the operation being executed. Examples:
- query
- subscription
- mutation
Requirement level: Recommended
The number of times the request has been resent
Log the connector HTTP request
Log the connector HTTP response
An event that can be logged as part of a trace.
The event has an implicit type attribute that matches the name of the event in the yaml
and a message that can be used to provide additional information.
The event message.
The event conditions.
The name of the subgraph containing the connector Examples:
- posts
Requirement level: Required
The name of the source for this connector, if defined Examples:
- posts_api
Requirement level: Conditionally Required: If the connector has a source defined
The HTTP method for the connector Examples:
- GET
- POST
Requirement level: Required
The connector URL template, relative to the source base URL if one is defined Examples:
- /users/{$this.id!}/post
Requirement level: Required
Specify a condition for when an instrument should be mutated or an event should be triggered.
Use new OpenTelemetry spec compliant span attributes or preserve existing. This will be defaulted in future to spec_compliant, eventually removed in future.
The attributes to include by default in spans based on their level as specified in the otel semantic conventions and Apollo documentation.
Configuration of router spans. Log events inherit attributes from the containing span, so attributes configured here will be included on log events for a request. Router spans contain http request and response information and therefore contain http specific attributes.
Configuration of supergraph spans. Supergraph spans contain information about the graphql request and response and therefore contain graphql specific attributes.
Attributes to include on the subgraph span. Subgraph spans contain information about the subgraph request and response and therefore contain subgraph specific attributes.
Attributes to include on the connector span. Connector spans contain information about the connector request and response and therefore contain connector specific attributes.
Attributes to include on the HTTP client span. HTTP client spans contain information about HTTP requests made to subgraphs, including any changes made by Rhai scripts.
Span mode to create new or deprecated spans
Custom attributes that are attached to the router span.
Common attributes for http server and client. See https://opentelemetry.io/docs/specs/semconv/http/http-spans/#common-attributes
The datadog trace ID. This can be output in logs and used to correlate traces in Datadog.
The OpenTelemetry trace ID. This can be output in logs.
All key values from trace baggage.
Describes a class of error the operation ended with. Examples:
- timeout
- name_resolution_error
- 500
Requirement level: Conditionally Required: If request has ended with an error.
The size of the request payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the Content-Length header. For requests using transport encoding, this should be the compressed size. Examples:
- 3495
Requirement level: Recommended
HTTP request method. Examples:
- GET
- POST
- HEAD
Requirement level: Required
The size of the response payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the Content-Length header. For requests using transport encoding, this should be the compressed size. Examples:
- 3495
Requirement level: Recommended
HTTP response status code. Examples:
- 200
Requirement level: Conditionally Required: If and only if one was received/sent.
OSI application layer or non-OSI equivalent. Examples:
- http
- spdy
Requirement level: Recommended: if not default (http).
Version of the protocol specified in network.protocol.name. Examples:
- 1.0
- 1.1
- 2
- 3
Requirement level: Recommended
OSI transport layer. Examples:
- tcp
- udp
Requirement level: Conditionally Required
OSI network layer or non-OSI equivalent. Examples:
- ipv4
- ipv6
Requirement level: Recommended
The matched route (path template in the format used by the respective server framework). Examples:
- /graphql
Requirement level: Conditionally Required: If and only if it’s available
Local socket address. Useful in case of a multi-IP host. Examples:
- 10.1.2.80
- /tmp/my.sock
Requirement level: Opt-In
Local socket port. Useful in case of a multi-port host. Examples:
- 65123
Requirement level: Opt-In
Peer address of the network connection - IP address or Unix domain socket name. Examples:
- 10.1.2.80
- /tmp/my.sock
Requirement level: Recommended
Peer port number of the network connection. Examples:
- 65123
Requirement level: Recommended
Name of the local HTTP server that received the request. Examples:
- example.com
- 10.1.2.80
- /tmp/my.sock
Requirement level: Recommended
Port of the local HTTP server that received the request. Examples:
- 80
- 8080
- 443
Requirement level: Recommended
The URI path component Examples:
- /search
Requirement level: Required
The URI query component Examples:
- q=OpenTelemetry
Requirement level: Conditionally Required: If and only if one was received/sent.
The URI scheme component identifying the used protocol. Examples:
- http
- https
Requirement level: Required
Value of the HTTP User-Agent header sent by the client. Examples:
- CERN-LineMode/2.15
- libwww/2.17b3
Requirement level: Recommended
Custom attributes that are attached to the supergraph span.
Attributes for Cost
The GraphQL document being executed. Examples:
query findBookById { bookById(id: ?) { name } }
Requirement level: Recommended
The name of the operation being executed. Examples:
- findBookById
Requirement level: Recommended
The type of the operation being executed. Examples:
- query
- subscription
- mutation
Requirement level: Recommended
The estimated cost of the operation using the currently configured cost model
The actual cost of the operation using the currently configured cost model
The delta (estimated - actual) cost of the operation using the currently configured cost model
The cost result, this is an error code returned by the cost calculation or COST_OK
Custom attributes that are attached to the subgraph span.
The name of the subgraph Examples:
- products
Requirement level: Required
The GraphQL document being executed. Examples:
query findBookById { bookById(id: ?) { name } }
Requirement level: Recommended
The name of the operation being executed. Examples:
- findBookById
Requirement level: Recommended
The type of the operation being executed. Examples:
- query
- subscription
- mutation
Requirement level: Recommended
The number of times the request has been resent
Custom attributes that are attached to the connector span.
The name of the subgraph containing the connector Examples:
- posts
Requirement level: Required
The name of the source for this connector, if defined Examples:
- posts_api
Requirement level: Conditionally Required: If the connector has a source defined
The HTTP method for the connector Examples:
- GET
- POST
Requirement level: Required
The connector URL template, relative to the source base URL if one is defined Examples:
- /users/{$this.id!}/post
Requirement level: Required
Custom attributes that are attached to the HTTP client span.
Specify a condition for when an instrument should be mutated or an event should be triggered.
The attributes and instruments to include by default in instruments based on their level as specified in the otel semantic conventions and Apollo documentation.
Router service instruments. For more information see documentation on Router lifecycle.
Supergraph service instruments. For more information see documentation on Router lifecycle.
Subgraph service instruments. For more information see documentation on Router lifecycle.
Histogram of server request duration
Counter of active requests
Histogram of server request body size
Histogram of server response body size
Histogram of router overhead (time not spent in subgraph requests)
The description of the instrument.
The units of the instrument, e.g. "ms", "bytes", "requests".
Attributes to include on the instrument.
The instrument conditions.
The HTTP request method
The server address
The server port
The URL scheme
Empty attributes struct for router overhead - no standard attributes, only custom selectors
A histogram of the estimated cost of the operation using the currently configured cost model
A histogram of the actual cost of the operation using the currently configured cost model
A histogram of the delta between the estimated and actual cost of the operation using the currently configured cost model
The description of the instrument.
The units of the instrument, e.g. "ms", "bytes", "requests".
Attributes to include on the instrument.
The instrument conditions.
Histogram of client request duration
Histogram of client request body size
Histogram of client response body size
The description of the instrument.
The units of the instrument, e.g. "ms", "bytes", "requests".
Attributes to include on the instrument.
The instrument conditions.
Histogram of client request duration
Histogram of client request body size
Histogram of client response body size
The description of the instrument.
The units of the instrument, e.g. "ms", "bytes", "requests".
Attributes to include on the instrument.
The instrument conditions.
A histogram of the length of a selected field in the GraphQL response
A counter of the number of times a field is used.
The description of the instrument.
The units of the instrument, e.g. "ms", "bytes", "requests".
Attributes to include on the instrument.
The instrument conditions.
The GraphQL field name
The GraphQL field type
If the field is a list, the length of the list
The GraphQL operation name
The GraphQL type name
Specify a condition for when an instrument should be mutated or an event should be triggered.
A counter of times we have a cache hit or cache miss (deprecated)
A counter of times we have a cache hit or cache miss
The description of the instrument.
The units of the instrument, e.g. "ms", "bytes", "requests".
Attributes to include on the instrument.
The instrument conditions.
Entity type
Configuration for the traffic shaping plugin
Applied at the router level
Applied on all subgraphs
Applied on specific subgraphs
DEPRECATED, now always enabled: Enable variable deduplication optimization when sending requests to subgraphs (https://github.com/apollographql/router/issues/87)
The global concurrency limit
Enable global rate limiting
Enable timeout for incoming requests
Number of requests allowed
Per interval
Traffic shaping options
Enable query deduplication
Enable compression for subgraphs (available compressions are deflate, br, gzip)
Enable global rate limiting
Enable timeout for incoming requests
Enable HTTP2 for subgraphs
DNS resolution strategy for subgraphs
Applied on all connectors
Applied on specific connector sources
Enable compression for connectors (available compressions are deflate, br, gzip)
Enable global rate limiting
Enable timeout for connectors requests
Enable HTTP2 for connectors
DNS resolution strategy for connectors
Configuration for Batching
Activates Batching (disabled by default)
Subgraph options for batching
Maximum size for a batch
Configuration options pertaining to the subgraph server component.
Common options for configuring subgraph batching
Whether this batching config should be enabled