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
engineoption to theApolloServerconstructor. 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
sendVariableValues
Object
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 sendVariableValues object signatures.
The default value is { none: true }, which means no variable values are sent to Studio. This is a security measure to prevent sensitive data from potentially reaching Apollo servers.
sendHeaders
Object
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 sendHeaders object signatures.
The default value is { none: true }, which means no header names or values are sent to Studio. This is a security measure to prevent sensitive data from potentially reaching Apollo servers.
rewriteError
Function
Specify this function to modify GraphQL operation errors before Apollo Server reports those errors to Apollo Studio. The function takes a GraphQLError object and must also return one (or null to prevent Apollo Server from reporting a particular error entirely).
The only properties of the reported error you can modify are its message and its extensions.
Note: If this ApolloServer instance is acting as the gateway in an Apollo Federation architecture, this option does not modify errors that originate in subgraphs. To modify those errors, instead configure the rewriteError option in the inline trace plugin, which you install in the subgraph's ApolloServer instance.
includeRequest
async Function
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 GraphQLRequestContext object and must return a Promise<Boolean> that indicates whether to include the request. It's called either after the operation is successfully resolved (via the didResolveOperation event), or after it generates an error (via the didEncounterErrors event).
By default, all requests are included in usage reports.
generateClientInfo
Function
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 GraphQLRequestContext object containing all available information about the request. It should return an object with clientName and clientVersion fields that identify the associated client.
By default, the plugin attempts to obtain these values from the incoming request's HTTP headers (specifically, apollographql-client-name and apollographql-client-version).
overrideReportedSchema
string
If you're using the overrideReportedSchema option with the schema reporting plugin (ApolloServerPluginSchemaReporting), you should provide the same value for this option. This ensures that the schema ID associated with a request in this plugin's usage reports matches the schema ID that the other plugin reports.
sendUnexecutableOperationDocuments
Boolean
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
sendReportsImmediately
boolean
If true, the plugin sends a usage report to Apollo Studio after every request instead of sending batched reports.
This option is useful for stateless environments like Amazon Lambda where processes terminate after handling a small number of requests.
The default value is true when using an ApolloServer subclass for a serverless framework (Amazon Lambda, Google Cloud Functions, or Azure Functions) and false otherwise.
Note that "immediately" does not mean synchronously with completing the response, but rather "very soon", such as after a setImmediate call.
requestAgent
http.Agent or https.Agent or false
An HTTP(S) agent to use for reporting. Can be either an http.Agent or an https.Agent. It behaves the same as the agent parameter to http.request.
fetcher
typeof fetch
Specifies which Fetch API function implementation to use when sending usage reports.
reportIntervalMs
number
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 maxUncompressedReportSize (default 4MB).
maxUncompressedReportSize
number
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 (4194304).
maxAttempts
number
The maximum number of times Apollo Server should attempt to report each trace report, performing exponential backoff between attempts.
The default value is 5.
minimumRetryDelayMs
number
The minimum amount of backoff (in milliseconds) Apollo Server should perform before retrying a failed trace report.
The default value is 100.
logger
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 Logger interface.
reportErrorFunction
Function
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 logger. Unlike the logger, this function receives the actual Error object instead of only an error message.
Internal and non-recommended options
endpointUrl
string
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.
debugPrintReports
boolean
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.)
calculateSignature
Function
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:
authorizationcookieset-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});