Skip to main content
This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (
Help us improve Python packaging - Donate today!

Opionionated high level StatsD client

Project Description

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.


$ 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.


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



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)


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,



For setting the current value.

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

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


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

visitors = my_client.set('visitors')


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

metric_to_send = '{value}|{type_suffix}'.format(


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)

Release History

This version
History Node


History Node


Download Files

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

Filename, Size & Hash SHA256 Hash Help File Type Python Version Upload Date
(6.7 kB) Copy SHA256 Hash SHA256
Wheel 3.5 May 31, 2016

Supported By

Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Google Google Cloud Servers DreamHost DreamHost Log Hosting