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 global
default_metric()
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, useall()
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 singleiterable
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 usingdump()
.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
- dump_atexit (bool) – automatically call
-
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 usingdump()
.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
- outfile – file to save to. Defaults to
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
andelapsed
Return type: function
- level (int) – logging level, defaults to
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 usingdump()
. These are the only public methods. This is an abstract base class; you should use one of the concrete subclases 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
-
classmethod