{"id":5440,"library":"python-logstash","title":"Python Logstash","description":"python-logstash is a Python logging handler for Logstash. It allows applications to send log messages to a Logstash instance using UDP, TCP, or AMQP protocols. The library is currently at version 0.4.8 and focuses on providing reliable, direct log forwarding, with updates addressing Python 3 compatibility and bug fixes.","status":"active","version":"0.4.8","language":"en","source_language":"en","source_url":"https://github.com/vklochan/python-logstash","tags":["logging","logstash","elk","log_management","handler","udp","tcp","amqp"],"install":[{"cmd":"pip install python-logstash","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for AMQPLogstashHandler to send logs via AMQP.","package":"pika","optional":true}],"imports":[{"note":"This handler sends logs via UDP by default.","symbol":"LogstashHandler","correct":"from logstash import LogstashHandler"},{"note":"Use this explicitly for TCP transport.","symbol":"TCPLogstashHandler","correct":"from logstash import TCPLogstashHandler"},{"note":"Requires 'pika' package to be installed.","symbol":"AMQPLogstashHandler","correct":"from logstash import AMQPLogstashHandler"}],"quickstart":{"code":"import logging\nimport logstash\nimport sys\nimport os\n\n# Configure Logstash host and port (use environment variables for production)\nLOGSTASH_HOST = os.environ.get('LOGSTASH_HOST', 'localhost')\nLOGSTASH_PORT = int(os.environ.get('LOGSTASH_PORT_UDP', 5959))\n\ntest_logger = logging.getLogger('my_logstash_app')\ntest_logger.setLevel(logging.INFO)\n\n# Add Logstash UDP handler (default behavior)\ntest_logger.addHandler(logstash.LogstashHandler(LOGSTASH_HOST, LOGSTASH_PORT, version=1))\n\n# Optional: Add Logstash TCP handler (uncomment and adjust port as needed)\n# LOGSTASH_TCP_PORT = int(os.environ.get('LOGSTASH_PORT_TCP', 5000))\n# test_logger.addHandler(logstash.TCPLogstashHandler(LOGSTASH_HOST, LOGSTASH_TCP_PORT, version=1))\n\n# Log messages\ntest_logger.info('python-logstash: test logstash info message.')\n\n# Add extra fields to logstash message\nextra_data = {\n    'test_string': 'python version: ' + repr(sys.version_info),\n    'test_boolean': True,\n    'test_dict': {'a': 1, 'b': 'c'},\n    'test_float': 1.23,\n    'test_integer': 123,\n    'test_list': [1, 2, '3'],\n}\ntest_logger.info('python-logstash: test extra fields', extra=extra_data)\n\ntry:\n    1 / 0\nexcept:\n    test_logger.exception('python-logstash-app: Exception with stack trace!')\n\nprint(f\"Logs sent to Logstash at {LOGSTASH_HOST}:{LOGSTASH_PORT} (UDP)\")","lang":"python","description":"This quickstart demonstrates how to configure the Python logging module to send messages to Logstash using the default UDPLogstashHandler. It also shows how to include custom 'extra' fields in your log entries. Remember to set `version=1` for compatibility with modern Logstash versions and ensure your Logstash input is configured for UDP on the specified port."},"warnings":[{"fix":"Use `from logstash import TCPLogstashHandler` and instantiate `TCPLogstashHandler(host, port, version=1)` instead of `LogstashHandler`.","message":"The default `LogstashHandler` uses UDP. If you intend to use TCP for more reliable delivery, you must explicitly use `TCPLogstashHandler`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Refer to Python's `logging.Formatter` documentation for a list of reserved `LogRecord` attribute names. Prefix custom fields (e.g., `my_custom_field`) or group them under a distinct key if conflicts are a concern.","message":"When using `extra` fields in log records, ensure the dictionary keys do not clash with reserved names used by the Python logging system (e.g., `pathname`, `lineno`, `levelname`).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Verify your Logstash configuration file (`logstash.conf`) matches the protocol and port used by the Python handler and includes a `json` codec for parsing the incoming messages. Check Logstash logs for errors.","message":"Logstash itself requires proper configuration (e.g., `udp { port => 5959 codec => json }`) to receive messages. Common issues arise from misconfigured Logstash inputs (wrong port, protocol, or codec).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade to `python-logstash==0.4.8` or newer to ensure correct JSON serialization in Python 3.","message":"Version 0.4.8 fixed Python 3 issues with JSON serialization. Earlier 0.4.x versions might have had broken JSON serialization for Python 3 environments, potentially leading to malformed logs.","severity":"breaking","affected_versions":"<0.4.8 (Python 3 environments)"},{"fix":"If asynchronous logging is desired, install and use `python-logstash-async` (`pip install python-logstash-async`) which provides non-blocking log event submission.","message":"For high-performance or web applications, consider `python-logstash-async` (a fork) if synchronous logging blocking your main thread is an issue. The original `python-logstash` is synchronous.","severity":"gotcha","affected_versions":"All versions of `python-logstash`"},{"fix":"Ensure you are using a recent version of `setuptools` that relies on `build` and `installer` instead of `distutils`. This is usually handled by `pip` automatically with up-to-date environments.","message":"The `distutils` module, used by older setup tools, is deprecated in Python 3.10+ and removed in Python 3.12. While not a direct API change, it can affect installation or packaging processes.","severity":"deprecated","affected_versions":"Python 3.10+"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}