Metrics exporters

Export router metrics

The GraphOS Router and Apollo Router Core support collection of metrics with OpenTelemetry, with exporters for:

In router.yaml, you configure router metrics with the following settings:

telemetry.exporters.metrics.common. Configure values for the router which are common across metrics exporters.
telemetry.exporters.metrics.prometheus. Configure the Prometheus exporter.
telemetry.exporters.metrics.otlp. Configure the OpenTelemetry exporter. Supports sending traces to Datadog.

Metrics common configuration

Common metrics configuration contains global settings for all exporters:

`service_name`

Set a service name for your router metrics so you can easily locate them in external metrics dashboards.

The service name can be set by an environment variable or in router.yaml, with the following order of precedence (first to last):

OTEL_SERVICE_NAME environment variable
OTEL_RESOURCE_ATTRIBUTES environment variable

telemetry.exporters.metrics.common.service_name in router.yaml

Example service_name

Example setting service name in telemetry.exporters.metrics.common.service_name:

YAML

router.yaml

1telemetry:
2  exporters:
3    metrics:
4      common:
5        # (Optional) Set the service name to easily find metrics related to the apollo-router in your metrics dashboards
6        service_name: "router"

telemetry.exporters.metrics.common.resource in router.yaml

Example resource

Example setting service name in telemetry.exporters.metrics.common.resource:

YAML

router.yaml

1telemetry:
2  exporters:
3    metrics:
4      common:
5        resource:
6          # (Optional) Set the service name to easily find metrics related to the apollo-router in your metrics dashboards
7          "service.name": "router"

If the service name isn't explicitly set, it defaults to unknown_service:router or unknown_service if the executable name cannot be determined.

`resource`

A resource attribute is a set of key-value pairs that provide additional information to an exporter. It's an attribute of an OpenTelemetry resource. Application performance monitors (APM) can interpret and display resource information.

In router.yaml, resource attributes are set in telemetry.metrics.common.resource. For example:

YAML

router.yaml

1telemetry:
2  exporters:
3    metrics:
4      common:
5        resource:
6          "environment.name": "production"
7          "environment.namespace": "{env.MY_K8_NAMESPACE_ENV_VARIABLE}"

For OpenTelemetry conventions for resources, see Resource Semantic Conventions.

`buckets`

You can customize bucket boundaries for all generated histograms by setting telemetry.exporters.metrics.common.buckets in router.yaml. For example:

YAML

router.yaml

1telemetry:
2  exporters:
3    metrics:
4      common:
5        buckets:
6          - 0.05
7          - 0.10
8          - 0.25
9          - 0.50
10          - 1.00
11          - 2.50
12          - 5.00
13          - 10.00
14          - 20.00

`attributes`

You can add custom attributes (OpenTelemetry) and labels (Prometheus) to the apollo_router_http_requests metric. Attributes can be:

static values (preferably using a resource)
headers from the request or response
a value from a context
a value from the request or response body (JSON path)

note

Use resource attributes instead to provide information about telemetry resources, including hosts and environments.

An example of configuring these attributes is shown below:

YAML

router.yaml

1telemetry:
2  exporters:
3    metrics:
4      common:
5        attributes:
6          supergraph: # Attribute configuration for requests to/responses from the router
7            static:
8              - name: "version"
9                value: "v1.0.0"
10            request:
11              header:
12                - named: "content-type"
13                  rename: "payload_type"
14                  default: "application/json"
15                - named: "x-custom-header-to-add"
16            response:
17              body:
18                # Apply the value of the provided path of the router's response body as an attribute
19                - path: .errors[0].extensions.http.status
20                  name: error_from_body
21                # Use the unique extension code to identify the kind of error
22                - path: .errors[0].extensions.code
23                  name: error_code
24            context:
25              # Apply the indicated element from the plugin chain's context as an attribute
26              - named: my_key
27          subgraph: # Attribute configuration for requests to/responses from subgraphs
28            all:
29              static:
30                # Always apply this attribute to all metrics for all subgraphs
31                - name: kind
32                  value: subgraph_request
33              errors: # Only work if it's a valid GraphQL error (for example if the subgraph returns an http error or if the router can't reach the subgraph)
34                include_messages: true # Will include the error message in a message attribute
35                extensions: # Include extensions data
36                  - name: subgraph_error_extended_type # Name of the attribute
37                    path: .type # JSON query path to fetch data from extensions
38                  - name: message
39                    path: .reason
40              # Will create this kind of metric for example apollo_router_http_requests_error_total{message="cannot contact the subgraph",subgraph="my_subgraph_name",subgraph_error_extended_type="SubrequestHttpError"}
41            subgraphs:
42              my_subgraph_name: # Apply these rules only for the subgraph named `my_subgraph_name`
43                request:
44                  header:
45                    - named: "x-custom-header"
46                  body:
47                    # Apply the value of the provided path of the router's request body as an attribute (here it's the query)
48                    - path: .query
49                      name: query
50                      default: UNKNOWN

note

OpenTelemetry includes many standard attributes that you can use via custom instruments.

`views`

You can override default attributes and default buckets for specific metrics thanks to this configuration.

YAML

router.yaml

1telemetry:
2  exporters:
3    metrics:
4      common:
5        service_name: apollo-router
6        views:
7          - name: apollo_router_http_request_duration_seconds # Instrument name you want to edit. You can use wildcard in names. If you want to target all instruments just use '*'
8            unit: "ms" # (Optional) override the unit
9            description: "my new description of this metric" # (Optional) override the description
10            aggregation: # (Optional)
11              histogram:
12                buckets: # Override default buckets configured for this histogram
13                - 1
14                - 2
15                - 3
16                - 4
17                - 5
18            allowed_attribute_keys: # (Optional) Keep only listed attributes on the metric
19            - status
20

You can drop specific metrics if you don't want these metrics to be sent to your APM.

YAML

router.yaml

1telemetry:
2  exporters:
3    metrics:
4      common:
5        service_name: apollo-router
6        views:
7          - name: apollo_router_http_request_duration_seconds # Instrument name you want to edit. You can use wildcard in names. If you want to target all instruments just use '*'
8            aggregation: drop
9

Metrics common reference

Attribute	Default	Description
`service_name`	`unknown_service:router`	The OpenTelemetry service name.
`service_namespace`		The OpenTelemetry namespace.
`resource`		The OpenTelemetry resource to attach to metrics.
`attributes`		Customization for the apollo_router_http_requests instrument.
`views`		Override default buckets or configuration for metrics (including dropping the metric itself)

Log Exporters