API Documentation

instrument

you are not expected to understand this implementation. that’s why it has tests. the above-mentioned ‘you’ includes the author. :-}

instrument.iter(iterable, name=None, metric=<function call_default>)

Measure total time and element count for consuming an iterable

Parameters:
  • iterable – any iterable
  • metric (function) – f(name, count, total_time)
  • name (str) – name for the metric
instrument.each(iterable, name=None, metric=<function call_default>)

Measure time elapsed to produce each item of an iterable

Parameters:
  • iterable – any iterable
  • metric (function) – f(name, 1, time)
  • name (str) – name for the metric
instrument.reduce(name=None, metric=<function call_default>)

Decorator to measure a function that consumes many items.

The wrapped func should take either a single iterable argument or *args (plus keyword arguments).

Parameters:
  • metric (function) – f(name, count, total_time)
  • name (str) – name for the metric
instrument.produce(name=None, metric=<function call_default>)

Decorator to measure a function that produces many items.

The function should return an object that supports __len__ (ie, a list). If the function returns an iterator, use iter.func() instead.

Parameters:
  • metric (function) – f(name, count, total_time)
  • name (str) – name for the metric
instrument.func(name=None, metric=<function call_default>)

Decorator to measure function execution time.

Parameters:
  • metric (function) – f(name, 1, total_time)
  • name (str) – name for the metric
instrument.first(iterable, name=None, metric=<function call_default>)

Measure time elapsed to produce first item of an iterable

Parameters:
  • iterable – any iterable
  • metric (function) – f(name, 1, time)
  • name (str) – name for the metric
instrument.block(name=None, metric=<function call_default>, count=1)

Context manager to measure execution time of a block

Parameters:
  • metric (function) – f(name, 1, time)
  • name (str) – name for the metric
  • count (int) – user-supplied number of items, defaults to 1
instrument.print_metric(name, count, elapsed)

A metric function that prints

Parameters:
  • name (str) – name of the metric
  • count (int) – number of elements
  • elapsed (float) – time in seconds
instrument.default_metric(name, count, elapsed)

A metric function that prints

Parameters:
  • name (str) – name of the metric
  • count (int) – number of elements
  • elapsed (float) – time in seconds
instrument.make_multi_metric(*metrics)

Make a new metric function that calls the supplied metrics

Parameters:metrics (functions) – metric functions
Return type:function

instrument.csv

class instrument.csv.CSVDirMetric(name)

Write metrics to multiple CSV files

Do not create instances of this class directly. Simply pass the classmethod metric() to a measurement function. Output using dump(). These are the only public methods.

Each metric consumes one open file and 32K of memory while running.

Variables:
  • dump_atexit – automatically call dump() when the interpreter exits. Defaults to True.
  • outdir – directory to save CSV files in. Defaults to ./mit_csv.
classmethod dump()

Output all recorded metrics

classmethod metric(name, count, elapsed)

A metric function that writes multiple CSV files

Parameters:
  • name (str) – name of the metric
  • count (int) – number of elements
  • elapsed (float) – time in seconds
class instrument.csv.CSVFileMetric(outfile='mit.csv', dump_atexit=True)

Write metrics to a single CSV file

Pass the method metric() to a measurement function. Output using dump(). These are the only public methods.

Variables:
  • outfile – file to save to. Defaults to ./mit.csv.
  • dump_atexit – automatically call dump() when the interpreter exits. Defaults to True.
dump()

Output all recorded metrics

metric(name, count, elapsed)

A metric function that writes a single CSV file

Parameters:
  • name (str) – name of the metric
  • count (int) – number of elements
  • elapsed (float) – time in seconds

instrument.numpy

numpy-based metrics

class instrument.numpy.NumpyMetric

Do not create instances of this class directly. Simply pass the classmethod metric() to a measurement function. Output using dump(). These are the only public methods. This is an abstract base class; you should use one of the concrete subclases in this module instead.

Each metric consumes one open file and 32K of memory while running. Output requires enough memory to load all data points for each metric.

Variables:dump_atexit – automatically call dump() when the interpreter exits. Defaults to True.
classmethod metric(name, count, elapsed)

A metric function that buffers through numpy

Parameters:
  • name (str) – name of the metric
  • count (int) – number of elements
  • elapsed (float) – time in seconds
classmethod dump()

Output all recorded metrics

class instrument.numpy.TableMetric

Print a table of statistics

Variables:outfile – output file. Defaults to sys.stderr.
class instrument.numpy.PlotMetric

Plot graphs of metrics.

Variables:outdir – directory to save plots in. Defaults to ./mit_plots.

instrument.statsd

save metrics to statsd

instrument.statsd.statsd_metric(name, count, elapsed)

Metric that records to statsd/graphite