Docs
Launch GraphOS Studio

Federated trace data

Reporting fine-grained performance metrics


One of the many benefits of using as an API layer is that it enables fine-grained, -level tracing of every executed . The GraphOS platform can consume and aggregate these traces to provide detailed insights into your 's usage and performance.

Your 's can generate federated traces and report them to GraphOS. A federated trace is assembled from timing and error information provided by each that helps resolve a particular .

Reporting flow

The overall flow of a federated trace is as follows:

  1. The receives an from a client.
  2. The generates a query plan for the and delegates sub-queries to individual .
  3. Each queried returns response data to the .
  4. The collects the set of sub- traces from and arranges them in the shape of the .
  5. The reports the federated trace to GraphOS for processing.

In summary, report timing and error information to the , and the router is responsible for aggregating those metrics and reporting them to .

Enabling federated tracing

In your subgraphs

For a to include trace data in its responses to your , it must use a subgraph-compatible library that supports the trace format.

To check whether your library supports federated tracing, see the FEDERATED TRACING entry for the library on this page.

If your library does support federated tracing, see its documentation to learn how to enable the feature.

If your uses with @apollo/subgraph, federated tracing is enabled by default. You can customize this behavior with 's inline trace plugin.

In the Apollo Router

See Sending Apollo Router usage data to GraphOS.

In @apollo/gateway

You can use the @apollo/server package's built-in usage reporting plugin to enable federated tracing for your gateway. Provide an API key to your gateway via the APOLLO_KEY environment variable for the gateway to report metrics to the default ingress. To ensure that do not report metrics as well, either do not provide them with an APOLLO_KEY or install the ApolloServerPluginUsageReportingDisabled plugin in your ApolloServer.

These options will cause the Apollo gateway to collect tracing information from the underlying and pass them on, along with the , to the Apollo metrics ingress.

By default, metrics are reported to the current . To change the variant for reporting, set the APOLLO_GRAPH_VARIANT environment variable.

How tracing data is exposed from a subgraph

This section explains how your communicates with around encoded tracing information. It is not necessary to understand in order to enable federated tracing.

Your inspects the extensions of all responses for the presence of an ftv1 . This field contains a representation of the tracing information for the sub- that was executed against the , sent as the Base64 encoding of the protobuf representation of the trace.

To obtain this information from a , the includes the header pair 'apollo-federation-include-trace': 'ftv1' in its request (if it's configured to collect trace data). If the supports federated traces, it attaches tracing information in the extensions of its response.

How traces are constructed and aggregated

Your constructs traces in the shape of the query plan, embedding an individual Trace for each fetch that is performed in the . This indicates the sub-query traces, as well as which order they were fetched from the underlying .

The -level statistics that Apollo aggregates from these traces are collected for the fields over which the was executed in the . In other words, field stats are collected based on the operations the makes, instead of the operations that the clients make. On the other hand, operation-level statistics are aggregated over the operations executed by the client, which means that even if query-planning changes, statistics still correspond to the same client-delivered operation.

How errors work

The Apollo Platform provides functionality to modify error details for the client, via the formatError option. Additionally, there is functionality to support modifying error details for the metrics ingress, via the sendErrors option to the inline trace plugin.

When modifying errors for the client, you might want to use this option to hide implementation details, like database errors, from your users. When modifying errors for reporting, you might want to obfuscate or redact personal information, like user IDs or emails.

Since federated metrics collection works by collecting latency and error information from a set of distributed , these options are respected from those subgraphs as well as from the . Subgraphs embed errors in their ftv1 extension after the rewriteError method (passed to the inline trace plugin in the , not the usage reporting plugin in the gateway!) is applied, and the gateway only reports the errors that are sent via that extension, ignoring the format that downstream errors are reported to end users. This functionality enables subgraph implementers to determine how error information should be displayed to both users and in metrics without needing the gateway to contain any logic that might be subgraph-specific.

Previous
Composition hints
Next
OpenTelemetry
Edit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc.

Privacy Policy

Company