Gatsby allows a build to be traced, enabling you to find which plugins or parts of the build are taking the longest. The trace information can be viewed in any OpenTracing compatible tool such as Jaeger. You can also use Zipkin compatible tools such as Zipkin or Honeycomb.
Gatsby code is instrumented with OpenTracing, which is a general tracing API that is implementation agnostic. Therefore, you’ll need to include and configure an OpenTracing compatible library in your application, as well as a backend to collect the trace data.
Add an OpenTracing compatible library to your site’s
Each OpenTracing library must be configured. For example, what is the URL of the tracing backend? How often should spans be sent to the backend? What service name should the trace be recorded under? Etc.
- create: Create and return an OpenTracing compatible tracer. It is called at the start of the build.
- stop: Called at the end of the build. Any cleanup required by the tracer should be performed here, such as clearing out any span queues and sending them to the tracing backend.
The above configuration file can be passed to Gatsby with the
--open-tracing-config-file command-line option. When Gatsby is started with this option, it will load the supplied tracing configuration file, and call its
create function. The returned Tracer will be used for tracing the build. Once the build has stopped, the configuration file’s
stop method will be called, allowing the tracing implementation to perform any cleanup.
Jaeger is an open source tracing system that can be run locally using Docker.
Add jaeger-client to your site:
Run Jaeger’s all-in-one Docker instance with:
See Jaeger getting started for more information.
--open-tracing-config-filepointing at the Jaeger configuration file. An example file is provided in the Gatsby project under node_modules/gatsby/dist/utils/tracer/jaeger-local.js that will send tracing spans to your local Docker instance over HTTP. E.g
Once the build is complete, view your tracing information at http://localhost:16686. On the left menu, select the
buildoperation to see your build’s root trace.
Zipkin is an open source tracing system that can be run locally using Docker.
Add following dependencies to your site’s
Run Zipkin’s all-in-one Docker instance with
docker run -d -p 9411:9411 openzipkin/zipkin. See Zipkin getting started for more information.
--open-tracing-config-filepointing at the Zipkin configuration file. An example file is provided in the Gatsby project under
node_modules/gatsby/dist/utils/tracer/zipkin-local.jsthat will send tracing spans to your local Docker instance. E.g
Once the build is complete, view your tracing information at http://localhost:9411
The default tracing that comes with Gatsby can give you a good idea of which plugins or stages of the build are slowing down your site. But sometimes, you’ll want to trace the internals of your site. Or if you’re a plugin author, you might want to trace long operations.
To provide custom tracing, you can use the
tracing object, which is present in the args passed to API implementers. This tracing object contains a function called
startSpan. This simply wraps OpenTracing startSpan, but provides the default
childOf: parentSpan span args.
startSpan returns a span object that you must explicitly end by calling its
.finish() method. For example:
With this span, you can perform any OpenTracing span operation such as span.setTag. Just make sure that the tracing backend supports these operations. You can provide an optional second span options argument to
startSpan which will be passed to the underlying OpenTracing call.
For advanced use cases, the
tracing object also provides
parentSpan fields. You can use these to construct independent spans, or your own child spans (see the OpenTracing project for more info).
Edit this page on GitHub