Join us from October 8-10 in New York City to learn the latest tips, trends, and news about GraphQL federation and API platform engineering.Join us for GraphQL Summit 2024 in NYC
Docs
Start for Free
Apollo Server 3 is officially deprecated, with end-of-life scheduled for 22 October 2024. Learn more about upgrading to a supported Apollo Server version.

API Reference: Inline trace plugin


Using the plugin

This API reference documents the ApolloServerPluginInlineTrace plugin.

This plugin enables your to include encoded performance and usage traces inside responses. This is primarily designed for use with Apollo Federation. Federated use this plugin and include a trace in the ftv1 response extension if requested to do so by the Apollo gateway. The gateway requests this trace by passing the HTTP header apollo-federation-include-trace: ftv1.

installs this plugin by default in all federated subgraphs, with its default configuration. (Apollo Server decides that it is a federated subgraph if the schema it is serving includes a _Service.sdl: String.) You typically do not have to install this plugin yourself; you only need to do so if you want to provide non-default configuration.

If you want to configure this plugin (or if you want to use it in a that is not a federated ), import it from the apollo-server-core package and pass it to your ApolloServer in the plugins array:

import { ApolloServer } from "apollo-server";
import {
ApolloServerPluginInlineTrace,
ApolloServerPluginLandingPageLocalDefault,
} from "apollo-server-core";
const server = new ApolloServer({
typeDefs,
resolvers,
csrfPrevention: true,
cache: "bounded",
plugins: [
ApolloServerPluginInlineTrace({
rewriteError: (err) => err.message.match(SENSITIVE_REGEX) ? null : err,
}),
ApolloServerPluginLandingPageLocalDefault({ embed: true }),
],
});

If you don't want to use the inline trace plugin even though your schema defines _Service.sdl: String, you can explicitly disable it with the ApolloServerPluginInlineTraceDisabled plugin:

import { ApolloServer } from "apollo-server";
import {
ApolloServerPluginInlineTraceDisabled,
ApolloServerPluginLandingPageLocalDefault,
} from "apollo-server-core";
const server = new ApolloServer({
typeDefs,
resolvers,
csrfPrevention: true,
cache: "bounded",
plugins: [
ApolloServerPluginInlineTraceDisabled(),
ApolloServerPluginLandingPageLocalDefault({ embed: true }),
],
});

Note that when this plugin is installed in your app, any client can request a trace for any they run, which may reveal information about your server that you consider sensitive (such as how long each individual field takes to execute). Federated subgraphs generally should not be directly exposed to the public Internet.

(Note: in addition to this plugin (which adds a base64-encoded trace to the ftv1 extension of responses), the Apollo platform used to have support for an older JSON-based format which added a tracing extension to responses. This support was enabled in Apollo Server 2 by passing tracing: true to the ApolloServer constructor; that option has been removed from Apollo Server 3. That format was designed for use with a no longer supported tool called engineproxy, and also is recognized by -playground. That format was more verbose due to its use of JSON and the way that it represented trace node IDs.)

When using Federation, you typically run this plugin in subgraphs and you run the usage reporting plugin in gateways; this is how the default behavior works. If you include this plugin in a gateway, then the gateway will include a full trace including the and all subgraph traces inline in its responses. This is not recommended for publicly exposed servers, but can be helpful when developing locally if you want to see the exact query plan generated by your gateway.

Options

Name /
Type
Description
rewriteError

Function

By default, all errors from this service get included in the trace. You can specify a filter function to exclude specific errors from being reported by returning an explicit null, or you can mask certain details of the error by modifying it and returning the modified error. This function has type (GraphQLError) => GraphQLError | null.

Previous
Schema reporting
Next
Drain HTTP server
Rate articleRateEdit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc.

Privacy Policy

Company