Launch GraphOS Studio
You're viewing documentation for a previous version of this software. Switch to the latest stable version.

Federated trace data

How federated tracing works

One of the many benefits of using as an API layer is that it enables fine-grained tracing of every API call. The Apollo platform supports consuming and aggregating these traces to provide detailed insights into your layer's performance and usage.

supports sending federated traces from your gateway, which are constructed from timing and error information provided by your . These federated traces capture the subgraph-level details in the shape of the , which is sent to Apollo's metrics ingress by default, and aggregated into -level stats and -level stats. The overall flow of a federated trace is as follows:

  1. The gateway receives an from a client.
  2. The gateway constructs a for the , delegating sub-queries to .
  3. For each fetch to a , a response is received.
  4. The extensions of each response includes a trace from the sub-.
  5. The gateway collects the set of sub- traces from and arranges them in the shape of the .
  6. The federated trace is sent to the Apollo metrics ingress for processing.

In summary, report timing and error information to the gateway, and the gateway is responsible for reporting those metrics to Apollo.

Enabling traces

Ensure that all dependencies on apollo-server are at version 2.7.0 or higher. 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. Currently, only supports detailed metrics insights as a subgraph, but we would love to work with you to implement the protocol in other languages!

Note: 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 is provided for additional technical context and is not required reading to enable federated tracing.

Your gateway 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. In order to request this information of , the gateway will send the header pair 'apollo-federation-include-trace': 'ftv1' on fetches if configured to collect metrics, as per above. By default, a federated will recognize this header pair and attach tracing information in of the response.

How traces are constructed and aggregated

The Apollo gateway constructs traces in the shape of the , 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 the Apollo Platform aggregates from these traces are collected over the fields over which the was executed in the federated subgraphs.

In other words, stats are collected based on the 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 ning changes, statistics still corresponded to the same client-delivered .

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 rewriteError 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 gateway level. will 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 will only report 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.

Error codes
Edit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc.

Privacy Policy