Skip to content
Python logging handler for Graylog that sends messages in GELF (Graylog Extended Log Format).
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
graypy
tests fixing `test_resolve_host` test logic to reflect `BaseGELFHandler._re… Jul 15, 2019
.gitignore updating CI script Nov 10, 2018
.pylintrc adding pylintrc Sep 26, 2018
.travis.yml Bugfix/PyPi readme render failure (#104) Mar 19, 2019
LICENSE More relaxed license. Nov 9, 2011
MANIFEST.in throwing in unset tests Nov 15, 2018
README.rst
perftest.py updating shebangs Mar 13, 2019
setup.cfg
setup.py Bugfix/PyPi readme render failure (#104) Mar 19, 2019

README.rst

PyPI_Status Build_Status Coverage_Status

Description

Python logging handlers that send messages in the Graylog Extended Log Format (GELF).

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

Messages are sent to Graylog2 using a custom handler for the builtin logging library in GELF format

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 Graylog2.')

Alternately, use GELFRabbitHandler to send messages to RabbitMQ and configure your Graylog2 server to consume messages via AMQP. This prevents log messages from being lost due to dropped UDP packets (GELFUDPHandler sends messages to Graylog2 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 Graylog2 (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 Graylog2.')

Tracebacks are added as full 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)

try:
    puff_the_magic_dragon()
except NameError:
    my_logger.debug('No dragons here.', exc_info=1)

For more detailed usage information please see the documentation provided within graypy's handler's docstrings.

Using with Django

It's easy to integrate graypy with Django's logging settings. Just add a new handler in your settings.py:

LOGGING = {
    ...

    'handlers': {
        'graypy': {
            'level': 'WARNING',
            'class': 'graypy.GELFUDPHandler',
            'host': 'localhost',
            'port': 12201,
        },
    },

    'loggers': {
        'django.request': {
            'handlers': ['graypy'],
            'level': 'ERROR',
            'propagate': True,
        },
    },
}

Custom fields

A number of custom fields are automatically added if available:
  • function
  • pid
  • process_name
  • thread_name

You can disable these additional fields if you don't want them by adding an the debugging_fields=False to the handler:

handler = graypy.GELFUDPHandler('localhost', 12201, debugging_fields=False)

graypy also supports additional fields to be included in the messages sent to Graylog2. This can be done by using Python's LoggerAdapter and Filter. In general, LoggerAdapter makes it easy to add static information to your log messages and Filters give you more flexibility, for example to add additional information based on the message that is being logged.

Example using LoggerAdapter

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 Graylog2 from John.')

Example using Filter

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 Graylog2 from John.')

Contributors:

  • Sever Banesiu
  • Daniel Miller
  • Tushar Makkar
  • Nathan Klapstein
You can’t perform that action at this time.