Graphitesender API

class graphitesend.graphitesend.GraphiteClient(graphite_server=None, graphite_port=None, prefix=None, timeout_in_seconds=2, debug=False, group=None, system_name=None, suffix=None, lowercase_metric_names=False, connect_on_create=True, fqdn_squash=False, dryrun=False, asynchronous=False, autoreconnect=False, clean_metric_name=True, formatter=None)

Graphite Client that will setup a TCP connection to graphite.

Parameters:

• prefix (Default: "systems.") – string added to the start of all metrics
• graphite_server (Default: graphite) – hostname or ip address of graphite server
• graphite_port (Default: The value of default_port) – TCP port we will connect to
• debug (True or False) – Toggle debug messages
• group – string added to after system_name and before metric name
• system_name (Default: current FDQN) – FDQN of the system generating the metrics
• suffix – string added to the end of all metrics
• lowercase_metric_names – Toggle the .lower() of all metric names
• fqdn_squash (True or False) – Change host.example.com to host_example_com
• dryrun (True or False) – Toggle if it will really send metrics or just return them
• timeout_in_seconds – Number of seconds before a connection is timed out.
• asynchronous – Send messages asynchronouly via gevent (You have to monkey patch sockets for it to work)
• clean_metric_name (True or False) – Does GraphiteClient needs to clean metric’s name
• formatter – Callable that will format metric names

It will then send any metrics that you give it via the .send() or .send_dict().

You can also take advantage of the prefix, group and system_name options that allow you to setup default locations where your whisper files will be kept. eg. ( where ‘linuxserver’ is the name of the localhost)

>>> init().prefix
systems.linuxserver.

>>> init(system_name='remote_host').prefix
systems.remote_host.

>>> init(group='cpu').prefix
systems.linuxserver.cpu.

>>> init(prefix='apache').prefix
apache.

autoreconnect(sleep=1, attempt=3, exponential=True, jitter=5)

Tries to reconnect with some delay:

exponential=False: up to attempt times with sleep seconds between each try

exponential=True: up to attempt times with exponential growing sleep and random delay in range 1..`jitter` (exponential backoff)

Parameters:

• sleep (float or int) – time to sleep between two attempts to reconnect
• attempt (int) – maximal number of attempts
• exponential (bool) – if set - use exponential backoff logic
• jitter (int) – top value of random delay, sec

block_metric(metric_name)

block_metric_cls

alias of graphitesend.block_metric.BlockMetric

clean_metric_name(metric_name)

Make sure the metric is free of control chars, spaces, tabs, etc.

connect()

Make a TCP connection to the graphite server on port self.port

decorator(metric_or_func)

default_port = 2003

If graphite_port is not given, this port will be used

disconnect()

Close the TCP connection with the graphite server.

enable_asynchronous()

Check if socket have been monkey patched by gevent

format_message(metric, value, timestamp=None, formatter=None)

reconnect()

send(metric, value, timestamp=None, formatter=None)

Format a single metric/value pair, and send it to the graphite server.

Parameters:

• metric – name of the metric
• value – value of the metric
• timestmap – epoch time of the event
• formatter – option non-default formatter

>>> g = init()
>>> g.send("metric", 54)

>>> g = init()
>>> g.send(metric="metricname", value=73)

send_dict(data, timestamp=None, formatter=None)

Format a dict of metric/values pairs, and send them all to the graphite server.

Parameters:

• data – key,value pair of metric name and metric value
• timestmap – epoch time of the event
• formatter – option non-default formatter

>>> g = init()
>>> g.send_dict({'metric1': 54, 'metric2': 43, 'metricN': 999})

send_list(data, timestamp=None, formatter=None)

Format a list of set’s of (metric, value) pairs, and send them all to the graphite server.

Parameters:

• data – list of key,value pairs of metric name and metric value
• timestmap – epoch time of the event
• formatter – option non-default formatter

>>> g = init()
>>> g.send_list([('metric1', 54),('metric2', 43, 1384418995)])

class graphitesend.graphitesend.GraphitePickleClient(graphite_server=None, graphite_port=None, prefix=None, timeout_in_seconds=2, debug=False, group=None, system_name=None, suffix=None, lowercase_metric_names=False, connect_on_create=True, fqdn_squash=False, dryrun=False, asynchronous=False, autoreconnect=False, clean_metric_name=True, formatter=None)

default_port = 2004

str2listtuple(string_message)

Covert a string that is ready to be sent to graphite into a tuple

exception graphitesend.graphitesend.GraphiteSendException

graphitesend.graphitesend.cli()

Allow the module to be called from the cli.

graphitesend.graphitesend.init(init_type='plaintext_tcp', *args, **kwargs)

Create the module instance of the GraphiteClient.

graphitesend.graphitesend.reset()

disconnect from the graphite server and destroy the module instance.

graphitesend.graphitesend.send(*args, **kwargs)

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

graphitesend.graphitesend.send_dict(*args, **kwargs)

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

graphitesend.graphitesend.send_list(*args, **kwargs)

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

Formatter

class graphitesend.formatter.GraphiteStructuredFormatter(prefix=None, group=None, system_name=None, suffix=None, lowercase_metric_names=False, fqdn_squash=False, clean_metric_name=True)

Default formatter for GraphiteClient.

Provides structured metric naming based on a prefix, system name, group, etc

Parameters:

• prefix (Default: "systems.") – string added to the start of all metrics
• group – string added to after system_name and before metric name
• system_name (Default: current FDQN) – FDQN of the system generating the metrics
• suffix – string added to the end of all metrics
• lowercase_metric_names – Toggle the .lower() of all metric names
• fqdn_squash (True or False) – Change host.example.com to host_example_com
• clean_metric_name (True or False) – Does GraphiteClient needs to clean metric’s name

Feel free to implement your own formatter as any callable that accepts a metric name as argument and return a formatted metric name.

clean_metric_name(metric_name)

Make sure the metric is free of control chars, spaces, tabs, etc.

cleaning_replacement_list = [('(', '_'), (')', ''), (' ', '_'), ('/', '_'), ('\\', '_')]

class graphitesend.formatter.TemplateFormatter(template, **kwargs)

Formatter based on a template string

Parameters:template – A template string that will be rendered for each metric

Additionnal keyword arguments must be callable, they will be called during rendering with the metric name and should return a string.

The template must use the modern python formatting syntax, but does not support ordered placeholders. The formatting data will consist of the result of the functions given during instanciation, plus special variables:

• name: The name of the metric
• host: The system’s node name

Consider the following example:

>>> formatter = TemplateFormatter("systems.{host}.worker{worker}.{name}",
                                  worker=get_worker_id)

On a machine named foobar and assuming a get_worker_id function that return an id, the metric “processing_time” would be formatted like “systems.foobar.worker3.processing_time”.

make_context(metric_name)

Block metric

class graphitesend.block_metric.BlockMetric(client, metric)

Enable tracking on a block of code

trackers = [<function executions>, <function errors>, <function processing_time>]

Trackers activated during the execution of the block of code

graphitesend.block_metric.errors(*args, **kwds)

Track the number of errors

graphitesend.block_metric.executions(*args, **kwds)

Track the number of executions

graphitesend.block_metric.processing_time(*args, **kwds)

Track the processing time