Spans
Add router lifecycle context to traces
A span captures contextual information about requests and responses as they're processed through the router's request lifecycle (pipeline). The information from spans can be used when displaying traces in your application performance monitors (APM).
Spans configuration
Router request lifecycle services
The Apollo Router's request lifecycle has three major services:
- Router service - Handles an incoming request before it is parsed. Works within a context of opaque bytes.
- Supergraph service - Handles a request after it has been parsed and before it is sent to the subgraph. Works within a GraphQL context.
- Subgraph service - Handles a request after it has been sent to the subgraph. Works within a GraphQL context.
The router
, supergraph
and subgraph
sections are used to define custom span configuration for each service:
telemetry:instrumentation:spans:router:attributes: {}# ...supergraph:attributes: {}# ...subgraph:attributes: {}# ...
attributes
Spans may have attributes attached to them from the Apollo Router pipeline. These attributes are used to filter and group spans in your APM.
Attributes may be drawn from standard attributes or selectors.
Granular customization of attributes on spans requires a GraphOS Dedicated or Enterprise plan.
The attributes that are available depend on the service of the pipeline.
telemetry:instrumentation:spans:router:attributes:# Standard attributeshttp.response.status_code: true# Custom attributes"my_attribute":response_header: "x-my-header"
default_attribute_requirement_level
The default_attribute_requirement_level
option sets the default attributes to attach to spans, as defined by OpenTelemetry semantic conventions.
Valid values:
required
(default)recommended
telemetry:instrumentation:spans:# Set the default requirement leveldefault_attribute_requirement_level: required
Attributes can be configured individually, so that required
attributes can be overridden or disabled. For example, http.response.status_code
is set individually to override the standard value:
telemetry:instrumentation:spans:# Set the default requirement leveldefault_attribute_requirement_level: requiredrouter:attributes:# Disable standard attributehttp.response.status_code: false
ⓘ NOTE
The attributes that the OpenTelemetry spec defines as opt-in
must be configured individually.
mode
The mode
option enables the router spans to either use legacy attributes in the router, or those defined in the OpenTelemetry specification.
Valid values:
spec_compliant
deprecated
(default)
spec_compliant
This mode follows the OpenTelemetry spec. Attributes that were previously added to spans that did not follow conventions are now removed.
You will likely gain a significant performance improvement by using this mode as it reduces the number of attributes that are added to spans.
telemetry:instrumentation:spans:mode: spec_compliant
For now this is not the default, however it will be in a future release.
deprecated
This mode is the default and follows the previous behavior if you have not configured the mode
option to spec_compliant
.
telemetry:instrumentation:spans:mode: deprecated
Attributes are added to spans that do not follow OpenTelemetry conventions.
ⓘ NOTE
The mode
option will be defaulted to spec_compliant
in a future release, and eventually removed.
Span configuration example
An example configuration of telemetry.spans
in router.yaml
sets both standard and custom attributes for the router service:
telemetry:instrumentation:spans:default_attribute_requirement_level: requiredmode: spec_compliantrouter:attributes:# Standard attributes (http)dd.trace_id: falsehttp.request.body.size: falsehttp.response.body.size: falsehttp.request.method: false# ...# Custom attributes"acme.custom_1":trace_id: datadog"acme.custom_2":response_header: "X-CUSTOM2"default: "unknown""acme.custom_3":env: "ENV_VAR""static_attribute": "my_static_value"# ...supergraph:attributes: {}# ...subgraph:attributes: {}# ...
Spans configuration reference
Option | Values | Default | Description |
---|---|---|---|
<attribute-name> | The name of the custom attribute. | ||
attributes | standard attributes|selectors | The attributes of the span. | |
default_attribute_requirement_level | required |recommended | required | The default attribute requirement level. |
legacy_request_span | true |false | Include the request span in traces. | |
mode | spec_compliant | deprecated | deprecated | The attributes of the span. |