jonathanultis/graphitesend

Easy python bindings to write to Carbon ( Re-write of carbonclient)

graphitesend

Easy python bindings to write to Carbon ( Re-write of carbonclient).

Read The Docs

graphitesend.rtfd.org

Blog posts

dansysadm.com

Example Scripts

The github repo of graphitesend-examples has lots of examples using graphitesend to grab data from your local linux system.

Usage Example

Very basic sending of a metric called metric with a value of 45

>>> import graphitesend
>>> graphitesend.init()
>>> graphitesend.send('metric', 45)
>>> graphitesend.send('metric2', 55)

The above would send the following metric to graphite

system.localhostname.metric 45 epoch-time-stamp
system.localhostname.metric2 55 epoch-time-stamp

Cleaning up the interface and using a group of cpu to alter the metric prefix

>>> import graphitesend
>>> g = graphitesend.init(group='cpu')
>>> g.send('metric', 45)
>>> g.send('metric2', 55)

The above would send the following metric to graphite

system.localhostname.cpu.metric 45 epoch-time-stamp
system.localhostname.cpu.metric2 55 epoch-time-stamp

Using a different prefix (other then system.hostname)

>>> import graphitesend
>>> g = graphitesend.init(prefix='apache.rc')
>>> g.send('404', 4)
>>> g.send('200', 500)

The above would send the following metric to graphite

apache.rc.localhostname.404 4 epoch-time-stamp
apache.rc.localhostname.200 500 epoch-time-stamp

To get rid of localhostname, set another argument — system_name

>>> import graphitesend
>>> g = graphitesend.init(prefix='apache.rc', system_name='')
>>> g.send('404', 4)
>>> g.send('200', 500)

The above would send the following metric to graphite

apache.rc.404 4 epoch-time-stamp
apache.rc.200 500 epoch-time-stamp

Sending a dict()

    >>> import graphitesend
    >>> g = graphitesend.init()
    >>> g.send_dict({'metric': 45, 'metric2': 55})

Sending a list()

    >>> import graphitesend
    >>> g = graphitesend.init()
    >>> g.send_list([('metric', 45), ('metric2', 55)])

Sending a list(), with a custom timestamp for all metric-value pairs

    >>> import graphitesend
    >>> g = graphitesend.init()
    >>> g.send_list([('metric', 45), ('metric2', 55)], timestamp=12345)

Sending a list(), with a custom timestamp for each metric-value pairs

    >>> import graphitesend
    >>> g = graphitesend.init()
    >>> g.send_list([('metric', 45, 1234), ('metric2', 55, 1234)])

Learning? Use dryrun.

With dryrun enabled the data will never get sent to a remote service, it will just print out what would have been sent.

    >>> import graphitesend
    >>> g = graphitesend.init(dryrun=True)
    >>> g.send_list([('metric', 45, 1234), ('metric2', 55, 1234)])

Example: the init()

Set a metric prefix (Default arg)

>>> g = graphitesend.init('prefix')
>>> print g.send('metric', 1)
sent 34 long message: prefix.metric 1.000000 1365068929

set a metric prefix using kwargs

>>> g = graphitesend.init(prefix='prefix')
>>> print g.send('metric', 2)
sent 34 long message: prefix.metric 2.000000 1365068929

Squash any dots in the hostname

>>> g = graphitesend.init(fqdn_squash=True)
>>> print g.send('metric', 3)
sent 56 long message: systems.host_example_com.metric 2.00000 1365069029

view the default prefix, hardset systems. then followed by the name of the host that execute the send().

>>> g = graphitesend.init()
>>> print g.send('metric', 3)
sent 44 long message: systems.<system_name>.metric 3.000000 1365069029

Set a suffix, handy if you have a bunch of timers or percentages

>>> g = graphitesend.init(suffix='_ms')
>>> print g.send('metric', 4)
sent 47 long message: systems.<system_name>.metric_ms 4.000000 1365069100

set a system_name if your submitting results for a different system

>>> g = graphitesend.init(system_name='othersystem')
>>> print g.send('metric', 5)
sent 47 long message: systems.othersystem.metric 5.000000 1365069100

Lowercase all the metric names that are send to the graphite server.

>>> g = graphitesend.init(lowercase_metric_names=True)
>>> print g.send('METRIC', 6)
sent 47 long message: systems.<hostname>.metric 6.000000 1365069100

Set a group name, handy if you just parsed iostat and want to prefix all the metrics with iostat, after its already in the <system_name> directory.

>>> g = graphitesend.init(group='groupname')
>>> print g.send('metric', 6)
sent 54 long message: systems.<system_name>.groupname.metric 6.000000 136506924

Connect to a different graphite server

>>> graphitesend.init(graphite_server='graphite.example.com')

Connect to a different graphite server port

>>> graphitesend.init(graphite_port=2003)

Send async messages

>>> graphitesend.init(asynchronous=True)

Change connect timeout (default 2)

>>> graphitesend.init(timeout_in_seconds=5)

CLI

Just added -- A cli script that allows for anything to send metrics over to graphite (not just python).

The usage is very simple you need to give the command a metric and a value.

	$ graphitesend name.of.the.metric 666

Send more* then 1 metric and value

	$ graphitesend name.of.the.metric 666
	$ graphitesend name.of.the.other_metric 2

* Call it 2 times ;)

Installing

pip

$ pip install graphitesend

or

source

$ git clone git://github.com/daniellawrence/graphitesend.git
$ cd graphitesend
$ python ./setup.py install

Porcelain Overview

init

Create the module instance of GraphiteSend.

send

Make sure that we have an instance of the GraphiteClient. Then send the metrics to the graphite server.

send_dict

Make sure that we have an instance of the GraphiteClient. Then send the metrics to the graphite server.

reset

Disconnect from the graphite server and destroy the module instance.

TCP vs UDP

There is a new branch for UDP support called 'udp and tcp'. TCP will continue to be the default with UDP as an option