Collecting metrics in the Apollo Router

The Apollo Router provides built-in support for metrics collection via Prometheus and OpenTelemetry Collector.

Using Prometheus

You can use Prometheus and Grafana to collect metrics and visualize the router metrics.

router.yaml

1
telemetry:
2
  metrics:
3
    prometheus:
4
      # By setting this endpoint you enable the prometheus exporter
5
      # All our endpoints exposed by plugins are namespaced by the name of the plugin
6
      # Then to access to this prometheus endpoint, the full url path will be `/plugins/apollo.telemetry/prometheus`
7
      enabled: true

Assuming you are running locally:

Run a query against the router.
Navigate to http://localhost:4000/plugins/apollo.telemetry/prometheus to see something like:

1
# HELP http_request_duration_seconds Total number of HTTP requests made.
2
# TYPE http_request_duration_seconds histogram
3
http_request_duration_seconds_bucket{le="0.5"} 1
4
http_request_duration_seconds_bucket{le="0.9"} 1
5
---SNIP---

Note that if you have not run a query against the router you will see a blank page as no metrics will have been generated yet!

Here is the list of available metrics you'll have using Prometheus:

HTTP router request duration (http_request_duration_seconds_bucket)
HTTP request duration by subgraph (http_request_duration_seconds_bucket with attribute subgraph)
Total number of HTTP requests by HTTP Status (http_requests_total)
Total number of HTTP requests in error (http_requests_error_total)

Using OpenTelemetry Collector

You may send metrics to OpenTelemetry Collector for processing and reporting metrics.

router.yaml

1
telemetry:
2
  metrics:
3
    otlp:
4
      # Either 'default' or a URL
5
      endpoint: default
6

7
      # Optional protocol. Only grpc is supported currently.
8
      # Setting to http will result in configuration failure.
9
      protocol: grpc
10

11
      # Optional Grpc configuration
12
      grpc:
13
        domain_name: "my.domain"
14
        key:
15
          file: ""
16
          # env: ""
17
        ca:
18
          file: ""
19
          # env: ""
20
        cert:
21
          file: ""
22
          # env: ""
23
        metadata:
24
          foo: bar
25

26
      # Optional timeout in humatime form
27
      timeout: 2s

If you need to add attributes/labels on your generated metrics, for example add a custom attributes/labels coming from a specific header in the original HTTP router request, or insert custom attributes/labels on every metrics. You also have access to the body of subgraph/router request/response. And be able to add a custom attribute coming from the context filled in the plugins chain.

router.yaml

1
telemetry:
2
  metrics:
3
    common:
4
      attributes:
5
        router:
6
          static:
7
            - name: "version"
8
              value: "v1.0.0"
9
          request:
10
            header:
11
              - named: "content-type"
12
                rename: "payload_type"
13
                default: "application/json"
14
              - named: "x-custom-header-to-add"
15
          response:
16
            body:
17
              # Take element from the response body of the router located at this path
18
              - path: .errors[0].extensions.status
19
                name: error_from_body
20
          context:
21
            # Take element from context in plugin chains and add it in attributes
22
            - named: my_key
23
        subgraph:
24
          all:
25
            static:
26
              # Always insert on all metrics for all subgraphs
27
              - name: kind
28
                value: subgraph_request
29
          subgraphs:
30
            my_subgraph_name: # Apply these rules only for the subgraph named `my_subgraph_name`
31
              request:
32
                header:
33
                  - named: "x-custom-header"
34
                body:
35
                  # Take element from the request body of the router located at this path (here it's the query)
36
                  - path: .query
37
                    name: query
38
                    default: UNKNOWN

Example of JSON Query to extract data from the body

If you have this data:

1
{
2
  "items": [
3
    {
4
      "unwanted": 7,
5
      "wanted": { "x": 3, "y": 7 },
6
      "array": [3, 2, 1]
7
    },
8
    {
9
      "whatever": true
10
    }
11
  ]
12
}

And want to fetch the field whatever here is the syntax .items[1].whatever. You can also try to fetch the field x by using this query .items[0].wanted.x. A JSON Query is always starting with a dot.

Edit on GitHub

Apollo Studio reporting

Tracing

Collecting metrics in the Apollo Router

Using Prometheus

Using OpenTelemetry Collector

Add custom attributes/labels

Example of JSON Query to extract data from the body