/
Launch Apollo Studio

Schema registration via schema reporting


Schema reporting enables your GraphQL server to register its latest schema with the Apollo schema registry every time it starts up. To use this feature, your server needs to support the schema reporting protocol. This protocol is supported by Apollo Server, and other GraphQL servers can implement support.

Schema reporting does not currently support graphs that use Apollo Federation. If you have a federated graph, instead see Registering federated schemas.

Apollo Server setup

Schema reporting is available in Apollo Server version 2.15 and later. To enable it:

  1. Obtain an API key for your data graph:

  2. Set this API key as the value of the APOLLO_KEY environment variable in your server's environment.

    If you're using the dotenv library, you can add the API key to the .env file in your project's root directory, like so:

    .env
    APOLLO_KEY=YOUR_KEY_HERE
  3. Set the engine.reportSchema option to true in your ApolloServer constructor, like so:

    const server = new ApolloServer({
      // ...other options...
      engine: {
        reportSchema: true
      }
    });

Now every time your server finishes starting up, it waits a random amount of time between zero and ten seconds before automatically registering its schema (you can customize this time range).

Registering to a variant with schema reporting

Your server can register its schema to a particular variant of your graph. Each of your server's environments (development, staging, production, etc.) should register to a different variant.

To do so with Apollo Server, set the APOLLO_GRAPH_VARIANT environment variable in each server environment:

.env
APOLLO_KEY=YOUR_KEY_HERE
APOLLO_GRAPH_VARIANT=staging

If you don't specify a variant, Apollo Server reports its schema to the default variant (named current).

The schema reporting protocol accepts optional values that help both you and Apollo associate each request with a particular server instance and platform. This in turn helps with diagnosing issues and improving performance.

To provide these values to Apollo Server, set the following environment variables in your server's environment:

NameDescription
APOLLO_SERVER_USER_VERSIONAn identifier for the current running version of your server, such as the SHA of its associated Git commit. We plan to display this value in Apollo Studio to help you segment metrics.
APOLLO_SERVER_IDAn ID that's unique for each running instance of your server. This value should persist across an instance's restarts. For example, in a Kubernetes cluster, you can use the server's pod name.
APOLLO_SERVER_PLATFORMThe infrastructure environment that your server is running in (localhost, kubernetes/deployment, aws lambda, google cloud run, google cloud function, AWS ECS, etc.)

Customizing schema reporting behavior in Apollo Server

In addition to engine.reportSchema, you can provide the following options to Apollo Server to modify schema reporting defaults:

NameTypeDescription
engine.overrideReportedSchemaString

If provided, Apollo Server sends this string value as the schema to register.

By default, Apollo Server sends its interpreted GraphQLSchema object (the same value it returns from an introspection request) as an SDL string. This default behavior is appropriate for the majority of use cases.

engine.schemaReportingInitialDelayMaxMsInteger

On startup, Apollo Server waits a random number of milliseconds between 0 and this value before attempting to register its schema. This helps stagger registration requests when you deploy multiple instances of your server simultaneously.

The default value is 10000 (10 seconds).

For example, the following value for engine.overrideReportedSchema provides a schema definition directly from Apollo Server's typeDefs object, instead of the interpreted GraphQLSchema created from that object:

const server = new ApolloServer({
  typeDefs,
  resolvers,
  engine: {
    reportSchema: true    overrideReportedSchema: typeDefs.loc && typeDefs.loc.source.body
  }
});

Other GraphQL servers

Any GraphQL server can (and is encouraged to!) support automatic schema registration by implementing the Schema reporting protocol.

Currently, we are not aware of GraphQL server libraries besides Apollo Server that implement the schema reporting protocol. If you add support to an open-source library, please let us know at support@apollographql.com!

Rolling deploys with schema reporting

Whenever you perform a rolling deployment of an update to your schema, different active instances of your server might temporarily report different schemas to the schema registry. If this occurs, the registry uses the following algorithm to choose which schema to register:

No
Yes
No
Yes
Does the specified variant already have an active schema?
Does the active schema match any schema reported in the last 90 seconds?
Register the schema most recently received by the registry
Keep the current active schema

Using this algorithm, your updated schema is registered within a few minutes after your rolling deployment completes.

Edit on GitHub