{"id":4707,"library":"pylogbeat","title":"Pylogbeat","description":"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.","status":"active","version":"2.1.0","language":"python","source_language":"en","source_url":"https://github.com/eht16/pylogbeat/","tags":["logging","logstash","beats","elastic","protocol","observability"],"install":[{"cmd":"pip install pylogbeat","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"symbol":"PyLogBeatClient","correct":"from pylogbeat import PyLogBeatClient"}],"quickstart":{"code":"import os\nfrom datetime import datetime\nfrom pylogbeat import PyLogBeatClient\n\n# Configure connection details (replace with your Logstash/Beats input host and port)\nHOST = os.environ.get('LOGSTASH_HOST', 'localhost')\nPORT = int(os.environ.get('LOGSTASH_PORT', 5959))\n\n# Example message in Logstash format\nmessage = {\n    '@timestamp': datetime.utcnow().strftime('%Y-%m-%dT%H:%M:%S.%fZ'),\n    '@version': '1',\n    'message': 'hello world from pylogbeat',\n    'level': 'INFO',\n    'host': 'my-python-app'\n}\n\ntry:\n    with PyLogBeatClient(HOST, PORT, ssl_enable=False) as client:\n        client.send([message])\n        print(f\"Sent message to {HOST}:{PORT}\")\nexcept Exception as e:\n    print(f\"Failed to send message: {e}\")","lang":"python","description":"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."},"warnings":[{"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).","message":"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`.","severity":"breaking","affected_versions":">=2.1.0"},{"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`.","message":"The `six` compatibility library dependency was removed in version 2.0.0. This makes `pylogbeat` a Python 3-only library from this version onwards.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure your Logstash instance is version `5.6.12` or higher, or `6.4.0` or higher.","message":"Due to a known bug (logstash-plugins/logstash-input-beats#342), Logstash requires specific versions to correctly receive data from `pylogbeat`.","severity":"gotcha","affected_versions":"*"},{"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.","message":"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.","severity":"gotcha","affected_versions":"*"},{"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.","message":"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.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"search_vec":"'2.1.0':50 '2025':53 'acknowledg':27 'activ':43 'allow':30 'beat':10,15,63 'client':32 'continu':55 'data':21,29 'elast':14,64 'enabl':19 'environ':60 'implement':7 'incomplet':6 'know':34 'late':52 'librari':41 'log':61 'logstash':17,62 'maintain':44 'major':48 'modern':58 'observ':66 'protocol':11,65 'pylogbeat':1,2 'python':59 'receiv':28 'recent':47 'releas':49 'reliabl':20 'resend':39 'server':26 'simpl':5 'support':57 'transfer':22 'use':12 'whether':35","created_at":"2026-04-12T14:04:10.705136+00:00","updated_at":"2026-04-16T18:32:07.077100+00:00","problems":[{"fix":"Install the library using pip: `pip install pylogbeat`","cause":"The 'pylogbeat' library is not installed in the Python environment, or the import statement is incorrect.","error":"ModuleNotFoundError: No module named 'pylogbeat'"},{"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.","cause":"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.","error":"ConnectionRefusedError: [Errno 111] Connection refused"},{"fix":"Increase the `timeout` value in the `PyLogBeatClient` constructor, verify network connectivity, and check the health and responsiveness of the Logstash or Beats server.","cause":"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.","error":"socket.timeout: timed out"},{"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).","cause":"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.","error":"SyntaxError: future feature annotations is not allowed in this Python version"},{"fix":"Wrap the single message dictionary in a list when calling `client.send()`: `client.send([message_dict])`","cause":"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.","error":"TypeError: 'str' object has no attribute 'get' (or similar AttributeError/TypeError when sending a dict directly)"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"2.1.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/eht16/pylogbeat","docs":null,"changelog":null,"pypi":"https://pypi.org/project/pylogbeat/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["communication","http-networking"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-30","next_check":"2026-07-28","install_tag":null}}