Instrumentation Generator

Usage

thor list can be passed to get a list of all available thor commands

instrumentation:scaffold

This task requires one parameter by default: the name of the library or class you are instrumenting. This task generates the basic file structure needed to add new instrumentation to the Ruby agent.

Run it using:

thor instrumentation:scaffold gem_name

It accepts two optional parameters:

With the optional parameters, the task can be run like so:

thor instrumentation:scaffold gem_name --method=method_to_instrument --args=arg1,arg2,arg3

WIP: instrumentation:add_new_method

Are you trying add instrumentation for a method within library we already instrument? This task is for you! Instead of building the entire scaffold, this task inserts only the changes needed within the instrumentation.rb and test files to instrument the new method. It requires one argument, the name of the existing instrumentation to add the method to. If the instrumented library does not already exist, it will create a new scaffold for that library.

Run it using:

thor instrumentation:scaffold gem_name

It accepts two optional parameters:

With the optional parameters, the task can be run like so:

thor instrumentation:add_new_method gem_name --method=method_to_instrument --args=arg1,arg2,arg3

Idea

Create a CLI, similar to Rails’ generators and scaffold scripts, to create the required files and basic classes for instrumenting new libraries. The hope is that the parts of adding new instrumentation that is repetitive can be eliminated and/or reduced so that it takes less time to add new instrumentation and we can spend development time considering the best attributes to collect and interactions to measure. I also hope this project will reduce the overall toil related to adding new instrumentation.

The files we create with little variation besides library and method names are:

Furthermore, we also create very similar snippets inside the default source configuration file that could be generated by this project as well.

Outcome

A prototype outside the agent was first created. This prototype generated the required files to add instrumentation. The prototype accepted three arguments: name (name of the library), method (method to instrument), args (arguments for the method). This prototype has evolved into the current directory.

This project leverages the Ruby gem Thor, a toolkit for building powerful command-line interfaces used in Bundler, Vagrant, Rails and others powers this CLI.