Join us for GraphQL Summit, October 10-12 in San Diego. Super Early Bird registration ends soon!
Try Apollo Studio

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.

# (Optional, default to "apollo-router") Set the service name to easily find metrics related to the apollo-router in your metrics dashboards
service_name: "apollo-router"
# (Optional)
service_namespace: "apollo"
# By setting this endpoint you enable the prometheus exporter
# All our endpoints exposed by plugins are namespaced by the name of the plugin
enabled: true
path: /metrics

Using in a containers environment

The prometheus endpoint listens to by default, which won't allow connections issued from a network. While this is a safe default, other containers won't be able to access the prometheus endpoint, which will disable metric scraping.

You can change this by setting:

# By setting this endpoint you enable other containers and pods to access the prometheus endpoint
enabled: true
path: /metrics

Assuming you're running locally:

  1. Run a query against the router.
  2. Navigate to http://localhost:9090/metrics to see something like:
# HELP apollo_router_http_request_duration_seconds Total number of HTTP requests made.
# TYPE apollo_router_http_request_duration_seconds histogram
apollo_router_http_request_duration_seconds_bucket{le="0.5"} 1
apollo_router_http_request_duration_seconds_bucket{le="0.9"} 1

Note that if you haven't run a query against the router yet, you'll see a blank page because no metrics have been generated!

Currently available metrics

The following metrics are available using Prometheus:

  • HTTP router request duration: apollo_router_http_request_duration_seconds_bucket
  • HTTP request duration by subgraph: apollo_router_http_request_duration_seconds_bucket with attribute subgraph
  • Total number of HTTP requests by HTTP Status: apollo_router_http_requests_total
  • Number of currently connected clients: apollo_router_session_count_total
  • Number of in flight GraphQL requests: apollo_router_session_count_active
  • Number of cache hits for different kind of cache (apq, query planner, introspection) and for different storage (memory, redis): apollo_router_cache_hit_count
  • Number of cache misses for different kind of cache (apq, query planner, introspection) and for different storage (memory, redis): apollo_router_cache_miss_count
  • Time to hit the cache for different kind of cache (apq, query planner, introspection) and for different storage (memory, redis), in seconds: apollo_router_cache_hit_time
  • Time to miss the cache for different kind of cache (apq, query planner, introspection) and for different storage (memory, redis), in seconds: apollo_router_cache_miss_time
  • Time spent processing a request, outside of waiting for external or subgraph requests, in seconds (apollo_router_processing_time)
  • Number of triggered timeouts: apollo_router_timeout

Using OpenTelemetry Collector

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

# Either 'default' or a URL
endpoint: default
# Optional protocol. Only grpc is supported currently.
# Setting to http will result in configuration failure.
protocol: grpc
# Optional Grpc configuration
domain_name: "my.domain"
key: ""
ca: ""
cert: ""
foo: bar
# Optional batch_processor configuration
scheduled_delay: 100ms
max_concurrent_exports: 1000
max_export_batch_size: 10000
max_export_timeout: 100s
max_queue_size: 10000

Remember that file. and env. prefixes can be used for expansion in config yaml. e.g. ${}.

Adding custom attributes/labels

You can add custom attributes (OpenTelemetry) and labels (Prometheus) to your generated metrics. You can apply these across all requests, or you can selectively apply them based on the details of a particular request. These details include:

  • The presence of a particular HTTP header
  • The value at a particular JSON path within a request or response body (either from a subgraph or from the router itself)
  • A custom value provided via the router plugin context

Examples of all of these are shown in the file below:

supergraph: # Attribute configuration for requests to/responses from the router
- name: "version"
value: "v1.0.0"
- named: "content-type"
rename: "payload_type"
default: "application/json"
- named: "x-custom-header-to-add"
# Apply the value of the provided path of the router's response body as an attribute
- path: .errors[0].extensions.status
name: error_from_body
# Apply the indicated element from the plugin chain's context as an attribute
- named: my_key
subgraph: # Attribute configuration for requests to/responses from subgraphs
# Always apply this attribute to all metrics for all subgraphs
- name: kind
value: subgraph_request
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)
include_messages: true # Will include the error message in a message attribute
extensions: # Include extensions data
- name: subgraph_error_extended_type # Name of the attribute
path: .type # JSON query path to fetch data from extensions
- name: message
path: .reason
# Will create this kind of metric for example apollo_router_http_requests_error_total{message="cannot contact the subgraph",service_name="apollo-router",subgraph="my_subgraph_name",subgraph_error_extended_type="SubrequestHttpError"}
my_subgraph_name: # Apply these rules only for the subgraph named `my_subgraph_name`
- named: "x-custom-header"
# Apply the value of the provided path of the router's request body as an attribute (here it's the query)
- path: .query
name: query
default: UNKNOWN

Example JSON path queries

Let's say you have a JSON request body with the following structure:

"items": [
"unwanted": 7,
"wanted": { "x": 3, "y": 7 },
"array": [3, 2, 1]
"isImportant": true

To fetch the value of the field isImportant, the corresponding path is .items[1].isImportant.

To fetch the value of the field x, the corresponding path is .items[0].wanted.x.

JSON path queries always begin with a period .

Adding custom resources

Resources are similar to attributes, but there are more globals. They're configured directly on the metrics exporter, which means they're always present on each of your metrics.

As an example, it can be useful to set a environment_name resource to help you identify metrics related to a particular environment:

environment_name: "production"

See OpenTelemetry conventions for resources.

For example, if you want to use a Datadog agent and specify a service name, you should set the resource as shown above and described in the conventions document.

Edit on GitHub
Apollo Studio reporting