aiographite

build status coverage status

An asyncio library for graphite.

What is aiographite ?

aiographite is Python3 library ultilizing asyncio, designed to help Graphite users to send data into graphite easily.

Quick start

Let’s get started.

from aiographite import connect
from aiographite.protocol import PlaintextProtocol
import asyncio

"""
  Initialize a aiographite instance
"""
loop = asyncio.get_event_loop()
plaintext_protocol = PlaintextProtocol()
graphite_conn = await connect(*httpd.address, plaintext_protocol, loop=loop)


"""
  Send a tuple (metric, value , timestamp)
"""
graphite_conn.send(metric, value, timestamp)


"""
  Send a list of tuples List[(metric, value , timestamp)]
"""
graphite_conn.send_multiple(list)


"""
  aiographite library also provides GraphiteEncoder module,
  which helps users to send valid metric name to graphite.
  For Example: (metric_parts, value ,timestamp)
"""
metric = graphite_conn.clean_and_join_metric_parts(metric_parts)
graphite_conn.send(metric, value, timestamp)


"""
  Close connection
"""
graphite_conn.close()

Contents:

Installation

Installing it globally

You can install aiographite globally with any Python package manager:

pip install aiographite

AIOGraphite

AIOGraphite is a Graphite client class, ultilizing asyncio, designed to help Graphite users to send data into graphite easily.

from aiographite.aiographite import connect

"""
  Initialize a aiographite instance
"""
loop = asyncio.get_event_loop()
plaintext_protocol = PlaintextProtocol()
graphite_conn = await aiographite.connect(*httpd.address, plaintext_protocol, loop=loop, timeout=None)


"""
  Send a tuple (metric, value , timestamp)
"""
graphite_conn.send(metric, value, timestamp)


"""
  Send a list of tuples List[(metric, value , timestamp)]
"""
graphite_conn.send_multiple(list)


"""
  aiographite library also provides GraphiteEncoder module,
  which helps users to send valid metric name to graphite.
  For Example: (metric_parts, value ,timestamp)
"""
metric = graphite_conn.clean_and_join_metric_parts(metric_parts)
graphite_conn.send(metric, value, timestamp)


"""
  Close connection
"""
graphite_conn.close()

Full API Reference

class aiographite.aiographite.AIOGraphite(graphite_server, graphite_port=2003, protocol=<aiographite.protocol.PlaintextProtocol object>, loop=None, timeout=None)[source]

AIOGraphite is a Graphite client class, ultilizing asyncio, designed to help Graphite users to send data into graphite easily.

clean_and_join_metric_parts(metric_parts: typing.List[str]) → str[source]

This method helps encode any input metric to valid metric for graphite in case that the metric name includes any special character which is not supported by Graphite.

args: a list of metric parts(string).

returns a valid metric name for graphite.

example:

metric = aiographite.clean_and_join_metric_parts(metric_parts)
close() → None[source]

Close the TCP connection to graphite server.

send(metric: str, value: int, timestamp: int = None) → None[source]

send a single metric.

args: metric, value, timestamp. (str, int, int).

send_multiple(dataset: typing.List[typing.Tuple], timestamp: int = None) → None[source]

send a list of tuples.

args: a list of tuples (metric, value, timestamp), and timestamp is optional.

Protocols

AIOGraphite support two protocols:

  • The plaintext protocol
  • The pickle protocol

Plaintext Protocol

class aiographite.protocol.PlaintextProtocol[source]
generate_message(listOfTuples: typing.List[typing.Tuple[[str, int], int]]) → bytes[source]

This method helps generate message with proper format for plaintext protocol.

args: a list of tuples (metric, value, timestamp).

Pickle Protocol

class aiographite.protocol.PickleProtocol[source]
generate_message(listOfTuples: typing.List[typing.Tuple[[str, int], int]]) → bytes[source]

This method helps generate message with proper format for pickle protocol.

args: a list of tuples (metric, value, timestamp).

GraphiteEncoder

aiographite library also provides GraphiteEncoder module, which helps users to send valid metric name to graphite.

Full API Reference

class aiographite.graphite_encoder.GraphiteEncoder[source]

Graphite expects everything to be just ASCII to split/processing them, and then make directories based on metric name. So any special name not allow to appear in directory/file name is not supported by Graphite.

GraphiteEncoder is designed to help users to send valid metric name to graphite.

Metrics: <section_name>.<section_name>.<section_name>.<section_name>

static decode(idna_str)[source]

This method helps to decode a valid metric name in graphite to its original metric name.

args: a valid metric name in graphite.

returns the original metric name.

static encode(section_name)[source]

This method helps to encode any input metric name to a valid graphite metric name.

args: section name(could include any character), a string

returns valid metric name for graphite

Example

A simple example.

from aiographite.protocol import PlaintextProtocol
from aiographite import connect
import time
import asyncio


LOOP = asyncio.get_event_loop()
SERVER = '127.0.0.1'
PORT = 2003


async def test_send_data():
  # Initiazlize an aiographite instance
  plaintext_protocol = PlaintextProtocol()
  graphite_conn = await connect(SERVER, PORT, plaintext_protocol, loop=LOOP)

  # Send data
  timestamp = time.time()
  for i in range(10):
      await graphite_conn.send("yun_test.aiographite", i, timestamp + 60 * i)


def main():
  LOOP.run_until_complete(test_send_data())
  LOOP.close()


if __name__ == '__main__':
  main()

Development

aiographite accepts contributions on GitHub, in the form of issues or pull requests.

Running the tests

Run unit tests.

./uranium test

Indices and tables