Here's your chance to speak at GraphQL Summit in New York City, October 8 - 10, 2024! 🏙️ Submit your proposal by May 31.
Docs
Launch GraphOS Studio

Metrics exporters

Export Apollo Router metrics


The supports collection of metrics with OpenTelemetry, with exporters for:

In router.yaml, you configure 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):

  1. OTEL_SERVICE_NAME environment variable

  2. OTEL_RESOURCE_ATTRIBUTES environment variable

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

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

resource

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

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

router.yaml
telemetry:
exporters:
metrics:
common:
resource:
"environment.name": "production"
"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
telemetry:
exporters:
metrics:
common:
buckets:
- 0.05
- 0.10
- 0.25
- 0.50
- 1.00
- 2.50
- 5.00
- 10.00
- 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)

An example of configuring these attributes is shown below:

router.yaml
telemetry:
exporters:
metrics:
common:
attributes:
supergraph: # Attribute configuration for requests to/responses from the router
static:
- name: "version"
value: "v1.0.0"
request:
header:
- named: "content-type"
rename: "payload_type"
default: "application/json"
- named: "x-custom-header-to-add"
response:
body:
# Apply the value of the provided path of the router's response body as an attribute
- path: .errors[0].extensions.http.status
name: error_from_body
# Use the unique extension code to identify the kind of error
- path: .errors[0].extensions.code
name: error_code
context:
# 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
all:
static:
# 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",subgraph="my_subgraph_name",subgraph_error_extended_type="SubrequestHttpError"}
subgraphs:
my_subgraph_name: # Apply these rules only for the subgraph named `my_subgraph_name`
request:
header:
- named: "x-custom-header"
body:
# 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

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
telemetry:
exporters:
metrics:
common:
service_name: apollo-router
views:
- 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 '*'
unit: "ms" # (Optional) override the unit
description: "my new description of this metric" # (Optional) override the description
aggregation: # (Optional)
histogram:
buckets: # Override default buckets configured for this histogram
- 1
- 2
- 3
- 4
- 5
allowed_attribute_keys: # (Optional) Keep only listed attributes on the metric
- status

Metrics common reference

AttributeDefaultDescription
service_nameunknown_service:routerThe OpenTelemetry service name.
service_namespaceThe OpenTelemetry namespace.
resourceThe OpenTelemetry resource to attach to metrics.
attributesCustomization for the apollo_router_http_requests instrument.
Previous
Stdout
Next
Datadog
Edit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc.

Privacy Policy

Company