Staphylus

Staphylus is a lightweight framework for trace probing and performance profiling.

Installation

Using npm:

$ npm install --save node-staphylus
$ npm install -g staphylus-cli

How It Works

By inserting traces in the code, it enables the profiler to collect runtime information, which will then be transferred via sockets to the client for printing and visualizing. Here is a simple demo.

Traces

Here is a list of available trace types.

• Single Trace

  single(name, ...args)

  Used for single entry probes. Optionally users can append a list of arguments for debugging.

  • name - Required. Name of the trace
  • args - Optional. List of custom arguments

  Example:

  function add(x, y) {
      const sum = x + y;
      profiler.single('Addition', x, y, sum);
      return sum;
  }

• Interval Trace

  begin(name, ...args)
  end(name, ...args)

  Used for interval probes. The begin and end trace will be coupled by the trace name to provide useful information like time duration. Optionally users can append a list of arguments for debugging.

  • name - Required. Name of the trace
  • args - Optional. List of custom arguments

  Example:

  // Asynchronously
  function readDir(path) {
      // Add path to the begin argument list
      profiler.begin('ReadDir', path);
        
      // Use fs to read directory synchronously
      fs.readdir(path, function(err, content) {
          // Add error, directory content to the end argument list
          profiler.end('ReadDir', err, content.toString('utf-8'));
      });
  }
  
  // Synchronously
  function readDirSync(path) {
      // Add path to the begin argument list
      profiler.begin('ReadDirSync', path);
        
      // Use fs to read dir synchronously
      var content = fs.readdirSync(path);
  
      // Add directory content to the end argument list
      profiler.end('ReadDirSync', content.toString('utf-8'));
  }

• Async Function Trace

  async(name, fn, ...args)

  Used for async function. It is similar to the async function example above but provides a more convenient way to embed interval traces.

  It assumes that the last argument of fn is the callback function, and the end trace will be embedded right below the callback is fired. If the last argument is not a function, the profiler will treat it as a sync function trace (see below).

  • name - Required. Name of the trace
  • fn - Required. Name of the async function
  • args - Optional. List of function arguments. If the async function does not require any arguments, then leave it blank.

  Example:

  profiler.async('ReadDir', fs.readdir, '/tmp', function(err, data) {
       console.log('err', err);
       console.log('data', data);
   });

• Sync Function Trace

  sync(name, fn, ...args)

  Used for sync function. It is similar to the sync function example above but provides a more convenient way to embed interval traces.

  sync will preserve the original return value of the function and add it to the end argument list.

  • name - Required. Name of the trace
  • fn - Required. Name of the async function
  • args - Optional. List of function arguments. If the async function does not require any arguments, then leave it blank.

  Example:

  var content = profiler.sync('ReadDirSync', fs.readdirSync, '/tmp');

Options

Here is a list of options that can be used to configure profiler.

• server.port

  Port for sending and receiving trace buffer. 3030 by default.

Example:

const options = {
    server: {
        port: 8080,
    },
};
const profiler = new Profiler(options);

Credits

Made possible by protobuf, socket.io. Inspired by Ariadne.