{"id":7561,"library":"pygelf","title":"GELF Logging Handler","description":"pygelf provides logging handlers for the GELF (Graylog Extended Log Format) specification, allowing Python applications to send logs to Graylog servers or other GELF-compatible log management systems. It supports UDP, TCP, and HTTP transport protocols, including features like compression and chunking for large messages. The current version is 0.4.3, and it receives active maintenance with a moderate release cadence.","status":"active","version":"0.4.3","language":"en","source_language":"en","source_url":"https://github.com/keeprocking/pygelf","tags":["logging","gelf","graylog","log-management"],"install":[{"cmd":"pip install pygelf","lang":"bash","label":"Install pygelf"}],"dependencies":[],"imports":[{"symbol":"GELFUDPHandler","correct":"from pygelf import GELFUDPHandler"},{"symbol":"GELFTCPHandler","correct":"from pygelf import GELFTCPHandler"},{"symbol":"GELFHTTPHandler","correct":"from pygelf import GELFHTTPHandler"}],"quickstart":{"code":"import logging\nimport os\nfrom pygelf import GELFUDPHandler\n\n# Replace with your Graylog host and port, or set as environment variables\nGRAYLOG_HOST = os.environ.get('GRAYLOG_HOST', '127.0.0.1')\nGRAYLOG_PORT = int(os.environ.get('GRAYLOG_PORT', '12201')) # Default GELF UDP port\n\nlogger = logging.getLogger('my_app')\nlogger.setLevel(logging.INFO)\n\n# Configure GELF UDP handler\nhandler = GELFUDPHandler(\n    host=GRAYLOG_HOST,\n    port=GRAYLOG_PORT,\n    _source_host='my_python_app', # Custom field example\n    include_extra_fields=True # Include extra dict fields in log record\n)\nlogger.addHandler(handler)\n\n# Example log messages\nlogger.info(\"This is an informational message.\")\nlogger.warning(\"A warning occurred!\", extra={'user_id': 123, 'transaction_id': 'abc-xyz'})\ntry:\n    1 / 0\nexcept ZeroDivisionError:\n    logger.exception(\"An error occurred during division.\")\n\nprint(f\"Logs sent to {GRAYLOG_HOST}:{GRAYLOG_PORT}. Check your Graylog instance.\")\n","lang":"python","description":"This quickstart demonstrates how to configure a Python logger with `GELFUDPHandler` to send log messages to a Graylog instance. It shows basic info, warning, and exception logging, including how to pass extra fields to GELF. Remember to replace placeholder host/port or set them via environment variables to match your Graylog setup."},"warnings":[{"fix":"Verify your Graylog input type and its listening address/port. For UDP, the default port is 12201; for TCP, it's 12202; for HTTP, it's typically 12201 (HTTP GELF input) on a dedicated Graylog HTTP input.","message":"Ensure you are using the correct GELF handler (UDP, TCP, or HTTP) and that the `host` and `port` parameters match your Graylog input configuration.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Set `compress=True` (defaults to `zlib`) on your handler. pygelf handles chunking automatically for UDP, but compression helps reduce the number of chunks and total payload size, improving reliability for large messages.","message":"Very large log messages (e.g., stack traces, large JSON payloads) might exceed UDP packet limits or be rejected by Graylog if not properly compressed or chunked.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Add `include_extra_fields=True` to your GELF handler initialization, e.g., `GELFUDPHandler(host=..., include_extra_fields=True)` to ensure these fields are sent.","message":"Custom `extra` fields passed to `logger.info(..., extra={'key': 'value'})` are not included in the GELF message by default.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Verify that your Graylog instance is running, the GELF input is active and configured correctly, and the network path between your application and Graylog is open. Check firewall rules.","cause":"The Graylog server is not running or not listening on the specified host/port, or a firewall is blocking the connection.","error":"socket.error: [Errno 111] Connection refused"},{"fix":"Double-check the `host` and `port` in your `GELFHandler` configuration. Ensure the Graylog GELF input matches the handler type (UDP, TCP, HTTP) and is listening on the correct network interface.","cause":"Common reasons include incorrect host/port, firewall blocks, or Graylog input misconfiguration (e.g., expecting TCP but receiving UDP).","error":"Log messages are not appearing in Graylog."},{"fix":"Ensure all values in `extra` fields are JSON-serializable (strings, numbers, booleans, lists, dicts). Convert custom objects to their string representation or a serializable dictionary before logging, e.g., `str(your_object)` or `your_object.__dict__`.","cause":"You are attempting to log an object in an `extra` field that cannot be directly converted to JSON by pygelf.","error":"TypeError: Object of type <YourCustomClass> is not JSON serializable"}]}