Pytelegraf

Python client for sending metrics to Telegraf inspired by pystatsd

Designed to work with Telegraf UDP listener input plugin. https://github.com/influxdata/telegraf/tree/master/plugins/inputs/udp_listener

Pytelegraf supports and is tested to function with Telegraf version 0.13 and newer. It may work with older versions too but that is untested.

Pytelegraf outputs InfluxDB line protocol https://docs.influxdata.com/influxdb/v0.13/write_protocols/line/

Contacting

Need answers? Join pytelegraf on Gitter

If you find this library useful please let me know https://twitter.com/joonapaak

If you have an idea how this library can be improved then open an issue or even better send a pull request :)

How to install

pip install pytelegraf

Usage

from telegraf.client import TelegrafClient
client = TelegrafClient(host='localhost', port=8092)

# Records a single value with no tags
client.metric('some_metric', 123)

# Records a three values with different data types
client.metric('some_metric', {'value_a': 100, 'value_b': 100, 'value_c': True})

# Records a single value with one tag
client.metric('some_metric', 123, tags={'server_name': 'my-server'})

Global tags

The client can be initialized with global tags that will be sent with every metric implicitly

This is useful for adding tagging metrics by host or app

client = TelegrafClient(host='localhost', port=8092, tags={'host': 'my-host-001'})

# Records a single value
client.metric('some_metric', 123)

Because client was initialized with tags the metric contains them too so the line that was sent to Telegraf looks like this

some_metric,host=my-host-001 value=123i

Global tags can be overridden by defining them when sending a metric

# Records a single value with host tag
client.metric('some_metric', 123, tags={'host':'another-host-001', 'some_tag':'some_value'})

Will send the following line

some_metric,host=another-host-001,some_tag=some_value value=123i

HTTP Client

The default TelegrafClient uses UDP to send metrics to Telegraf. The HttpClient works similarly, except that it issues requests via an HTTP POST. HTTP introduces non-trivial overhead, so to avoid blocking the main thread, these POSTs are issued in the background.

To use the HttpClient, pytelegraf must be installed like this: pip install pytelegraf[http]. Alternatively, add pytelegraf[http] to requirements.txt.

from telegraf import HttpClient

http_client = HttpClient(host='localhost', port=8186)
http_client.metric('some_metric', 123, tags={'server_name': 'my-server'})

Telegraf configuration for versions 1.3 and higher

Just follow the sample configuration https://github.com/influxdata/telegraf/tree/master/plugins/inputs/socket_listener

[[inputs.socket_listener]]
  service_address = "udp://localhost:8092"
  data_format = "influx"

Telegraf configuration for versions lower than 1.3

Just follow the sample configuration https://github.com/influxdata/telegraf/blob/b59266249dbeff43ba21bfd3dcc854b12eefd9ca/plugins/inputs/udp_listener/README.md

[[inputs.udp_listener]]
  service_address = "localhost:8092"
  allowed_pending_messages = 10000
  data_format = "influx"

Using with Django

Define configuration in Django settings

TELEGRAF_HOST = 'localhost'
TELEGRAF_PORT = 8092
TELEGRAF_TAGS = {'some-global-tag': 'some-value'}

Then use the client in code

from telegraf.defaults.django import telegraf

telegraf.metric('some-metric', 1)

How to develop

• Clone or fork this repo
• Make changes
• Run tests with python setup.py test
• Submit a pull request

Contributors

• bobo333
• sbi
• isvinogradov
• umax