Docs
Launch GraphOS Studio

API Reference: Schema reporting plugin


Note: The schema reporting plugin does not support graphs that use Apollo Federation. If you are using Federation, or if you want to publish your monolith schema in your CI/CD pipeline, you can use the Rover CLI to publish your schema or subgraph changes.

Using the plugin

This article the options for the ApolloServerPluginSchemaReporting plugin, which you can import from @apollo/server/plugin/schemaReporting.

This plugin enables your to register its latest schema with the Apollo schema registry every time it starts up. Full details on schema reporting can be found in the Apollo Studio docs.

In order to use this plugin, you must configure your server with a API key, either with the APOLLO_KEY environment variable or by passing it directly to your ApolloServer constructor (e.g., new ApolloServer({apollo: {key: KEY}})). This is the same way you configure usage reporting.

You must explicitly enable schema reporting. If you want to turn on schema reporting with its default configuration, you can set the APOLLO_SCHEMA_REPORTING environment variable to true.

If you want to configure schema reporting (or prefer your setup to be via code rather than using environment variables), import the ApolloServerPluginSchemaReporting plugin and pass it to the ApolloServer constructor:

import { ApolloServer } from '@apollo/server';
import { ApolloServerPluginSchemaReporting } from '@apollo/server/plugin/schemaReporting';
const server = new ApolloServer({
typeDefs,
resolvers,
plugins: [ApolloServerPluginSchemaReporting()],
});
import { ApolloServer } from '@apollo/server';
import { ApolloServerPluginSchemaReporting } from '@apollo/server/plugin/schemaReporting';
const server = new ApolloServer({
typeDefs,
resolvers,
plugins: [ApolloServerPluginSchemaReporting()],
});

Using the plugin with multiple deployment instances

A single instance of running the plugin reports the current schema hash to in a heartbeat fashion. This hash is an identifier of the schema version and doesn't incorporate any usage data. GraphOS only reflects a new schema version in the changelog once all Apollo Server instances—whether one or more—are reporting the same schema hash.

Options

Name /
Type
Description
initialDelayMaxMs

number

The schema reporter waits before starting reporting. By default, the report waits some random amount of time between 0 and 10 seconds. A longer interval leads to more staggered starts which means it is less likely multiple servers will get asked to upload the same schema.

If this server runs in lambda or in other constrained environments it would be useful to decrease the schema reporting max wait time to be less than default.

This number will be the max for the range in ms that the schema reporter will wait before starting to report.

overrideReportedSchema

string

Override the reported schema that is reported to the Apollo registry. This schema does not go through any and the string is directly sent to the Apollo registry. This can be useful for comments or other ordering and whitespace changes that get stripped when generating a GraphQLSchema.

If you pass this option to this plugin, you should explicitly configure ApolloServerPluginUsageReporting and pass the same value to its overrideReportedSchema option. This ensures that the schema ID associated with requests reported by the usage reporting plugin matches the schema ID that this plugin reports. For example:

new ApolloServer({
plugins: [
ApolloServerPluginSchemaReporting({
overrideReportedSchema: schema
}),
ApolloServerPluginUsageReporting({
overrideReportedSchema: schema
}),
],
// ...
})
endpointUrl

string

The URL to use for reporting schemas. Primarily for testing and internal Apollo use.

fetcher

typeof fetch

Specifies which Fetch API function implementation to use when reporting schemas.

Disabling the plugin

The schema reporting plugin is only automatically installed if the APOLLO_SCHEMA_REPORTING is set to true, so the easiest way to disable the plugin is to avoid setting that environment variable (and to not explicitly install ApolloServerPluginSchemaReporting). However, if you'd like to ensure that the schema reporting plugin is not installed in your server (perhaps for a test that might run with arbitrary environment variables set), you can disable schema reporting by installing the ApolloServerPluginSchemaReportingDisabled plugin, like so:

import { ApolloServer } from '@apollo/server';
import { ApolloServerPluginSchemaReportingDisabled } from '@apollo/server/plugin/disabled';
const server = new ApolloServer({
typeDefs,
resolvers,
plugins: [ApolloServerPluginSchemaReportingDisabled()],
});
import { ApolloServer } from '@apollo/server';
import { ApolloServerPluginSchemaReportingDisabled } from '@apollo/server/plugin/disabled';
const server = new ApolloServer({
typeDefs,
resolvers,
plugins: [ApolloServerPluginSchemaReportingDisabled()],
});
Previous
Usage reporting
Next
Inline trace
Edit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc.

Privacy Policy

Company