pylogbeat

library2.1.0pypypi✓ verified 25d ago

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.

communication http-networking

pip install pylogbeat

github ↗package ↗

INSTALL

IMPORT

SIG · PYLOGBEAT

pylogbeat

communicationpythonv2.1.0

Install

1.5s avg

Import

49ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.0.1 · 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

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.050s · 17.8MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.5s · import 0.048s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

PyLogBeatClient

✓ from pylogbeat import PyLogBeatClient

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}")

Debug

Known issues

breakingVersion 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).

affects: >=2.1.0

breakingThe `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`.

affects: >=2.0.0

gotchaDue 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.

affects: *

gotchaThe `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.

affects: *

gotchaThe 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.

affects: *

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'pylogbeat'

The 'pylogbeat' library is not installed in the Python environment, or the import statement is incorrect.

fix

Install the library using pip: `pip install pylogbeat`

ConnectionRefusedError: [Errno 111] Connection refused

The PyLogBeatClient could not establish a connection to the specified host and port, often because the Logstash or Beats server is not running, is configured on a different address/port, or a firewall is blocking the connection.

fix

Ensure the Beats protocol listener (e.g., Logstash Beats input plugin) is running and accessible on the specified host and port, and check any firewall rules on both client and server machines.

socket.timeout: timed out

The PyLogBeatClient successfully connected but the server did not respond within the configured timeout period, often due to network latency, a slow server, or the server crashing after connection.

fix

Increase the `timeout` value in the `PyLogBeatClient` constructor, verify network connectivity, and check the health and responsiveness of the Logstash or Beats server.

SyntaxError: future feature annotations is not allowed in this Python version

The installed 'pylogbeat' version (2.1.0 or newer) is incompatible with the Python interpreter being used, as it requires Python 3.11 or newer.

fix

Upgrade your Python environment to version 3.11 or newer, or downgrade 'pylogbeat' to a compatible version (e.g., `pip install pylogbeat<2.1.0` for Python 3.6-3.10).

TypeError: 'str' object has no attribute 'get' (or similar AttributeError/TypeError when sending a dict directly)

The `PyLogBeatClient.send()` method expects an iterable (like a list) containing message dictionaries or JSON strings, but a single dictionary object was passed directly, causing the library to iterate over its keys (strings) instead of its items.

fix

Wrap the single message dictionary in a list when calling `client.send()`: `client.send([message_dict])`

Upgrade

Version history

2.1.0latest on PyPI · released Nov 23, 2025

Audit

Dependencies

No dependency data recorded yet.

Agent activity

16 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/eht16/pylogbeat ↗

packagehttps://pypi.org/project/pylogbeat/ ↗