Debugging Subgraph Requests from the GraphOS Router or @apollo/gateway

As your graph grows, you may need to debug a problematic query for one reason or another. The Apollo Router (Apollo GraphOS Router or Apollo Router Core) and @apollo/gateway both serve as an entry point into your federated graph and offer ways to debug requests.

Each client request goes through a process called query planning that generates the subgraph requests to execute. You can log out the query plan in both the router and gateway.

Output query plans with headers

With the Apollo GraphOS Router or Apollo Router Core v1.61.0+ or v2.x+, you can pass the following header to return the query plans in the GraphQL response extensions:

• The header Apollo-Expose-Query-Plan must be set with one of the following options:

  • A value of true returns a human-readable string and JSON blob of the query plan

  • A value of dry-run will generate the query plan and then abort execution. This can be helpful if you want to warm up any internal or external query plan caches

Legacy header options

In older versions of the router v0.16.0+ and @apollo/gateway v2.5.4+, you can pass the following headers to return the query plans in the GraphQL response extensions:

• Including the Apollo-Query-Plan-Experimental header returns the query plan in the response extensions

• Additionally including the Apollo-Query-Plan-Experimental-Format header with one of the supported options changes the output format:

  • A value of prettified returns a human-readable string of the query plan

  • A value of internal returns a JSON representation of the query plan

Log router subgraph calls

If, instead, you want to debug your subgraph HTTP requests in a router instance, you can use Rhai scripts to log the necessary information out. An example Rhai script is shown below.

1fn subgraph_service(service, subgraph) {
2  service.map_request(|request| {
3      log_info(`Subgraph: ${subgraph} Query: ${request.subgraph.body.query}`);
4  });
5}

The above uses an inline closure within the map_request function of the subgraph_service hook to log the subgraph-related information.

To enable query plans, you must run the router with the --dev flag and leverage Apollo Sandbox to display your query plans.

As an alternative to using --dev, you can also enable query plans via the below configuration option, however, Apollo strongly discourages this as the feature may be removed or renamed in the future.

1plugins:
2  experimental.expose_query_plan: true

Log @apollo/gateway subgraph calls

To debug queries to your subgraphs within an @apollo/gateway instance, you can use a buildService function to log the operation name and body.

1class DebugDataSource extends RemoteGraphQLDataSource {
2  willSendRequest({
3    request
4  }: GraphQLDataSourceProcessOptions<
5    Record<string, any>
6  >): void | Promise<void> {
7    console.log(`Operation name: ${request.operationName}`);
8    console.log(`Query body: ${request.query}`);
9  }
10}
11const gateway = new ApolloGateway({
12  debug: true,
13  supergraphSdl,
14  buildService({url}) {
15    return new DebugDataSource({url});
16  }
17});

The above snippet creates a new class called DebugDataSource to log out the operation name and body using the willSendRequest hook, which is called before execution.

Lastly, it also enables the debug setting on the gateway configuration to print out query plans in the logs for further debugging if needed.