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='')[source]¶
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 andObservation
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__()[source]¶
The number of metrics sent. This accounts for multi metric packets that may be sent.
- iter_observations()¶
Iterates the
Observations
provided to this statsd client.
- iter_packets()[source]¶
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
- property packets¶
A list of raw statsd packets collected by this client.
See also
- 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)[source]¶
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)[source]¶
Creates a metric from the provided statsd packet.
- Raises
ValueError – if packet is a multi metric packet or otherwise invalid.
- classmethod make_all(packet)[source]¶
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 [source]¶
A hamcrest matcher validating the parts of a counter
Observation
.See also
is_metric
- is_gauge(*, name, value, sampling_rate) matcher [source]¶
A hamcrest matcher validating the parts of a gauge
Observation
See also
is_metric
- is_observation(*, kind, name, value, sampling_rate) matcher [source]¶
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 [source]¶
A hamcrest matcher validating the parts of a set
Observation
See also
is_metric
- is_timer(*, name, value, sampling_rate) matcher [source]¶
A hamcrest matcher validating the parts of a timer
Observation
See also
is_metric