Testing

perfmetrics.testing provides a testing client for verifying StatsD metrics emitted by perfmetrics in the context of an instrumented application.

It’s easy to create a new client for use in testing:

>>> from perfmetrics.testing import FakeStatsDClient
>>> test_client = FakeStatsDClient()

This client exposes the same public interface as perfmetrics.statsd.StatsdClient. For example we can increment counters, set gauges, etc:

>>> test_client.incr('request_c')
>>> test_client.gauge('active_sessions', 320)

Unlike perfmetrics.statsd.StatsdClient, FakeStatsDClient simply tracks the statsd packets that would be sent. This information is exposed on our test_client both as the raw statsd packet, and for convenience this information is also parsed and exposed as Observation objects. For complete details see FakeStatsDClient and Observation.

>>> test_client.packets
['request_c:1|c', 'active_sessions:320|g']
>>> test_client.observations
[Observation(name='request_c', value='1', kind='c', sampling_rate=None), Observation(name='active_sessions', value='320', kind='g', sampling_rate=None)]

For validating metrics we provide a set of PyHamcrest matchers for use in test assertions:

>>> from hamcrest import assert_that
>>> from hamcrest import contains_exactly as contains
>>> from perfmetrics.testing.matchers import is_observation
>>> from perfmetrics.testing.matchers import is_gauge

We can use both strings and numbers (or any matcher) for the value:

>>> assert_that(test_client,
...     contains(is_observation('c', 'request_c', '1'),
...              is_gauge('active_sessions', 320)))
>>> assert_that(test_client,
...     contains(is_observation('c', 'request_c', '1'),
...              is_gauge('active_sessions', '320')))
>>> from hamcrest import is_
>>> assert_that(test_client,
...     contains(is_observation('c', 'request_c', '1'),
...              is_gauge('active_sessions', is_('320'))))

If the matching fails, we get a descriptive error:

>>> assert_that(test_client,
...     contains(is_gauge('request_c', '1'),
...              is_gauge('active_sessions', '320')))
Traceback (most recent call last):
...
AssertionError:
Expected: a sequence containing [(an instance of Observation and (an object with a property 'kind' matching 'g' and an object with a property 'name' matching 'request_c' and an object with a property 'value' matching '1')), (an instance of Observation and (an object with a property 'kind' matching 'g' and an object with a property 'name' matching 'active_sessions' and an object with a property 'value' matching '320'))]
       but: item 0: was Observation(name='request_c', value='1', kind='c', sampling_rate=None)

Reference

perfmetrics.testing

class FakeStatsDClient(prefix='')

Bases: StatsdClient

A mock statsd client that tracks sent statsd metrics in memory rather than pushing them over a socket. This class is a drop in replacement for perfmetrics.statsd.StatsdClient that collects statsd packets and Observation that are sent through the client.

Changed in version 3.1.0: Like the normal clients, this object is now always true, whether or not any observations have been sent.

__len__()

The number of metrics sent. This accounts for multi metric packets that may be sent.

clear()

Clears the statsd metrics that have been collected

iter_observations()

Iterates the Observations provided to this statsd client.

iter_packets()

Iterates the raw statsd packets provided to the statsd client.

Returns

Iterator of native strings.

property observations

A list of Observation objects collected by this client.

See also

iter_observations

property packets

A list of raw statsd packets collected by this client.

See also

iter_packets

OBSERVATION_KIND_COUNTER = 'c'

The statsd metric kind for Counters

OBSERVATION_KIND_GAUGE = 'g'

The statsd metric kind for Gauges

OBSERVATION_KIND_SET = 's'

The statsd metric kind for Sets

OBSERVATION_KIND_TIMER = 'ms'

The statsd metric kind for Timers

class Observation(name, value, kind, sampling_rate=None)

Bases: object

The representation of a single statsd metric.

kind = None

The statsd code for the type of metric. e.g. one of the METRIC_*_KIND constants

classmethod make(packet)

Creates a metric from the provided statsd packet.

Raises

ValueError – if packet is a multi metric packet or otherwise invalid.

classmethod make_all(packet)

Makes a list of metrics from the provided statsd packet.

Like make but supports multi metric packets

name = None

The metric name

sampling_rate = None

The rate with which this event has been sampled from (optional)

value = None

The value provided for the metric

perfmetrics.testing.matchers

is_counter(*, name, value, sampling_rate) → matcher

A hamcrest matcher validating the parts of a counter Observation.

See also

is_metric

is_gauge(*, name, value, sampling_rate) → matcher

A hamcrest matcher validating the parts of a gauge Observation

See also

is_metric

is_observation(*, kind, name, value, sampling_rate) → matcher

A hamcrest matcher that validates the specific parts of a Observation. All arguments are optional and can be provided by name or position.

Parameters

• kind (str) – A hamcrest matcher or string that matches the kind for this metric

• name (str) – A hamcrest matcher or string that matches the name for this metric

• value (str) – A hamcrest matcher or string that matches the value for this metric

• sampling_rate (float) – A hamcrest matcher or number that matches the sampling rate this metric was collected with

is_set(*, name, value, sampling_rate) → matcher

A hamcrest matcher validating the parts of a set Observation

See also

is_metric

is_timer(*, name, value, sampling_rate) → matcher

A hamcrest matcher validating the parts of a timer Observation

See also

is_metric