Introduction¶

A library to easily measure what’s going on in your python.

Metrology allows you to add instruments to your python code and hook them to external reporting tools like Graphite so as to better understand what’s going on in your running python program.

You can report bugs and discuss features on the issues page.

Table Of Contents¶

Installation¶

Either check out Metrology from GitHub or to pull a release off PyPI

pip install metrology

Instruments¶

Gauges¶

class metrology.instruments.gauge.Gauge¶

A gauge is an instantaneous measurement of a value

class JobGauge(metrology.instruments.Gauge):
    @property
    def value(self):
        return len(queue)

gauge = Metrology.gauge('pending-jobs', JobGauge())

class metrology.instruments.gauge.PercentGauge¶: A percent gauge is a ratio gauge where the result is normalized to a value between 0 and 100.

class metrology.instruments.gauge.RatioGauge¶: A ratio gauge is a simple way to create a gauge which is the ratio between two numbers.

Counters¶

class metrology.instruments.counter.Counter¶

A counter is like a gauge, but you can increment or decrement its value

counter = Metrology.counter('pending-jobs')
counter.increment()
counter.decrement()
counter.count

count¶: Return the current value of the counter.

decrement(value=1)¶

Decrement the counter. By default it will decrement by 1.

Parameters:	value – value to decrement the counter.

increment(value=1)¶

Increment the counter. By default it will increment by 1.

Parameters:	value – value to increment the counter.

Derive¶

class metrology.instruments.derive.Derive(average_class=<class 'metrology.stats.ewma.EWMA'>)¶

A derive is like a meter but accepts an absolute counter as input.

derive = Metrology.derive(‘network.io’) derive.mark() derive.count

mark(value=1)¶

Record an event with the derive.

Parameters:	value – counter value to record

Meters¶

class metrology.instruments.meter.Meter(average_class=<class 'metrology.stats.ewma.EWMA'>)¶

A meter measures the rate of events over time (e.g., “requests per second”).

In addition to the mean rate, you can also track 1, 5 and 15 minutes moving averages

meter = Metrology.meter('requests')
meter.mark()
meter.count

count¶: Returns the total number of events that have been recorded.

fifteen_minute_rate¶: Returns the fifteen-minute average rate.

five_minute_rate¶: Returns the five-minute average rate.

mark(*args, **kwargs)¶

Record an event with the meter. By default it will record one event.

Parameters:	value – number of event to record

mean_rate¶: Returns the mean rate of the events since the start of the process.

one_minute_rate¶: Returns the one-minute average rate.

Histograms¶

class metrology.instruments.histogram.Histogram(sample)¶

A histogram measures the statistical distribution of values in a stream of data. In addition to minimum, maximum, mean, it also measures median, 75th, 90th, 95th, 98th, 99th, and 99.9th percentiles

histogram = Metrology.histogram('response-sizes')
histogram.update(len(response.content))

Metrology provides two types of histograms: uniform and exponentially decaying.

count¶: Return number of values.

max¶: Returns the maximun value.

mean¶: Returns the mean value.

min¶: Returns the minimum value.

stddev¶: Returns the standard deviation.

total¶: Returns the total value.

variance¶: Returns variance

class metrology.instruments.histogram.HistogramExponentiallyDecaying¶

A exponentially decaying histogram produces quantiles which are representative of approximately the last five minutes of data.

Unlike the uniform histogram, a biased histogram represents recent data, allowing you to know very quickly if the distribution of the data has changed.

class metrology.instruments.histogram.HistogramUniform¶

A uniform histogram produces quantiles which are valid for the entirely of the histogram’s lifetime. It will return a median value, for example, which is the median of all the values the histogram has ever been updated with.

Use a uniform histogram when you’re interested in long-term measurements. Don’t use one where you’d want to know if the distribution of the underlying data stream has changed recently.

Timers and utilization timers¶

class metrology.instruments.timer.Timer(histogram=<class 'metrology.instruments.histogram.HistogramExponentiallyDecaying'>)¶

A timer measures both the rate that a particular piece of code is called and the distribution of its duration

timer = Metrology.timer('responses')
with timer:
    do_something()

count¶: Returns the number of measurements that have been made.

fifteen_minute_rate¶: Returns the fifteen-minute average rate.

