Python3 Logstash Logging Handler

0.4.80 · abandoned · verified Sun Apr 12

The `python3-logstash` library, version `0.4.80`, provides Python logging handlers for sending messages to a Logstash server over UDP or TCP. Originally created as a Python 3 fork of the `python-logstash` library, this specific package was last updated in July 2018. Due to its lack of recent updates, it appears to be unmaintained. For actively maintained alternatives with asynchronous capabilities, users often consider `python-logstash-async`.

Warnings

gotcha Avoid using reserved logging system keys (e.g., `message`, `asctime`, `levelname`) in the `extra` dictionary passed to log methods. This can cause conflicts or unexpected behavior, as these keys are used internally by the Python logging system.
Fix: Review the Python logging `Formatter` documentation to understand reserved keys and choose unique names for custom fields.
breaking The `python3-logstash` library is a fork that has not been updated since July 2018 (v0.4.80). The original `python-logstash` (v0.4.8) received updates in March 2022. This means `python3-logstash` likely lacks bug fixes and features present in its upstream or in more actively maintained alternatives like `python-logstash-async`.
Fix: Consider migrating to `python-logstash` or, for asynchronous logging and more features, `python-logstash-async`.
gotcha This library uses synchronous network calls for sending logs, which can block the main application thread if Logstash is unavailable or experiences high latency. For applications where logging performance is critical (e.g., web servers), this can introduce significant overhead.
Fix: For non-blocking, asynchronous log sending, consider using `python-logstash-async`, which is designed for this purpose.
gotcha The `version` parameter in `LogstashHandler` and `TCPLogstashHandler` refers to the Logstash event schema version. While the default is `0` for backward compatibility, `version=1` is recommended for Logstash 1.2.x and later for a modern JSON schema.
Fix: Always explicitly set `version=1` in your handler configuration unless you have a specific need for an older schema.

Install

pip install python3-logstash Install latest version

Imports

LogstashHandler
```
from logstash import LogstashHandler
```
TCPLogstashHandler
```
from logstash import TCPLogstashHandler
```
AMQPLogstashHandler
```
from logstash import AMQPLogstashHandler
```
Requires 'pika' package to be installed.

Quickstart

This quickstart demonstrates how to configure a logger with `LogstashHandler` (UDP) or `TCPLogstashHandler` to send messages to a Logstash instance. It includes examples for different log levels and adding custom `extra` fields. Ensure environment variables `LOGSTASH_HOST` and `LOGSTASH_PORT` are set, or it will default to `localhost:5959`.

import logging
import logstash
import sys
import os

host = os.environ.get('LOGSTASH_HOST', 'localhost')
port = int(os.environ.get('LOGSTASH_PORT', '5959'))

test_logger = logging.getLogger('python-logstash-logger')
test_logger.setLevel(logging.INFO)

# Example for UDP handler
test_logger.addHandler(logstash.LogstashHandler(host, port, version=1))

# Example for TCP handler (uncomment to use)
# test_logger.addHandler(logstash.TCPLogstashHandler(host, port, version=1))

test_logger.error('python-logstash: test logstash error message.')
test_logger.info('python-logstash: test logstash info message.')
test_logger.warning('python-logstash: test logstash warning message.')

# Add extra fields to logstash message
extra = {
    'test_string': 'python version: ' + repr(sys.version_info),
    'test_boolean': True,
    'test_dict': {'a': 1, 'b': 'c'},
    'test_float': 1.23,
    'test_integer': 123,
    'test_list': [1, 2, '3'],
}
test_logger.info('python-logstash: test extra fields', extra=extra)

try:
    1 / 0
except ZeroDivisionError:
    test_logger.exception('python-logstash-logger: Exception with stack trace!')

view raw JSON →