---
id: loki-logger-handler
version: "1.1.2"
license: MIT
license_treatment: permissive
maintenance: aging
---

# loki-logger-handler — Handler designed for transmitting logs to Grafana Loki in JSON format.

License: permissive · Maintenance: aging · Downloads: 122.7K/mo

## What it is and what it does

loki-logger-handler is a Python logging handler that bridges the standard logging module (and optionally loguru) to Grafana Loki, a log aggregation system. It formats log messages as JSON, attaches custom labels for filtering and querying, and sends them to a Loki server in batches, optionally compressed. The handler automatically includes log metadata like timestamps, process IDs, thread IDs, and function names; you can also attach custom fields via logging extras, which become searchable keys in the JSON payload.

The package supports both Python's built-in logging and the loguru library, with separate formatters for each. It includes options for basic authentication, custom headers, configurable timeouts, and Loki 3.0 structured metadata. Logs are buffered and flushed either when the buffer fills or after a timeout, reducing network overhead. The handler runs as a background thread, so it does not block your application.

Use it for:

- Centralize application logs from multiple Python services into a single Loki instance for unified querying and monitoring.
- Add structured metadata (user IDs, trace IDs, request codes) to logs for filtering and correlation in Grafana dashboards.
- Replace file-based logging with cloud-native log aggregation in containerized or serverless deployments.
- Batch and compress logs before sending to reduce network bandwidth and Loki ingestion costs.
- Integrate loguru-based applications with Loki without rewriting logging code.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

A logging handler that sends Python log messages to Grafana Loki in JSON format, with support for custom labels, batch publishing, and compression.

Yes, if you are already running Grafana Loki and need a straightforward Python logging integration. The package has no runtime dependencies, low install friction, and a permissive license. However, note that maintenance is aging (last update 2025-05-26, last commit 2026-01-09); if you require active support or plan to use Loki 3.0 structured metadata in production, verify compatibility first or be prepared to maintain a fork.

## Install

pip install loki-logger-handler
uv add loki-logger-handler
poetry add loki-logger-handler

## Installing loki-logger-handler

Before you install: Low install friction with no runtime dependencies. Maintenance status is aging—last commit was 2026-01-09 and the package has not been updated since 2025-05-26, so expect slower response to issues or feature requests.

License in practice: MIT license is permissive; you can use this package freely in commercial and private projects with minimal restrictions.

Quickstart:

pip install loki-logger-handler

from loki_logger_handler.loki_logger_handler import LokiLoggerHandler
import logging
import os

logger = logging.getLogger("app")
logger.setLevel(logging.DEBUG)
handler = LokiLoggerHandler(
    url=os.environ["LOKI_URL"],
    labels={"application": "MyApp"},
    timeout=10,
)
logger.addHandler(handler)
logger.info("Test message")

Requires a Grafana Loki server endpoint URL, typically provided via environment variable LOKI_URL in the format https://user:password@host/loki/api/v1/push.

Verify before relying:

- Whether loguru integration works reliably with all loguru versions and configurations.
- Performance characteristics when sending high-volume logs or with large batch sizes.
- Compatibility with Loki 3.0 structured metadata features in production environments.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: aging
- Downloads: 122.7K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

grafana loki logging handler, send logs to loki, python logging to loki, loki json log handler, grafana loki integration, structured logging loki, log aggregation handler, logging, grafana-loki, log-aggregation

[View on SkillFed](https://skillfed.io/packages/loki-logger-handler) · [View on PyPI](https://pypi.org/project/loki-logger-handler/)