Install & Compatibility
Where this runs
tested against v0.4.80 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.050s · 17.8MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.5s · import 0.046s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
LogstashHandler
✓ from logstash import LogstashHandler
TCPLogstashHandler
✓ from logstash import TCPLogstashHandler
AMQPLogstashHandler
✓ from logstash import AMQPLogstashHandler
Requires 'pika' package to be installed.
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!')
Debug
Known issues
gotchaAvoid 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.fixReview the Python logging `Formatter` documentation to understand reserved keys and choose unique names for custom fields.
affects: All versions
breakingThe `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`.fixConsider migrating to `python-logstash` or, for asynchronous logging and more features, `python-logstash-async`.
affects: All versions (due to lack of future maintenance)
gotchaThis 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.fixFor non-blocking, asynchronous log sending, consider using `python-logstash-async`, which is designed for this purpose.
affects: All versions
gotchaThe `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.fixAlways explicitly set `version=1` in your handler configuration unless you have a specific need for an older schema.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'logstash'
The 'python3-logstash' package is not installed in the current Python environment.
fixpip install python3-logstash
AttributeError: module 'logstash' has no attribute 'LogstashHandler'
The 'python3-logstash' library provides specific handlers like 'LogstashUDPHandler' and 'LogstashTCPHandler', but not a generic 'LogstashHandler', which was present in the older 'python-logstash' library.
fixUse 'LogstashUDPHandler' or 'LogstashTCPHandler' instead, for example: 'from logstash import LogstashUDPHandler'.
ConnectionRefusedError: [Errno 111] Connection refused
The Logstash server is not running, is not listening on the specified host and port, or a network firewall is blocking the connection.
fixVerify that the Logstash server is running, configured to listen on the correct host and port, and that network access is permitted from the Python application.
UnicodeEncodeError: 'latin-1' codec can't encode character
Attempting to send log messages containing characters that cannot be represented by the chosen encoding (e.g., non-latin-1 characters when 'latin-1' encoding is implicitly or explicitly used in the logging pipeline).
fixEnsure consistent UTF-8 encoding throughout the logging pipeline, from the Python application to the Logstash server, and configure the handler to use UTF-8 explicitly if needed (though it's the default).
Upgrade
Version history
0.4.80latest on PyPI · released Jul 12, 2018
Audit
Dependencies
pikaoptionalRequired for using the AMQPLogstashHandler to send logs via AMQP.