Python logging handlers that send messages in the Graylog Extended Log Format (GELF).
Project description
Description
Python logging handlers that send log messages in the Graylog Extended Log Format (GELF).
graypy supports sending GELF logs to both Graylog2 and Graylog3 servers.
Installing
Using pip
Install the basic graypy python logging handlers:
pip install graypy
Install with requirements for GELFRabbitHandler:
pip install graypy[amqp]
Using easy_install
Install the basic graypy python logging handlers:
easy_install graypy
Install with requirements for GELFRabbitHandler:
easy_install graypy[amqp]
Usage
graypy sends GELF logs to a Graylog server via subclasses of the python logging.Handler class.
Below is the list of ready to run GELF logging handlers defined by graypy:
- GELFUDPHandler - UDP log forwarding
- GELFTCPHandler - TCP log forwarding
- GELFTLSHandler - TCP log forwarding with TLS support
- GELFHTTPHandler - HTTP log forwarding
- GELFRabbitHandler - RabbitMQ log forwarding
UDP Logging
UDP Log forwarding to a locally hosted Graylog server can be easily done with the GELFUDPHandler:
import logging import graypy my_logger = logging.getLogger('test_logger') my_logger.setLevel(logging.DEBUG) handler = graypy.GELFUDPHandler('localhost', 12201) my_logger.addHandler(handler) my_logger.debug('Hello Graylog.')
UDP GELF Chunkers
GELF UDP Chunking is supported by the GELFUDPHandler and is defined by the gelf_chunker argument within its constructor. By default the GELFWarningChunker is used, thus, GELF messages that chunk overflow (i.e. consisting of more than 128 chunks) will issue a GELFChunkOverflowWarning and will be dropped.
Other gelf_chunker options are also available:
- BaseGELFChunker silently drops GELF messages that chunk overflow
- GELFTruncatingChunker issues a GELFChunkOverflowWarning and simplifies and truncates GELF messages that chunk overflow in a attempt to send some content to Graylog. If this process fails to prevent another chunk overflow a GELFTruncationFailureWarning is issued.
RabbitMQ Logging
Alternately, use GELFRabbitHandler to send messages to RabbitMQ and configure your Graylog server to consume messages via AMQP. This prevents log messages from being lost due to dropped UDP packets (GELFUDPHandler sends messages to Graylog using UDP). You will need to configure RabbitMQ with a gelf_log queue and bind it to the logging.gelf exchange so messages are properly routed to a queue that can be consumed by Graylog (the queue and exchange names may be customized to your liking).
import logging import graypy my_logger = logging.getLogger('test_logger') my_logger.setLevel(logging.DEBUG) handler = graypy.GELFRabbitHandler('amqp://guest:guest@localhost/', exchange='logging.gelf') my_logger.addHandler(handler) my_logger.debug('Hello Graylog.')
Django Logging
It’s easy to integrate graypy with Django’s logging settings. Just add a new handler in your settings.py:
LOGGING = { 'version': 1, # other dictConfig keys here... 'handlers': { 'graypy': { 'level': 'WARNING', 'class': 'graypy.GELFUDPHandler', 'host': 'localhost', 'port': 12201, }, }, 'loggers': { 'django.request': { 'handlers': ['graypy'], 'level': 'ERROR', 'propagate': True, }, }, }
Traceback Logging
By default log captured exception tracebacks are added to the GELF log as full_message fields:
import logging import graypy my_logger = logging.getLogger('test_logger') my_logger.setLevel(logging.DEBUG) handler = graypy.GELFUDPHandler('localhost', 12201) my_logger.addHandler(handler) try: puff_the_magic_dragon() except NameError: my_logger.debug('No dragons here.', exc_info=1)
Default Logging Fields
By default a number of debugging logging fields are automatically added to the GELF log if available:
- function
- pid
- process_name
- thread_name
You can disable automatically adding these debugging logging fields by specifying debugging_fields=False in the handler’s constructor:
handler = graypy.GELFUDPHandler('localhost', 12201, debugging_fields=False)
Adding Custom Logging Fields
graypy also supports including custom fields in the GELF logs sent to Graylog. This can be done by using Python’s LoggerAdapter and Filter classes.
Using LoggerAdapter
LoggerAdapter makes it easy to add static information to your GELF log messages:
import logging import graypy my_logger = logging.getLogger('test_logger') my_logger.setLevel(logging.DEBUG) handler = graypy.GELFUDPHandler('localhost', 12201) my_logger.addHandler(handler) my_adapter = logging.LoggerAdapter(logging.getLogger('test_logger'), {'username': 'John'}) my_adapter.debug('Hello Graylog from John.')
Using Filter
Filter gives more flexibility and allows for dynamic information to be added to your GELF logs:
import logging import graypy class UsernameFilter(logging.Filter): def __init__(self): # In an actual use case would dynamically get this # (e.g. from memcache) self.username = 'John' def filter(self, record): record.username = self.username return True my_logger = logging.getLogger('test_logger') my_logger.setLevel(logging.DEBUG) handler = graypy.GELFUDPHandler('localhost', 12201) my_logger.addHandler(handler) my_logger.addFilter(UsernameFilter()) my_logger.debug('Hello Graylog from John.')
Contributors
- Sever Banesiu
- Daniel Miller
- Tushar Makkar
- Nathan Klapstein
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Filename, size | File type | Python version | Upload date | Hashes |
---|---|---|---|---|
Filename, size graypy-2.1.0-py2.py3-none-any.whl (29.9 kB) | File type Wheel | Python version py2.py3 | Upload date | Hashes View |
Filename, size graypy-2.1.0.tar.gz (24.2 kB) | File type Source | Python version None | Upload date | Hashes View |
Hashes for graypy-2.1.0-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5df0102ed52fdaa24dd579bc1e4904480c2c9bbb98917a0b3241ecf510c94207 |
|
MD5 | 2bb0120d4db56496fd631ac0bd08bbaa |
|
BLAKE2-256 | 8280d9de7f4747ab54aad84c479d2c3dad9171de5a7f832ce4229bcef1f472ce |