Python-logstash-async is an asynchronous Python logging handler designed to send log events to a remote Logstash instance. It processes log events in a separate worker thread to avoid blocking the main application, crucial for performance-sensitive applications like web services. It supports TCP, UDP, and Beats protocols, with optional SSL for TCP, and can persist unsent logs to a SQLite database. The library is actively maintained with regular releases addressing bug fixes and introducing new features.
pip install python-logstash-asyncVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to configure `python-logstash-async` with `AsynchronousLogstashHandler` and `LogstashFormatter`. It sets up a logger to send INFO, WARNING, and ERROR messages to a Logstash instance, including extra fields. A `database_path` is specified for persistent storage of events in case Logstash is unreachable or the application restarts. The example also includes a console handler for immediate feedback during development.
Upgrade to Python 3.11 or newer, or stick to `python-logstash-async` versions < 4.0.0.
Always provide a `database_path` argument to `AsynchronousLogstashHandler` to enable event persistence to a SQLite database. For example: `database_path='logstash_events.db'`.
For multiple handlers in a single process, configure them to use the *same* `database_path`. Avoid using `AsynchronousLogstashHandler` directly in multi-process scenarios where logs need to be flushed from each child process independently; consider using `logging.QueueHandler` with a `QueueListener` in the parent process or writing to files and using a tool like Filebeat for robust multi-process logging.
Upgrade to version 4.0.2 or newer to benefit from fixes addressing socket handling and preventing hangs during network errors.
Refer to Python's `logging.Formatter` documentation for a list of reserved attributes. Use a `extra_prefix` in `LogstashFormatter` to avoid conflicts (e.g., `extra_prefix='my_app_data'`).
Ensure the library is installed with `pip install python-logstash-async` and use the correct import: `from logstash_async.handler import AsynchronousLogstashHandler`.
Verify that the Logstash instance is running and listening on the specified host and port, and check network connectivity between the client and server.
Ensure `ssl_enable=True` and provide the correct `ssl_ca_certs` parameter pointing to the trusted CA certificate bundle when initializing `AsynchronousLogstashHandler`.
Ensure the `port` parameter is set to an integer representing the Logstash input port, e.g., `port=5000`.