Docs
Launch GraphOS Studio

Spans

Add router lifecycle context to traces


A span captures contextual information about requests and responses as they're processed through the

. The information from spans can be used when displaying traces in your application performance monitors (APM).

Spans configuration

Router request lifecycle services

The '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 . Works within a 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:

router.yaml
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

or
selectors
.

Granular customization of attributes on spans requires a

.

The attributes that are available depend on the service of the pipeline.

desc.router.yaml
telemetry:
instrumentation:
spans:
router:
attributes:
# Standard attributes
http.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

.

Valid values:

  • required (default)
  • recommended
router.yaml
telemetry:
instrumentation:
spans:
# Set the default requirement level
default_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:

desc.router.yaml
telemetry:
instrumentation:
spans:
# Set the default requirement level
default_attribute_requirement_level: required
router:
attributes:
# Disable standard attribute
http.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 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.

router.yaml
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.

router.yaml
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:

router.yaml
telemetry:
instrumentation:
spans:
default_attribute_requirement_level: required
mode: spec_compliant
router:
attributes:
# Standard attributes (http)
dd.trace_id: false
http.request.body.size: false
http.response.body.size: false
http.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

OptionValuesDefaultDescription
<attribute-name>The name of the custom attribute.
attributes
standard attributes
|
selectors
The attributes of the span.
default_attribute_requirement_levelrequired|recommendedrequiredThe default attribute requirement level.
legacy_request_spantrue|falseInclude the request span in traces.
modespec_compliant | deprecateddeprecatedThe attributes of the span.
Previous
Zipkin
Next
Selectors
Edit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc.

Privacy Policy

Company