fastify-gcloud-trace

fastify-gcloud-trace

Google Cloud Trace API Connector for Fastify

fastify-gcloud-trace is a plugin that connects your application with Stackdriver Trace API for Fastify. It is build on top of Stackdriver Trace package, so you can configure Stackdriver Trace API by passing options to traceApiOptions.

This plugin measures how long each event takes in one request, and generates trace results. Here is an example trace result that you can find on Google Cloud Console:

Install

npm i fastify-gcloud-trace --save

or

yarn add fastify-gcloud-trace

Usage

Register the plugin with your project in the following way and that's it!

const fastify = require('fastify')();

// Please register this plugin at the beginning unless there is a specific reason not to.
fastify.register(
  require('fastify-gcloud-trace')({
    traceApiOptions: {
      // Pass options for Stackdriver Trace API
      ignoreMethods: ['OPTIONS'],
    },
  }),
);

fastify.listen(3000, err => {
  if (err) throw err;
});

This plugin attaches a Trace object to each request, and the object is accessible as rootSpan in a request.gtrace object. Therefore, you can access the trace instance in your application code, and perform all functionalities defined in the Stackdriver Trace API. For example, you can create a childSpan in the following way. It is important to note that rootSpan is only defined when traceAPI generates a "traced" root span, so your application code has to handle the case where rootSpan is null. You can find the different types of span here.

fastify.get('/foo', (req, reply) => {
  const span = req.gtrace.rootSpan
    ? req.gtrace.rootSpan.createChildSpan({name: 'Perform Heavy Calculation'})
    : null;
  // Do something
  if (span) {
    span.endSpan();
  }
  reply.send({hello: 'world'});
});

Options

This is the list of available options.

• traceApiOptions - The options for the Trace API. The details are here.
• tracePluginOptions:
  • enabled - If it is true, it generates a trace. The default value is true.
  • nameOverride - You can pass a function to overide a name for a trace. The function should take a Request as an argument.

Limitations

It only supports StackDriver Trace API right now. If there is enough demand, I would also build support for OpenCensus packages unless Google adds automatic support for Fasify.

License Licensed under MIT.

Changelog

[2.0.0] - 2020-04-05

Changed

• Avoid modifing request objects too much. Now you can access root span under req.gtrace property. This is not a backward compatible chage.