Performance Tracing for Gatsby Builds

Profiling can give you a significant amount of information about the React side of the equation, but performance tracing to see what takes the longest during Gatsby builds is important as well. Gatsby provides performance tracing capabilities compatible with the OpenTracing standard that can be viewed in an introspection tool such as Zipkin, Jaeger, or Honeycomb.

The instrumentation in Gatsby’s code is done through OpenTracing, an implementation-agnostic tracing API that requires an integrated OpenTracing-compatible library. Gatsby also offers additional tracing capabilities for GraphQL resolvers, which may have a detrimental impact on performance. As such, this is disabled by default, but it can be enabled using the --graphql-tracing flag as follows when kicking off a build:

$ gatsby build --graphql-tracing

Once you’ve added an OpenTracing-compatible library to the dependencies in your package.json file through a package installation, you will need to configure the library to set fields such as the tracing backend’s URL and the frequency with which spans should be delivered to that tracing backend, as well as the service name for recording. OpenTracing configuration files consist of two function exports:createThis function creates and returns a tracer compatible with OpenTracing and is invoked when the build initializes.stopThis function is invoked when the build concludes. Any cleanup that the tracer needs to perform should occur at this point, including clearing any remaining span queues and delivering them to the backend.

Once you have your OpenTracing configuration file in place, you can execute a build for tracing with the following command, optionally including --graphql-tracing:

$ gatsby build --open-tracing-config-file

NOTE

Coverage of tracing using Jaeger and Zipkin in Gatsby is beyond the scope of this app, but you can find out more in the Gatsby documentation. For more information about custom-built tracing, consult the Gatsby documentation’s guide to adding your own tracing. In addition, Gatsby recommends certain workarounds when scalability issues arise, such as out-of-memory errors or extremely slow builds. For more information about these, consult the documentation’s guide to scaling issues.