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.all(iterable=None, *, name=None, metric=<function call_default>)

Measure total time and item count for consuming an iterable

Parameters:
  • iterable – any iterable
  • metric (function) – f(name, count, total_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.call_default(name, count, elapsed)

call the default_metric() global in this module

Parameters:
  • name (str) – name of the metric
  • count (int) – number of items
  • elapsed (float) – time in seconds
class instrument.counted_iterable(iterable)

helper class that wraps an iterable and counts items

instrument.each(iterable=None, *, 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.first(iterable=None, *, 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.function(*, 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.producer(*, 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() instead.

Parameters:
  • metric (function) – f(name, count, total_time)
  • name (str) – name for the metric
instrument.reducer(*, 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.output

instrument.output.make_multi_metric(*metrics)

Make a new metric function that calls the supplied metrics

Parameters:metrics (functions) – metric functions
Return type:function
instrument.output.print_metric(name, count, elapsed)

A metric function that prints to standard output

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

A metric function that prints to standard error

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

instrument.output.csv

write metrics to csv files

class instrument.output.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 (bool) – automatically call dump() when the interpreter exits. Defaults to True.
  • outdir (str) – directory to save CSV files in. Defaults to ./instrument_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 items
  • elapsed (float) – time in seconds
class instrument.output.csv.CSVFileMetric(outfile='instrument.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 ./instrument.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 items
  • elapsed (float) – time in seconds

instrument.output.logging

save metrics to standard library logging

instrument.output.logging.make_log_metric(level=20, msg='%d items in %.2f seconds')

Make a new metric function that logs at the given level

Parameters:
  • level (int) – logging level, defaults to logging.INFO
  • msg (string) – logging message format string, taking count and elapsed
Return type:

function

instrument.output.table

print pretty tables of statistics

class instrument.output.table.TableMetric(name)

Print a table of statistics. See NumpyMetric for usage.

Variables:outfile – output file. Defaults to sys.stderr.

instrument.output.plot

plot metrics with matplotlib

class instrument.output.plot.PlotMetric(name)

Plot graphs of metrics. See NumpyMetric for usage.

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

instrument.output.statsd

save metrics to statsd

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

Metric that records to statsd & graphite

instrument.output._numpy

numpy-based metrics

class instrument.output._numpy.NumpyMetric(name)

Base class for numpy-based metrics

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 (bool) – automatically call dump() when the interpreter exits. Defaults to True.
classmethod dump()

Output all recorded metrics

classmethod metric(name, count, elapsed)

A metric function that buffers through numpy

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