{"id":4386,"library":"python-logging-loki","title":"Python Logging Loki Handler","description":"The `python-logging-loki` library provides a handler for Python's standard `logging` module, allowing applications to send logs directly to Grafana Loki. It includes `LokiHandler` for synchronous logging and `LokiQueueHandler` for asynchronous, non-blocking log submission. The library supports custom labels, basic HTTP authentication, and explicit Loki API versioning. The current stable version is 0.3.1.","status":"active","version":"0.3.1","language":"en","source_language":"en","source_url":"https://github.com/greyzmeem/python-logging-loki","tags":["logging","loki","grafana","observability","logs","metrics"],"install":[{"cmd":"pip install python-logging-loki","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Requires Python 3.6 or newer.","package":"python","optional":false}],"imports":[{"note":"The primary synchronous logging handler.","symbol":"LokiHandler","correct":"from logging_loki import LokiHandler"},{"note":"A non-blocking handler for high-throughput applications, often preferred in production. It uses `multiprocessing.Queue` internally.","symbol":"LokiQueueHandler","correct":"from logging_loki import LokiQueueHandler"}],"quickstart":{"code":"import logging\nimport os\nfrom logging_loki import LokiHandler\n\n# Configure Loki URL and optional authentication\nLOKI_URL = os.environ.get('LOKI_URL', 'http://localhost:3100/loki/api/v1/push')\nLOKI_USERNAME = os.environ.get('LOKI_USERNAME', '')\nLOKI_PASSWORD = os.environ.get('LOKI_PASSWORD', '')\n\n# Create a Loki handler\nhandler_kwargs = {\n    'url': LOKI_URL,\n    'tags': {'app': 'my-python-app', 'environment': 'development'},\n    'version': '1' # Use '1' for Loki >= 0.4.0\n}\n\nif LOKI_USERNAME and LOKI_PASSWORD:\n    handler_kwargs['auth'] = (LOKI_USERNAME, LOKI_PASSWORD)\n\nhandler = LokiHandler(**handler_kwargs)\n\n# Get a logger and add the Loki handler\nlogger = logging.getLogger('my-app')\nlogger.setLevel(logging.INFO)\nlogger.addHandler(handler)\n\n# Log a message\nlogger.info('Hello, Loki! This is an info message.')\nlogger.warning('This is a warning message with extra data.', extra={'tags': {'component': 'auth'}})\n\nprint(f\"Logs sent to Loki at {LOKI_URL}\")","lang":"python","description":"This quickstart demonstrates how to configure a `LokiHandler` to send logs to a Loki instance. It includes setting the Loki URL, adding default and extra tags, and handling optional basic authentication using environment variables. It explicitly sets the Loki API version to '1' for compatibility with modern Loki deployments."},"warnings":[{"fix":"Upgrade Python to 3.6+ if using an older version of the library or remain on an older library version if Python 3.5 is strictly required.","message":"Version 0.3.0 dropped official support for Python 3.5. Ensure your environment uses Python 3.6 or newer.","severity":"breaking","affected_versions":"<0.3.0"},{"fix":"Always explicitly set the `version` parameter in `LokiHandler` or `LokiQueueHandler` to '1' (recommended for modern Loki) or '0' to match your Loki instance's API.","message":"The default Loki API version used by the handler has changed over time. Loki 0.4.0 and newer typically require API version '1' for the `/loki/api/v1/push` endpoint. Older Loki versions might expect API version '0' at `/api/prom/push`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"When defining `tags` or `extra={'tags': ...}`, use underscores (`_`) instead of hyphens for label keys to ensure Loki processes them correctly. For example, use `my_app_tag` instead of `my-app-tag`.","message":"Using hyphens (`-`) in Loki label keys can cause Loki to return internal server errors during ingestion.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For production or performance-critical applications, use `LokiQueueHandler` which processes logs asynchronously in a separate thread, preventing the main application thread from blocking.","message":"The `LokiHandler` is blocking, meaning each log call waits for the HTTP request to Loki to complete. In high-throughput applications, this can negatively impact performance.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Evaluate if the current feature set meets your needs. Consider contributing to the project or forking it if specific new features or bug fixes are required. Be aware that community alternatives like `python-loki-logger` (unrelated project) exist with more recent activity.","message":"The `python-logging-loki` library, while functional, has not seen a new release since November 2019 (v0.3.1). This means it may not incorporate the latest Loki features or recent bug fixes, and maintenance might be limited.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}