GELF Logging Handler

0.4.3 · active · verified Thu Apr 16

pygelf provides logging handlers for the GELF (Graylog Extended Log Format) specification, allowing Python applications to send logs to Graylog servers or other GELF-compatible log management systems. It supports UDP, TCP, and HTTP transport protocols, including features like compression and chunking for large messages. The current version is 0.4.3, and it receives active maintenance with a moderate release cadence.

Common errors

```
socket.error: [Errno 111] Connection refused
```
cause The Graylog server is not running or not listening on the specified host/port, or a firewall is blocking the connection.

fix Verify that your Graylog instance is running, the GELF input is active and configured correctly, and the network path between your application and Graylog is open. Check firewall rules.
```
Log messages are not appearing in Graylog.
```
cause Common reasons include incorrect host/port, firewall blocks, or Graylog input misconfiguration (e.g., expecting TCP but receiving UDP).

fix Double-check the `host` and `port` in your `GELFHandler` configuration. Ensure the Graylog GELF input matches the handler type (UDP, TCP, HTTP) and is listening on the correct network interface.
```
TypeError: Object of type <YourCustomClass> is not JSON serializable
```
cause You are attempting to log an object in an `extra` field that cannot be directly converted to JSON by pygelf.

fix Ensure all values in `extra` fields are JSON-serializable (strings, numbers, booleans, lists, dicts). Convert custom objects to their string representation or a serializable dictionary before logging, e.g., `str(your_object)` or `your_object.__dict__`.

Warnings

gotcha Ensure you are using the correct GELF handler (UDP, TCP, or HTTP) and that the `host` and `port` parameters match your Graylog input configuration.
Fix: Verify your Graylog input type and its listening address/port. For UDP, the default port is 12201; for TCP, it's 12202; for HTTP, it's typically 12201 (HTTP GELF input) on a dedicated Graylog HTTP input.
gotcha Very large log messages (e.g., stack traces, large JSON payloads) might exceed UDP packet limits or be rejected by Graylog if not properly compressed or chunked.
Fix: Set `compress=True` (defaults to `zlib`) on your handler. pygelf handles chunking automatically for UDP, but compression helps reduce the number of chunks and total payload size, improving reliability for large messages.
gotcha Custom `extra` fields passed to `logger.info(..., extra={'key': 'value'})` are not included in the GELF message by default.
Fix: Add `include_extra_fields=True` to your GELF handler initialization, e.g., `GELFUDPHandler(host=..., include_extra_fields=True)` to ensure these fields are sent.

Install

pip install pygelf Install pygelf

Imports

GELFUDPHandler
```
from pygelf import GELFUDPHandler
```
GELFTCPHandler
```
from pygelf import GELFTCPHandler
```
GELFHTTPHandler
```
from pygelf import GELFHTTPHandler
```

Quickstart

This quickstart demonstrates how to configure a Python logger with `GELFUDPHandler` to send log messages to a Graylog instance. It shows basic info, warning, and exception logging, including how to pass extra fields to GELF. Remember to replace placeholder host/port or set them via environment variables to match your Graylog setup.

import logging
import os
from pygelf import GELFUDPHandler

# Replace with your Graylog host and port, or set as environment variables
GRAYLOG_HOST = os.environ.get('GRAYLOG_HOST', '127.0.0.1')
GRAYLOG_PORT = int(os.environ.get('GRAYLOG_PORT', '12201')) # Default GELF UDP port

logger = logging.getLogger('my_app')
logger.setLevel(logging.INFO)

# Configure GELF UDP handler
handler = GELFUDPHandler(
    host=GRAYLOG_HOST,
    port=GRAYLOG_PORT,
    _source_host='my_python_app', # Custom field example
    include_extra_fields=True # Include extra dict fields in log record
)
logger.addHandler(handler)

# Example log messages
logger.info("This is an informational message.")
logger.warning("A warning occurred!", extra={'user_id': 123, 'transaction_id': 'abc-xyz'})
try:
    1 / 0
except ZeroDivisionError:
    logger.exception("An error occurred during division.")

print(f"Logs sent to {GRAYLOG_HOST}:{GRAYLOG_PORT}. Check your Graylog instance.")

view raw JSON →