Metrics and logging

Apollo Server integrates seamlessly with Apollo GraphOS to help you monitor the execution of your GraphQL operations. Apollo Server additionally provides configurable mechanisms for logging each phase of a GraphQL operation.

Sending metrics to GraphOS

Apollo GraphOS provides an integrated hub for all of your GraphQL performance data, which you can view in Apollo Studio. Studio aggregates and displays information for your schema, queries, requests, and errors. You can also configure alerts that support Slack and Datadog integrations.

Connecting to GraphOS

To connect Apollo Server to GraphOS, first obtain a graph API key. To provide this key to Apollo Server, assign it to the APOLLO_KEY environment variable in your server's environment.

Then associate your server instance with a particular graph ID and graph variant by setting the APOLLO_GRAPH_REF environment variable.

You can set environment variable values on the command line as seen below, or with the dotenv npm package (or similar).

1
# Replace the example values below with values specific to your use case.
2
# This example associates your server with the `my-variant` variant of
3
# the `my-graph` graph.
4
$ APOLLO_KEY=YOUR_API_KEY APOLLO_GRAPH_REF=my-graph@my-variant \
5
  node start-server.js

Communicating with Studio

By default, Apollo Server aggregates your traces and sends them in batches to Studio every minute. This behavior is highly configurable, and you can change the parameters in the Usage Reporting plugin's configuration.

Identifying distinct clients

Apollo Studio's client awareness feature enables you to view metrics for distinct versions of your clients. To enable this, your clients need to include some or all of the following identifying information in the headers of GraphQL requests they send to Apollo Server:

Each of these fields can have any string value that's useful for your application. To simplify the browsing and sorting of your client data in Studio, a three-part version number (such as 1.0.1) is recommended for client versions.

Setting client awareness headers in Apollo Client

If you're using Apollo Client, you can set default values for client name and version in the ApolloClient constructor. All requests to Apollo Server will automatically include these values in the appropriate headers.

Using custom headers

For more advanced cases, or to use headers other than the default headers, pass a generateClientInfo function into the usage reporting plugin:

1
import { ApolloServer } from '@apollo/server';
2
import { ApolloServerPluginUsageReporting } from '@apollo/server/plugin/usageReporting';
3

4
const server = new ApolloServer({
5
  typeDefs,
6
  resolvers,
7
  plugins: [
8
    ApolloServerPluginUsageReporting({
9
      generateClientInfo: ({ request }) => {
10
        const headers = request.http && request.http.headers;
11
        if (headers) {
12
          return {
13
            clientName: headers['apollographql-client-name'],
14
            clientVersion: headers['apollographql-client-version'],
15
          };
16
        } else {
17
          return {
18
            clientName: 'Unknown Client',
19
            clientVersion: 'Unversioned',
20
          };
21
        }
22
      },
23
    }),
24
  ],
25
});
26

27
const { url } = await startStandaloneServer(server);
28

29
console.log(`🚀 Server listening at: ${url}`);

1
import { ApolloServer } from '@apollo/server';
2
import { ApolloServerPluginUsageReporting } from '@apollo/server/plugin/usageReporting';
3

4
const server = new ApolloServer({
5
  typeDefs,
6
  resolvers,
7
  plugins: [
8
    ApolloServerPluginUsageReporting({
9
      generateClientInfo: ({ request }) => {
10
        const headers = request.http && request.http.headers;
11
        if (headers) {
12
          return {
13
            clientName: headers['apollographql-client-name'],
14
            clientVersion: headers['apollographql-client-version'],
15
          };
16
        } else {
17
          return {
18
            clientName: 'Unknown Client',
19
            clientVersion: 'Unversioned',
20
          };
21
        }
22
      },
23
    }),
24
  ],
25

26
});
27

28
const { url } = await startStandaloneServer(server);
29

30
console.log(`🚀 Server listening at: ${url}`);

Logging

You can set up fine-grained operation logging in Apollo Server by defining a custom plugin. Apollo Server plugins enable you to perform actions in response to individual phases of the GraphQL request lifecycle, such as whenever a GraphQL request is received from a client.

The example below defines a plugin that responds to three different operation events. As it shows, you provide an array of your defined plugins to the ApolloServer constructor.

For a list of available lifecycle events and their descriptions, see Plugins.

1
const myPlugin = {
2
  // Fires whenever a GraphQL request is received from a client.
3
  async requestDidStart(requestContext) {
4
    console.log('Request started! Query:\n' + requestContext.request.query);
5

6
    return {
7
      // Fires whenever Apollo Server will parse a GraphQL
8
      // request to create its associated document AST.
9
      async parsingDidStart(requestContext) {
10
        console.log('Parsing started!');
11
      },
12

13
      // Fires whenever Apollo Server will validate a
14
      // request's document AST against your GraphQL schema.
15
      async validationDidStart(requestContext) {
16
        console.log('Validation started!');
17
      },
18
    };
19
  },
20
};
21

22
const server = new ApolloServer({
23
  typeDefs,
24
  resolvers,
25
  plugins: [myPlugin],
26
});

1
const myPlugin = {
2
  // Fires whenever a GraphQL request is received from a client.
3
  async requestDidStart(requestContext) {
4
    console.log('Request started! Query:\n' + requestContext.request.query);
5

6
    return {
7
      // Fires whenever Apollo Server will parse a GraphQL
8
      // request to create its associated document AST.
9
      async parsingDidStart(requestContext) {
10
        console.log('Parsing started!');
11
      },
12

13
      // Fires whenever Apollo Server will validate a
14
      // request's document AST against your GraphQL schema.
15
      async validationDidStart(requestContext) {
16
        console.log('Validation started!');
17
      },
18
    };
19
  },
20
};
21

22
const server = new ApolloServer({
23
  typeDefs,
24
  resolvers,
25
  plugins: [myPlugin],
26
});

OpenTelemetry support

See OpenTelemetry in Apollo Server.