Registry / observability / loki-logger-handler

loki-logger-handler

library1.1.2pypypiunverified

Loki Logger Handler is a Python logging handler designed for transmitting logs to Grafana Loki. It formats logs in JSON by default, allows custom label definitions, and supports extracting extra keys from log records as labels or structured metadata. The library is currently at version 1.1.2 and appears to be under active development with regular updates addressing compatibility and feature enhancements.

observability http-networking

pip install loki-logger-handler

github ↗package ↗

INSTALL

IMPORT

SIG · LOKI-LOGGER-HANDLE

loki-logger-handler

observabilitypythonv1.1.2

Install

1.5s avg

Import

—

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.1.2 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.000s · 17.9MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 1.5s · import 0.000s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

LokiLoggerHandler

✓ from loki_logger_handler import LokiLoggerHandler

✗ from loki_logger_handler import LokiLoggerHandler

This quickstart demonstrates how to configure the `LokiLoggerHandler` with Python's standard `logging` module. It sets up a handler to send logs to a Loki instance, including static labels and dynamically extracting `extra` dictionary keys as labels. Ensure the `LOKI_URL` environment variable is set or replace the placeholder.

import logging import os from loki_logger_handler.loki_logger_handler import LokiLoggerHandler, LoggerFormatter LOKI_URL = os.environ.get('LOKI_URL', 'http://localhost:3100/loki/api/v1/push') logger = logging.getLogger(__name__) logger.setLevel(logging.INFO) # Configure Loki Handler loki_handler = LokiLoggerHandler( url=LOKI_URL, labels={ 'application': 'my-python-app', 'environment': 'dev' }, # Optionally, specify keys from 'extra' dict to be used as labels label_keys={'user_id', 'request_id'}, # For Loki 3.0+ and structured metadata # enable_structured_loki_metadata=True, # loki_metadata_keys={'metadata_field'} ) # Optionally, use a specific formatter (LoggerFormatter is default for standard logging) loki_handler.setFormatter(LoggerFormatter()) logger.addHandler(loki_handler) # Example logging logger.info('Application started successfully.') logger.warning('Potential issue detected.', extra={'user_id': '12345'}) try: 1 / 0 except ZeroDivisionError: logger.error('A critical error occurred!', exc_info=True, extra={'request_id': 'abc-123'})

Debug

Known issues

breakingOlder versions (pre-1.0.0, especially pre-0.1.3) had Python 2/3 compatibility issues related to file operations (`open` vs `io.open`) and dictionary merging syntax, which could lead to runtime errors on specific Python versions.

fix

Upgrade to version 1.0.0 or higher to ensure broader Python 2/3 compatibility. If sticking to older versions, test thoroughly across target Python environments.

affects: <1.0.0

gotchaThe `auth` attribute for basic authentication was added in version 1.1.1. If you are using an older version and require authenticated access to Loki, this feature will be unavailable.

fix

Upgrade to version 1.1.1 or later to utilize the `auth` parameter for basic authentication credentials.

affects: <1.1.1

gotchaEnabling structured metadata (for Loki 3.0+) requires specific parameters (`enable_structured_loki_metadata`, `loki_metadata`, `loki_metadata_keys`) introduced in version 1.1.0. Using these features with older versions or an incompatible Loki server will not work as expected.

fix

Ensure you are using `loki-logger-handler` version 1.1.0 or newer and have a Loki 3.0+ instance if you intend to send structured metadata.

affects: <1.1.0

gotchaAn `AttributeError` could be raised in version 1.1.1 when `message_in_json_format` was set to `False` due to an incorrect attribute access. This was fixed in 1.1.2.

fix

Upgrade to version 1.1.2 or higher to resolve the `AttributeError` when `message_in_json_format` is `False`.

affects: 1.1.1

gotchaAvoid using high-cardinality values (e.g., `user_id`, `request_id`, dynamic timestamps) directly as Loki labels. This can lead to performance degradation and increased storage costs in Loki itself.

fix

Move high-cardinality fields into the log message body or as structured metadata (if using Loki 3.0+ and the handler supports it) rather than labels. Use labels for broad categories like `application`, `environment`, `service`.

affects: All

Upgrade

Version history

1.1.2latest on PyPI · released May 26, 2025

Audit

Dependencies

requestsrequiredUsed internally for making HTTP POST requests to the Loki API endpoint.

Agent activity

16 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/xente/loki-logger-handler ↗

packagehttps://pypi.org/project/loki-logger-handler/ ↗