Skip to main content

Testing StatsD client

Project description


Latest release Supported Python versions Documentation Status


This project is deprecated and unmaintained. Its code has moved into perfmetrics.testing.

The following is for historical information only.

nti.fakestatsd is a testing client for verifying StatsD metrics emitted by perfmetrics.

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

>>> from nti.fakestatsd 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 ~.Metric objects. For complete details see ~.FakeStatsDClient and ~.Metric.

>>> test_client.packets
['request_c:1|c', 'active_sessions:320|g']
>>> test_client.metrics
[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 hamcrest matchers for use in test assertions:

>>> from hamcrest import assert_that
>>> from hamcrest import contains
>>> from nti.fakestatsd.matchers import is_metric
>>> from nti.fakestatsd.matchers import is_gauge

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

>>> assert_that(test_client,
...     contains(is_metric('c', 'request_c', '1'),
...              is_gauge('active_sessions', 320)))
>>> assert_that(test_client,
...     contains(is_metric('c', 'request_c', '1'),
...              is_gauge('active_sessions', '320')))
>>> from hamcrest import is_
>>> assert_that(test_client,
...     contains(is_metric('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):
Expected: a sequence containing [(an instance of Metric 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 Metric 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 Metric(name='request_c', value='1', kind='c', sampling_rate=None)

For complete details and the changelog, see the documentation.


1.0.0 (2019-09-03)

  • This project has been merged into perfmetrics.testing. There will be no further development.

0.0.2 (2018-10-26)

  • Metric kind s is now handled as a distinct type. See issue 6.
  • Metric values are now always native strings. See issue 2.
  • Restructure and document public objects. See issue 1.
  • Add convenience hamcrest matchers. See issue 1.

0.0.1 (2018-10-12)

  • First PyPI release.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

nti.fakestatsd-1.0.0.tar.gz (12.8 kB view hashes)

Uploaded source

Built Distribution

nti.fakestatsd-1.0.0-py2.py3-none-any.whl (9.6 kB view hashes)

Uploaded py2 py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page