API Reference: Usage reporting plugin
Apollo Server has a built-in usage reporting plugin that gathers data on how your clients use the operations and fields in your GraphQL schema. The plugin also handles pushing this usage data to Apollo Studio, as described in Metrics and logging.
This plugin was introduced in Apollo Server 2.18. In previous versions, usage reporting is configured by providing the
engine
option to theApolloServer
constructor. That option continues to work (but is now deprecated). See the migration guide for details.
Default installation
Apollo Server automatically installs and enables this plugin with default settings if you provide a graph API key to Apollo Server (usually by setting the value of the APOLLO_KEY
environment variable). No other action is required.
If you don't provide an API key, this plugin is not installed.
Custom installation
You can configure the usage reporting plugin's behavior by including it in the plugins
array you pass to the ApolloServer
constructor:
1import { ApolloServer } from "apollo-server";
2import { ApolloServerPluginUsageReporting } from "apollo-server-core";
3
4const server = new ApolloServer({
5 typeDefs,
6 resolvers,
7 plugins: [
8 ApolloServerPluginUsageReporting({
9 sendVariableValues: { all: true },
10 }),
11 ],
12});
Supported configuration options are listed below.
Options
Name / Type |
Description |
---|---|
Configuring which data is sent to Apollo Studio |
|
|
Provide this object to configure which GraphQL variable values are included in trace data that's sent to Apollo Studio. Valid options are described in Valid The default value is |
|
Provide this object to configure which request header names and values are included in trace data that's sent to Apollo Studio. Valid options are described in Valid The default value is |
|
Specify this function to modify GraphQL operation errors before Apollo Server reports those errors to Apollo Studio. The function takes a The only properties of the reported error you can modify are its Note: If this |
|
Specify this asynchronous function to configure which requests are included in usage reports sent to Apollo Studio. For example, you can omit requests that execute a particular operation or requests that include a particular HTTP header. This function is called for each received request. It takes a By default, all requests are included in usage reports. |
|
Specify this function to provide Apollo Studio with client details for each processed request. Apollo Studio uses this information to segment metrics by client. This function is passed a By default, the plugin attempts to obtain these values from the incoming request's HTTP headers (specifically, |
|
If you're using the |
|
Statistics about operations that your server cannot execute are not reported under each document separately to Apollo Studio, but are grouped together as "parse failure", "validation failure", or "unknown operation name". By default, the usage reporting plugin does not include the full operation document in reported traces, because it is challenging to strip potential private information (like string constants) from invalid operations. If you'd like the usage reporting plugin to send the full operation document and operation name so you can view it in Apollo Studio's trace view, set this to true. |
Configuring communication protocol |
|
|
If This option is useful for stateless environments like Amazon Lambda where processes terminate after handling a small number of requests. The default value is Note that "immediately" does not mean synchronously with completing the response, but rather "very soon", such as after a |
|
An HTTP(S) agent to use for reporting. Can be either an |
|
Specifies which Fetch API function implementation to use when sending usage reports. |
|
The interval at which Apollo Server should send batched trace reports to Studio, in milliseconds. Regardless of this value, Apollo Server sends a trace report whenever the size of a pending batch exceeds the value of |
|
Apollo Server sends a trace report whenever the size of a pending batched trace report exceeds this value (in bytes), regardless of its standard reporting interval. Note that this is a rough limit that includes the size of serialized traces and signatures. It ignores the size of the report's header and some other top-level bytes. The default value is 4MB ( |
|
The maximum number of times Apollo Server should attempt to report each trace report, performing exponential backoff between attempts. The default value is |
|
The minimum amount of backoff (in milliseconds) Apollo Server should perform before retrying a failed trace report. The default value is |
|
If you provide this object, the plugin sends it all log messages related to Apollo Studio communication, instead of sending them to the default logger. The object must implement all methods of the |
|
If you provide this function, the plugin calls it whenever it encounters an error while reporting usage data. The details of the error are passed to the function. By default, the plugin logs these errors to its specified |
Internal and non-recommended options |
|
|
The URL base that the plugin sends reports to (not including the path). This option only needs to be set for testing and Apollo-internal uses. |
|
If set, prints all reports as JSON when they are sent. (Note that for technical reasons, traces embedded in a report are printed separately when they are added to a report.) |
|
Specify this function to create a signature for a query. This option is not recommended, because Apollo's servers make assumptions about how the signature relates to the operation you executed. |
Valid sendVariableValues
object signatures
Object | Description |
---|---|
{ none: true } | If you provide this object, no GraphQL variable values are sent to Apollo Studio. This is the default behavior. |
{ all: true } | If you provide this object, all GraphQL variable values are sent to Apollo Studio. |
{ onlyNames: ["apple", "orange"]} | If you provide an object with this structure, only values of the GraphQL variables with names that appear in the array are sent to Apollo Studio. Case-sensitive. |
{ exceptNames: ["apple", "orange"]} | If you provide an object with this structure, all GraphQL variable values except values of variables with names that appear in the array are sent to Apollo Studio. Case-sensitive. |
{ transform: ({ variables, operationString)} => { ... } } | The value of transform is a function that takes the values of all GraphQL variables for an operation and the operation string. The function returns a new variables map containing values for the operation's variables that should be sent to Apollo Studio. This map does not need to contain all of the operation's variables, but it cannot add variables to the map. You should not mutate variables itself or any of the values contained in it.For security reasons, if an error occurs in the transform function, all variable values are replaced with [PREDICATE_FUNCTION_ERROR] . |
Valid sendHeaders
object signatures
Object | Description |
---|---|
{ none: true } | If you provide this object, no request header names or values are sent to Apollo Studio. This is the default behavior. |
{ all: true } | If you provide this object, all GraphQL header names and values are sent to Apollo Studio, except for the protected headers listed above. |
{ onlyNames: ["apple", "orange"]} | If you provide an object with this structure, only names and values of the request headers with names that appear in the array are sent to Apollo Studio. Case-insensitive. |
{ exceptNames: ["apple", "orange"]} | If you provide an object with this structure, all GraphQL header values except values of headers with names that appear in the array are sent to Apollo Studio. Case-insensitive. |
Note: Regardless of your configuration, Apollo Server never sends the values of the following headers to Apollo Studio:
authorization
cookie
set-cookie
Disabling the plugin
If you don't want to install the usage reporting plugin and you are providing an API key to Apollo Server for other purposes, you can disable usage reporting by installing the ApolloServerPluginUsageReportingDisabled
plugin, like so:
1import { ApolloServer } from "apollo-server";
2import { ApolloServerPluginUsageReportingDisabled } from "apollo-server-core";
3
4const server = new ApolloServer({
5 typeDefs,
6 resolvers,
7 plugins: [ApolloServerPluginUsageReportingDisabled()],
8});