Sending Apollo Router operation metrics to GraphOS

The Apollo Router can report operation usage metrics to GraphOS that you can then visualize in GraphOS Studio. These metrics also enable powerful GraphOS features like schema checks.

Enabling usage reporting

You enable usage reporting in the Apollo Router by setting the following environment variables:

1
export APOLLO_KEY=<YOUR_GRAPH_API_KEY>
2
export APOLLO_GRAPH_REF=<YOUR_GRAPH_ID>@<VARIANT_NAME>

For more information, see Sending operation metrics to GraphOS.

In their responses to your router, your subgraphs can include field-level traces that indicate how long the subgraph took to resolve each field in an operation. By analyzing this data in GraphOS Studio, you can identify and optimize your slower fields:

Your subgraph libraries must support federated tracing (also known as FTV1 tracing) to provide this data.

To confirm support, check the FEDERATED TRACING entry for your library on this page.
Consult your library's documentation to learn how to enable federated tracing.
- If you use Apollo Server with @apollo/subgraph, federated tracing support is enabled automatically.

Trace sampling rate

By default, the Apollo Router requests subgraph trace data for 1% of operations. In most cases, this provides a sufficient sample size while minimizing latency for most operations (traces can affect latency because they increase the size of subgraph response payloads).

You can customize your router's trace sampling rate by setting the following options in your YAML config file:

router.yaml

1
telemetry:
2
  apollo:
3
    # In this example, the router will request traces for 50% of requests.
4
    # This value can't exceed the value of tracing.trace_config.sampler.
5
    field_level_instrumentation_sampler: 0.5
6

7
  tracing:
8
    trace_config:
9
      # FTV1 uses the same trace sampling as other tracing options,
10
      # so this value is also required.
11
      sampler: 0.5

Note: Because field-level instrumentation is dependent on general-purpose OpenTelemetry tracing, the value of apollo.field_level_instrumentation_sampler cannot exceed the value of tracing.trace_config.sampler.

Disabling field-level traces

To completely disable requesting and reporting subgraph trace data, set field_level_instrumentation_sampler to always_off:

router.yaml

1
telemetry:
2
  apollo:
3
    field_level_instrumentation_sampler: always_off

Advanced configuration

`send_headers`

Provide this field to configure which request header names and values are included in trace data that's sent to GraphOS. By default, no header information is sent to GraphOS as a security measure.

router.yaml

1
telemetry:
2
  apollo:
3
    field_level_instrumentation_sampler: 0.01 # (default)
4
    send_headers:
5
      only: # Include only headers with these names
6
        - referer

Supported values:

Value / Type	Description
`none` `string`	Set `send_headers` to the string value `none` to include no header information in reported traces. send_headers: none This is the default behavior.
`all` `string`	Set `send_headers` to the string value `all` to include all header information in reported traces. send_headers: all ⚠️ Use with caution! Headers might contain sensitive data (such as access tokens) that should not be reported to GraphOS.
`only` `array`	An array of names for the headers that the router will report to GraphOS. All other headers are not reported. See the example above.
`except` `array`	An array of names for the headers that the router will not report to GraphOS. All other headers are. Uses the same format as the `only` example above.

`send_variable_values`

Provide this field to configure which GraphQL variable values are included in trace data that's sent to GraphOS. By default, no variable information is sent to GraphOS as a security measure.

router.yaml

1
telemetry:
2
  apollo:
3
    field_level_instrumentation_sampler: 0.01 # (default)
4
    send_variable_values:
5
      except: # Send all variables EXCEPT ones with these names
6
        - first

Supported values:

Value / Type	Description
`none` `string`	Set `send_variable_values` to the string value `none` to include no variable information in reported traces. send_variable_values: none This is the default behavior.
`all` `string`	Set `send_variable_values` to the string value `all` to include all variable information in reported traces. send_variable_values: all ⚠️ Use with caution! GraphQL variables might contain sensitive data that should not be reported to GraphOS.
`only` `array`	An array of names for the variables that the router will report to GraphOS. All other variables are not reported. Uses the same format as the `except` example above.
`except` `array`	An array of names for the variables that the router will not report to GraphOS. All other variables are reported. See the example above.

router.yaml

1
telemetry:
2
  apollo:
3
    # The percentage of requests will include HTTP request and response headers in traces sent to Apollo Studio.
4
    # This is expensive and should be left at a low value.
5
    # This cannot be higher than tracing->trace_config->sampler
6
    field_level_instrumentation_sampler: 0.01 # (default)
7

8
    # Include HTTP request and response headers in traces sent to Apollo Studio
9
    send_headers: # other possible values are all, only (with an array), except (with an array), none (by default)
10
      except: # Send all headers except referer
11
        - referer
12

13
    # Include variable values in Apollo in traces sent to Apollo Studio
14
    send_variable_values: # other possible values are all, only (with an array), except (with an array), none (by default)
15
      except: # Send all variable values except for variable named first
16
        - first
17
  tracing:
18
    trace_config:
19
      sampler: 0.5 # The percentage of requests that will generate traces (a rate or `always_on` or `always_off`)

`errors`

You can configure whether the Apollo Router reports GraphQL error information to GraphOS, and whether the details of those errors are redacted. You can customize this behavior globally and override that global behavior on a per-subgraph basis.

By default, your router does report error information, and it does redact the details of those errors.

To prevent your router from reporting error information at all, you can set the send option to false.
To include all error details in your router's reports to GraphOS, you can set the redact option to false.

Note: Your subgraph libraries must support federated tracing (also known as FTV1 tracing) to provide errors to GraphOS. If you use Apollo Server with @apollo/subgraph, federated tracing support is enabled automatically.

To confirm support:

Check the FEDERATED TRACING entry for your library on the supported subgraphs page.
If federated tracing isn't enabled automatically for your library, consult its documentation to learn how to enable it.

See the example below:

router.yaml

1
telemetry:
2
  apollo:
3
    errors:
4
      subgraph:
5
        all:
6
          # By default, subgraphs should report errors to GraphOS
7
          send: true # (default: true)
8
          redact: false # (default: true)
9
        subgraphs:
10
          account: # Override the default behavior for the "account" subgraph
11
            send: false

Client protocol: HTTP multipart

OpenTelemetry tracing

Sending Apollo Router operation metrics to GraphOS

Enabling usage reporting

Reporting field-level traces

Trace sampling rate

Disabling field-level traces

Advanced configuration

`send_headers`

`none`

`all`

`only`

`except`

`send_variable_values`

`none`

`all`

`only`

`except`

`errors`