API Reference: Inline trace plugin
Using the plugin
This API reference documents the ApolloServerPluginInlineTrace
plugin.
This plugin enables your GraphQL server to include encoded performance and usage traces inside responses. This is primarily designed for use with Apollo Federation. Federated subgraphs use this plugin and include a trace in the ftv1
GraphQL 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
.
Apollo Server 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 field _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 graph that is not a federated subgraph), import it from the apollo-server-core
package and pass it to your ApolloServer
in the plugins
array:
1import { ApolloServer } from "apollo-server";
2import { ApolloServerPluginInlineTrace } from "apollo-server-core";
3
4const server = new ApolloServer({
5 typeDefs,
6 resolvers,
7 plugins: [
8 ApolloServerPluginInlineTrace({
9 rewriteError: (err) => err.message.match(SENSTIVE_REGEX) ? null : err,
10 }),
11 ],
12});
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:
1import { ApolloServer } from "apollo-server";
2import { ApolloServerPluginInlineTraceDisabled } from "apollo-server-core";
3
4const server = new ApolloServer({
5 typeDefs,
6 resolvers,
7 plugins: [ApolloServerPluginInlineTraceDisabled()],
8});
Note that when this plugin is installed in your app, any client can request a trace for any operation 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), Apollo Server also contains support for an older JSON-based format which is enabled if you pass tracing: true
to the ApolloServer
constructor. This format was designed for use with a no longer supported tool called engineproxy
, and also is recognized by graphql-playground. This format was more verbose due to its use of JSON and the way that it represented trace node IDs. Enabling it is not recommended.)
This plugin was introduced in Apollo Server 2.18. In previous versions, inline tracing was configured using the engine
option to the ApolloServer
constructor. That option continues to work; see the migration guide for details.
Options
Name / Type |
Description |
---|---|
|
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 |