OpenTelemetry standard attributes

Attach standard attributes to router telemetry

OpenTelemetry semantic conventions define a set of standard attributes that can be attached to spans. These attributes are used to filter and group data in your application performance monitor (APM).

The attributes available depend on the service of the router pipeline.

For example, set the standard attribute http.response.status_code on the router span:

router.yaml

1
telemetry:
2
  instrumentation:
3
    spans:
4
      router:
5
        attributes:
6
          # Standard attributes
7
          http.response.status_code: true

Attribute configuration reference

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.

Each service supports a unique set of standard attributes.

Router

Standard attributes of the router service:

Attribute	Values	Description
`error.type`		Describes a class of error the operation ended with
`http.request.body.size`		The size of the request payload body in bytes
`http.request.method`		HTTP request method
`http.request.method.original`		Original HTTP method sent by the client in the request line
`http.response.body.size`		The size of the response payload body in bytes
`http.response.status_code`		HTTP response status code
`network.protocol.name`		OSI application layer or non-OSI equivalent
`network.protocol.version`		Version of the protocol specified in network.protocol.name
`network.transport`		OSI transport layer
`network.type`		OSI network layer or non-OSI equivalent
`user_agent.original`		Value of the HTTP User-Agent header sent by the client
`client.address`		Client address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name
`client.port`		The port of the original client behind all proxies, if known (e.g. from Forwarded or a similar header). Otherwise, the immediate client peer port
`http.route`		The matched route (path template in the format used by the respective server framework)
`network.local.address`		Local socket address. Useful in case of a multi-IP host
`network.local.port`		Local socket port. Useful in case of a multi-port host
`network.peer.address`		Peer address of the network connection - IP address or Unix domain socket name
`network.peer.port`		Peer port number of the network connection
`server.address`		Name of the local HTTP server that received the request
`server.port`		Port of the local HTTP server that received the request
`url.path`		The URI path component
`url.query`		The URI query component
`url.scheme`		The scheme portion of the URL, such as "https" or "http"

ⓘ NOTE

The http.request.header.<key> and http.response.header.<key> attributes are not available as standard attributes, but they can be configured using a custom attribute.

For example, to configure an attribute for x-my-header on router spans:

router.yaml

1
telemetry:
2
  instrumentation:
3
    spans:
4
      router:
5
        attributes:
6
          "http.request.header.x-my-header":
7
            request_header: "x-my-header"

Supergraph

Standard attributes of the supergraph service:

Attribute	Values	Description
`graphql.operation.name`		The operation name from the graphql query
`graphql.operation.type`	`query`\|`mutation`\|`subscription`	The operation kind from the subgraph query
`graphql.document`		The GraphQL query to the subgraph

Subgraph

Standard attributes of the subgraph service:

Attribute	Values	Description
`subgraph.name`		The name of the subgraph
`subgraph.graphql.operation.name`		The operation name from the subgraph query
`subgraph.graphql.operation.type`	`query`\|`mutation`\|`subscription`	The operation kind from the subgraph query
`subgraph.graphql.document`		The GraphQL query to the subgraph

Selectors

Standard instruments