Skip to main content

Opionionated high level StatsD client

Project description

https://travis-ci.org/cknv/charcoal.svg?branch=master

A simple library for sending StatsD metrics in python. It aims to provide a high level API for the user, however that also means that much of the lower level functionality found in most other StatsD clients are not exposed, frankly because I do not find that I need it. So no manually timing things and etc.

Installing

$ pip install charcoal

Use it like so:

import charcoal

my_client = charcoal.StatsClient(prefix, host, port)

For development, the client also provides a disabled kwarg, so you do not have change anything in the code when you want to not send stats:

my_client = charcoal.StatsClient(prefix, host, port, disabled=True)

By itself, the client does not provide much use, but it does provide easy ways to get specific sub-clients, such as timers, counters, etc.

Timing

timer = my_client.timer('my-timer-name').start()

this_takes_a_while()
timer.intermediate('first-pass')

this_takes_a_while()
timer.intermediate('second-pass')
timer.stop()

When you have end up with a measurement from somewhere else, perhaps from an external service, you can also send that, using the .send function on the timer class, in fact this is what the higler level functions above use, behind the scenes.

timer = my_client.timer('my-timer-name')
timer.send('db-call', 12.5)

Counting

counter = my_client.counter('my-counter-name')

counter.increment('some-value', 10)
counter.decrement('some-other-value', 10)

The counter can even be fed a dict like object, such as the Counter from the standard library and send the stats as a single message.

pre_counted = {
    'a-name': 5,
    'another-name': 10,
}

counter.from_mapping(pre_counted)

Gauges

For setting the current value.

gauge = my_client.gauge('my-gauge')

gauge.set('a-name', 10)
gauge.update('a-name', 10)

Sets

For counting unique events, such as unique users on a page.

visitors = my_client.set('visitors')
visitors.add('ids', user.id)

Custom

In case the server you are using supports more metric types than this library, you can send custom metrics:

metric_to_send = 'metric.name:{value}|{type_suffix}'.format(
    value=str(value),
    type_suffix=type_suffix,
)

my_client.send(metric_to_send)

The prefix given to the client when creating it, is then prepended to the metric name, encoded, and sent to the server.

Currently it can even accept multiple metrics in one go:

my_client.send(metric_to_send, other_metric_to_send)

Project details


Download files

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

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distribution

charcoal-0.2.0-py3-none-any.whl (6.7 kB view details)

Uploaded Python 3

File details

Details for the file charcoal-0.2.0-py3-none-any.whl.

File metadata

File hashes

Hashes for charcoal-0.2.0-py3-none-any.whl
Algorithm Hash digest
SHA256 b12ac748c4acc3a6532b44509893269c4d720061877c4909a33ed1863fd1f970
MD5 1ec8872a8015166321d9cbe6745f5dd1
BLAKE2b-256 7d85d27175832aa4d510bc0e08d611683757ec4c45edfca4f3157c8b761fcd24

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page