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
Resource attributes
Custom default histogram buckets
apollo_router_http_requests attributes
OpenTelemetry views

`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 setting service name in telemetry.exporters.metrics.common.service_name:
router.yaml
telemetry:
exporters:
metrics:
common:
# (Optional) Set the service name to easily find metrics related to the apollo-router in your metrics dashboards
service_name: "router"

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

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

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:

router.yaml

1
telemetry:
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:

router.yaml

1
telemetry:
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:

router.yaml

1
telemetry:
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.

router.yaml

1
telemetry:
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

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

router.yaml

1
telemetry:
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

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)

Stdout

Datadog