Docs
Launch GraphOS Studio

GraphOS reporting

Send Apollo Router operation metrics to GraphOS


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

Enabling usage reporting

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

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

For more information, see Sending operation metrics to GraphOS.

Reporting field-level traces

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

Viewing a trace in GraphOS Studio

Your 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 with @apollo/subgraph, federated tracing support is enabled automatically.

Trace sampling rate

By default, the requests trace data for 1% of . 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 's trace sampling rate by setting the following options in your YAML config file:

router.yaml
telemetry:
apollo:
# In this example, the router will request traces for 50% of requests.
# This value can't exceed the value of tracing.common.sampler.
field_level_instrumentation_sampler: 0.5
exporters:
tracing:
common:
# FTV1 uses the same trace sampling as other tracing options,
# so this value is also required.
sampler: 0.5

NOTE

Because -level instrumentation is dependent on general-purpose OpenTelemetry tracing, the value of telemetry.apollo.field_level_instrumentation_sampler cannot exceed the value of telemetry.exporters.tracing.common.sampler.

Disabling field-level traces

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

router.yaml
telemetry:
apollo:
field_level_instrumentation_sampler: always_off

Advanced configuration

send_headers

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

router.yaml
telemetry:
apollo:
field_level_instrumentation_sampler: 0.01 # (default)
send_headers:
only: # Include only headers with these names
- referer

Supported values:

Value / TypeDescription
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 .

only

array

An array of names for the headers that the will report to . All other headers are not reported. See the example above.

except

array

An array of names for the headers that the will not report to . All other headers are. Uses the same format as the only example above.

send_variable_values

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

router.yaml
telemetry:
apollo:
field_level_instrumentation_sampler: 0.01 # (default)
send_variable_values:
except: # Send all variables EXCEPT ones with these names
- first

Supported values:

Value / TypeDescription
none

string

Set send_variable_values to the string value none to include no 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 information in reported traces.

send_variable_values: all

⚠️ Use with caution! might contain sensitive data that should not be reported to .

only

array

An array of names for the that the will report to . All other are not reported. Uses the same format as the except example above.

except

array

An array of names for the that the will not report to . All other are reported. See the example above.

router.yaml
telemetry:
apollo:
# The percentage of requests will include HTTP request and response headers in traces sent to Apollo Studio.
# This is expensive and should be left at a low value.
# This cannot be higher than tracing->common->sampler
field_level_instrumentation_sampler: 0.01 # (default)
# Include HTTP request and response headers in traces sent to Apollo Studio
send_headers: # other possible values are all, only (with an array), except (with an array), none (by default)
except: # Send all headers except referer
- referer
# Include variable values in Apollo in traces sent to Apollo Studio
send_variable_values: # other possible values are all, only (with an array), except (with an array), none (by default)
except: # Send all variable values except for variable named first
- first
exporters:
tracing:
common:
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 reports error information to , and whether the details of those errors are redacted. You can customize this behavior globally and override that global behavior on a per- basis.

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

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

Your libraries must support federated tracing (also known as FTV1 tracing) to provide errors to . If you use 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.
  • Note that federated tracing can also be sampled (see above) so error messages might not be available for all your if you have sampled to a lower level.

See the example below:

router.yaml
telemetry:
apollo:
errors:
subgraph:
all:
# By default, subgraphs should report errors to GraphOS
send: true # (default: true)
redact: false # (default: true)
subgraphs:
account: # Override the default behavior for the "account" subgraph
send: false
Previous
Overview
Next
Client awareness
Edit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc.

Privacy Policy

Company