apollo-tracing

What is apollo-tracing?

The apollo-tracing npm package is used to collect and expose performance tracing data for GraphQL requests in Apollo Server. It helps in understanding the performance characteristics of your GraphQL operations by providing detailed timing information.

What are apollo-tracing's main functionalities?

Enable Tracing in Apollo Server

This code sample demonstrates how to enable tracing in Apollo Server. By setting the `tracing` option to `true` and using `addTracingToResolvers`, you can collect detailed performance data for each GraphQL request.

const { ApolloServer, gql } = require('apollo-server');
const { makeExecutableSchema } = require('@graphql-tools/schema');
const { addTracingToResolvers } = require('apollo-tracing');

const typeDefs = gql`
  type Query {
    hello: String
  }
`;

const resolvers = {
  Query: {
    hello: () => 'Hello world!',
  },
};

const schema = makeExecutableSchema({ typeDefs, resolvers });
addTracingToResolvers(schema);

const server = new ApolloServer({
  schema,
  tracing: true,
});

server.listen().then(({ url }) => {
  console.log(`🚀 Server ready at ${url}`);
});

Accessing Tracing Data

This code sample shows how to access tracing data in the response of a GraphQL query. When tracing is enabled, the response will include an `extensions` field containing detailed timing information for each resolver.

const { ApolloServer, gql } = require('apollo-server');

const typeDefs = gql`
  type Query {
    hello: String
  }
`;

const resolvers = {
  Query: {
    hello: () => 'Hello world!',
  },
};

const server = new ApolloServer({
  typeDefs,
  resolvers,
  tracing: true,
});

server.listen().then(({ url }) => {
  console.log(`🚀 Server ready at ${url}`);
});

// Example query to access tracing data
// query {
//   hello
// }
// The response will include a `extensions` field with tracing data
// {
//   "data": {
//     "hello": "Hello world!"
//   },
//   "extensions": {
//     "tracing": {
//       "version": 1,
//       "startTime": "2023-10-01T00:00:00.000Z",
//       "endTime": "2023-10-01T00:00:00.100Z",
//       "duration": 100000000,
//       "execution": {
//         "resolvers": [
//           {
//             "path": ["hello"],
//             "parentType": "Query",
//             "fieldName": "hello",
//             "returnType": "String",
//             "startOffset": 0,
//             "duration": 100000000
//           }
//         ]
//       }
//     }
//   }
// }

Other packages similar to apollo-tracing

apollo-engine

Apollo Engine is a comprehensive performance monitoring and tracing tool for GraphQL. It provides more advanced features compared to apollo-tracing, such as error tracking, caching, and detailed analytics. It is a more robust solution for production environments.

graphql-metrics

graphql-metrics is a package that provides performance metrics for GraphQL servers. It offers similar functionality to apollo-tracing but focuses more on integrating with monitoring tools like Prometheus and Grafana. It is suitable for users who need to integrate GraphQL performance data with existing monitoring infrastructure.

graphql-extensions

graphql-extensions is a package that allows you to extend the functionality of your GraphQL server, including adding performance tracing. It is more flexible and can be used to implement custom tracing logic, making it a good choice for advanced users who need more control over their tracing implementation.

README

Apollo Tracing (for Node.js)

This package is used to collect and expose trace data in the Apollo Tracing format.

It relies on instrumenting a GraphQL schema to collect resolver timings, and exposes trace data for an individual request under extensions as part of the GraphQL response.

The extension format is work in progress, and we're collaborating with others in the GraphQL community to make it broadly available, and to build awesome tools on top of it.

One use of Apollo Tracing is to add support for Apollo Optics to more GraphQL servers.

Usage

Apollo Server

Apollo Server will include built-in support for tracing in a future release. Until then, you can install a WIP version of tracing support with npm install apollo-server-<variant>@tracing.

The only code change required is to add tracing: true to the options passed to the Apollo Server middleware function for your framework of choice. For example, for Express:

app.use('/graphql', bodyParser.json(), graphqlExpress({
  schema,
  context: {},
  tracing: true,
}));

express-graphql

Using Apollo Tracing with express-graphql currently requires more manual configuration:

import {
  TraceCollector,
  instrumentSchemaForTracing,
  formatTraceData
} from 'apollo-tracing'

...

app.use('/graphql', 
  (req, res, next) => {
    const traceCollector = new TraceCollector();
    traceCollector.requestDidStart();
    req._traceCollector = traceCollector;
    next(); 
  }, 
  graphqlHTTP(request => ({
    schema: instrumentSchemaForTracing(schema),
    context: {
      _traceCollector: request._traceCollector
    },
    graphiql: true,
    extensions: () => {
      const traceCollector = request._traceCollector;
      traceCollector.requestDidEnd();
      return {
        tracing: formatTraceData(traceCollector)
      }
    }
  }))
);