Pylogbeat

2.1.0 · active · verified Sun Apr 12

PyLogBeat is a simple, incomplete implementation of the Beats protocol used by Elastic Beats and Logstash. It enables reliable data transfer by having the server acknowledge received data, allowing the client to know whether and what to resend. The library is actively maintained, with a recent major release (2.1.0) in late 2025, and continues to support modern Python environments.

Warnings

breaking Version 2.1.0 dropped support for Python versions older than 3.11. If you are on an older Python version, you must upgrade Python or stick to `pylogbeat < 2.1.0`.
Fix: Upgrade Python to 3.11 or newer, or pin `pylogbeat` to a version compatible with your Python environment (e.g., `<2.0.0` for Python 2.x, `<2.1.0` for Python 3.6-3.10).
breaking The `six` compatibility library dependency was removed in version 2.0.0. This makes `pylogbeat` a Python 3-only library from this version onwards.
Fix: Ensure your project is running on Python 3 and that any dependencies on `six` are handled elsewhere if necessary. If still on Python 2, use `pylogbeat < 2.0.0`.
gotcha Due to a known bug (logstash-plugins/logstash-input-beats#342), Logstash requires specific versions to correctly receive data from `pylogbeat`.
Fix: Ensure your Logstash instance is version `5.6.12` or higher, or `6.4.0` or higher.
gotcha The `PyLogBeatClient` constructor's `use_logging` argument defaults to `False`. If `pylogbeat` is used as part of your logging system, setting `use_logging=True` might lead to recursive logging issues during shutdown.
Fix: Set `use_logging=False` if `pylogbeat` is acting as a transport for a logging handler to prevent infinite logging loops or issues during logging subsystem shutdown.
gotcha The implemented Beats protocol in `pylogbeat` is described as 'incomplete' as the protocol itself is not yet officially specified. While core functionality like sending data and awaiting ACK is present, some details might be missing.
Fix: Be aware that not all advanced or edge-case features of the Beats protocol might be fully supported. Test thoroughly if your use case relies on complex Beats protocol behaviors.

Install

pip install pylogbeat Install latest version

Imports

PyLogBeatClient
```
from pylogbeat import PyLogBeatClient
```

Quickstart

This quickstart demonstrates how to send a single log message to a Logstash or Beats input plugin using `PyLogBeatClient`. It utilizes a context manager for automatic connection and disconnection, and shows a basic message structure. Remember to set `LOGSTASH_HOST` and `LOGSTASH_PORT` environment variables or update the default values.

import os
from datetime import datetime
from pylogbeat import PyLogBeatClient

# Configure connection details (replace with your Logstash/Beats input host and port)
HOST = os.environ.get('LOGSTASH_HOST', 'localhost')
PORT = int(os.environ.get('LOGSTASH_PORT', 5959))

# Example message in Logstash format
message = {
    '@timestamp': datetime.utcnow().strftime('%Y-%m-%dT%H:%M:%S.%fZ'),
    '@version': '1',
    'message': 'hello world from pylogbeat',
    'level': 'INFO',
    'host': 'my-python-app'
}

try:
    with PyLogBeatClient(HOST, PORT, ssl_enable=False) as client:
        client.send([message])
        print(f"Sent message to {HOST}:{PORT}")
except Exception as e:
    print(f"Failed to send message: {e}")

view raw JSON →