Python logging handler that sends messages to InfluxDB using the line protocol over UDP.
Project description
# ``influxpy``
[![Coverage Status](https://coveralls.io/repos/github/awelzel/influxpy/badge.svg?branch=master)](https://coveralls.io/github/awelzel/influxpy?branch=master) [![Build Status](https://travis-ci.org/awelzel/influxpy.svg?branch=master)](https://travis-ci.org/awelzel/influxpy)
# About
Python logging handler that sends messages to InfluxDB using the line protocol
with support for UDP and decidedly not HTTP.
The code is heavily inspired by and based on [graypy][1].
# Usage
## Example
import logging
import influxpy
my_logger = logging.getLogger("test_logger")
my_logger.setLevel(logging.DEBUG)
handler = influxpy.UDPHandler("localhost", 8089, "example_logs",
facility="example")
my_logger.addHandler(handler)
my_logger.debug("Hello InfluxDB.")
Tracebacks are added as full messages::
try:
puff_the_magic_dragon()
except NameError:
my_logger.debug("No dragons here.", exc_info=1)
## InfluxDB Configuration
The UDP Input for InfluxDB has to be enabled in order to make use of this
library.
# influxdb.conf:
...
[[udp]]
enabled = true
bind-address = ":8089"
database = "udp"
Also take note of the [InfluxDB UDP documentation][2].
## Configuration parameters
``influxpy.UDPHandler``:
* **host** - The host of the InfluxDB server.
* **port** - The UDP port of the InfluxDB server.
* **debugging_fields** - send debug fields if true (the default).
* **extra_fields** - send extra fields on the log record to InfluxDB if true (the default).
* **fqdn** - Use ``socket.getfqdn()`` instead of ``socket.gethostname()`` to set the source host.
* **localname** - Use the specified hostname as source host.
* **facility** - Set facility. If unspecified, it is naively guessed from ``sys.argv[0]``.
# Schema
## Tags
facility, host, level, level_name, logger
The ``facility`` field, in most cases, should be provided by the user.
By default it will create a name from ``sys.argv[0]``, but setting it
explicitly is most likely the better approach.
The ``host`` is set to ``socket.gethostname()``, but can be overridden
by setting ``localname``.
## Fields
message, full_message
The ``full_message`` field is added only to messages with tracebacks.
For example, when using ``logger.exception()`` or setting ``exec_info=1``.
When ``debugging_fields`` is True (default), the following fields are added
as well:
file, function, line, pid, process_name, thread_name
When ``extra_fields`` is set to True, any extra fields on the ``LogRecord``
instance are sent to InfluxDB. Adding extra fields can be achieved by
passing the ``extra`` keyword argument to a logger call or using
``logging.LoggerAdapter``, for example.
my_logger.debug("Login successful.", extra={"username": "John"})
my_logger.info("It is warm.", extra={"temperature": 26.3})
my_logger.warn("Disk Report.", extra={"disk_utilization": 73.4,
"disk_free_space_mb": 63129})
This allows to conveniently add timeseries information that can be
visualized using Grafana.
# Using with Django
It should be easy to integrate ``influxpy`` with Django's logging settings.
# Credits:
* [graypy][1] / Sever Banesiu
[1]: https://github.com/severb/graypy
[2]: https://docs.influxdata.com/influxdb/v1.6/supported_protocols/udp/
[![Coverage Status](https://coveralls.io/repos/github/awelzel/influxpy/badge.svg?branch=master)](https://coveralls.io/github/awelzel/influxpy?branch=master) [![Build Status](https://travis-ci.org/awelzel/influxpy.svg?branch=master)](https://travis-ci.org/awelzel/influxpy)
# About
Python logging handler that sends messages to InfluxDB using the line protocol
with support for UDP and decidedly not HTTP.
The code is heavily inspired by and based on [graypy][1].
# Usage
## Example
import logging
import influxpy
my_logger = logging.getLogger("test_logger")
my_logger.setLevel(logging.DEBUG)
handler = influxpy.UDPHandler("localhost", 8089, "example_logs",
facility="example")
my_logger.addHandler(handler)
my_logger.debug("Hello InfluxDB.")
Tracebacks are added as full messages::
try:
puff_the_magic_dragon()
except NameError:
my_logger.debug("No dragons here.", exc_info=1)
## InfluxDB Configuration
The UDP Input for InfluxDB has to be enabled in order to make use of this
library.
# influxdb.conf:
...
[[udp]]
enabled = true
bind-address = ":8089"
database = "udp"
Also take note of the [InfluxDB UDP documentation][2].
## Configuration parameters
``influxpy.UDPHandler``:
* **host** - The host of the InfluxDB server.
* **port** - The UDP port of the InfluxDB server.
* **debugging_fields** - send debug fields if true (the default).
* **extra_fields** - send extra fields on the log record to InfluxDB if true (the default).
* **fqdn** - Use ``socket.getfqdn()`` instead of ``socket.gethostname()`` to set the source host.
* **localname** - Use the specified hostname as source host.
* **facility** - Set facility. If unspecified, it is naively guessed from ``sys.argv[0]``.
# Schema
## Tags
facility, host, level, level_name, logger
The ``facility`` field, in most cases, should be provided by the user.
By default it will create a name from ``sys.argv[0]``, but setting it
explicitly is most likely the better approach.
The ``host`` is set to ``socket.gethostname()``, but can be overridden
by setting ``localname``.
## Fields
message, full_message
The ``full_message`` field is added only to messages with tracebacks.
For example, when using ``logger.exception()`` or setting ``exec_info=1``.
When ``debugging_fields`` is True (default), the following fields are added
as well:
file, function, line, pid, process_name, thread_name
When ``extra_fields`` is set to True, any extra fields on the ``LogRecord``
instance are sent to InfluxDB. Adding extra fields can be achieved by
passing the ``extra`` keyword argument to a logger call or using
``logging.LoggerAdapter``, for example.
my_logger.debug("Login successful.", extra={"username": "John"})
my_logger.info("It is warm.", extra={"temperature": 26.3})
my_logger.warn("Disk Report.", extra={"disk_utilization": 73.4,
"disk_free_space_mb": 63129})
This allows to conveniently add timeseries information that can be
visualized using Grafana.
# Using with Django
It should be easy to integrate ``influxpy`` with Django's logging settings.
# Credits:
* [graypy][1] / Sever Banesiu
[1]: https://github.com/severb/graypy
[2]: https://docs.influxdata.com/influxdb/v1.6/supported_protocols/udp/
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
influxpy-0.1.1.tar.gz
(5.3 kB
view hashes)