five_minute_rate¶: Returns the five-minute average rate.

max¶: Returns the maximum amount of time spent in the operation.

mean¶: Returns the mean time spent in the operation.

mean_rate¶: Returns the mean rate of the events since the start of the process.

min¶: Returns the minimum amount of time spent in the operation.

one_minute_rate¶: Returns the one-minute average rate.

stddev¶: Returns the standard deviation of the mean spent in the operation.

total_time¶: Returns the total time spent.

update(duration)¶: Records the duration of an operation.

class metrology.instruments.timer.UtilizationTimer(histogram=<class 'metrology.instruments.histogram.HistogramExponentiallyDecaying'>)¶

A specialized timer that calculates the percentage of wall-clock time that was spent

utimer = Metrology.utilization_timer('responses')
with utimer:
  do_something()

count¶: Returns the number of measurements that have been made.

fifteen_minute_rate¶: Returns the fifteen-minute average rate.

fifteen_minute_utilization¶: Returns the fifteen-minute average utilization as a percentage.

five_minute_rate¶: Returns the five-minute average rate.

five_minute_utilization¶: Returns the five-minute average utilization as a percentage.

max¶: Returns the maximum amount of time spent in the operation.

mean¶: Returns the mean time spent in the operation.

mean_rate¶: Returns the mean rate of the events since the start of the process.

mean_utilization¶: Returns the mean (average) utilization as a percentage since the process started.

min¶: Returns the minimum amount of time spent in the operation.

one_minute_rate¶: Returns the one-minute average rate.

one_minute_utilization¶: Returns the one-minute average utilization as a percentage.

stddev¶: Returns the standard deviation of the mean spent in the operation.

total_time¶: Returns the total time spent.

Health Checks¶

class metrology.instruments.healthcheck.HealthCheck¶

A health check is a small self-test to verify that a specific component or responsibility is performing correctly

class DatabaseHealthCheck(metrology.healthcheck.HealthCheck):
    def __init__(self, database):
        self.database = database

    def check(self):
        if database.ping():
            return True
        return False

health_check = Metrology.health_check('database',
                                      DatabaseHealthCheck(database))
health_check.check()

check()¶: Returns True if what is being checked is healthy

Reporters¶

Graphite¶

class metrology.reporter.graphite.GraphiteReporter(host, port, **options)¶

A graphite reporter that send metrics to graphite

reporter = GraphiteReporter('graphite.local', 2003)
reporter.start()

Parameters:	host – hostname of graphite port – port of graphite interval – time between each reporting prefix – metrics name prefix

Logging¶

class metrology.reporter.logger.LoggerReporter(logger=<module 'logging' from '/usr/lib/python2.7/logging/__init__.pyc'>, level=20, **options)¶

A logging reporter that write metrics to a logger

reporter = LoggerReporter(level=logging.DEBUG, interval=10)
reporter.start()

Parameters:	logger – logger to use level – logger level interval – time between each reporting prefix – metrics name prefix

Librato¶

class metrology.reporter.librato.LibratoReporter(email, token, **options)¶

A librato metrics reporter that send metrics to librato

reporter = LibratoReporter("<email>", "<token>", source="front.local")
reporter.start()

Parameters:	email – your librato email token – your librato api token source – source of the metric interval – time between each reporting prefix – metrics name prefix filters – allow given keys to be send excludes – exclude given keys to be send

Ganglia¶

class metrology.reporter.ganglia.GangliaReporter(default_group_name, host, port, protocol='udp', *args, **kwargs)¶

A ganglia reporter that send metrics to ganglia

reporter = GangliaReporter('Report Group Name',
                           'localhost',
                           8649,
                           'udp',
                           interval=60)
reporter.start()

Parameters:	default_group_name – default group name for ganglia host – hostname of gmond port – port of gmond protocol – protocol for gmond sockets interval – time between each reporting

set_group(metric_name, group_name)¶: Override the group name for certain metrics.

WSGI Middleware¶

WSGI¶

class metrology.wsgi.Middleware(application, reporter=None, **kwargs)¶

A WSGI middleware to measure requests rate and time

application = Middleware(application, reporter)

Parameters:	application – your wsgi application reporter – your metrology reporter