🚀 tjzegmott-python-logging-loki

Send Python logs directly to Grafana Loki with minimal configuration.

✨ Features

• 📤 Direct Integration - Send logs straight to Loki
• 🔐 Authentication Support - Basic auth and custom headers
• 🏷️ Custom Labels - Flexible tagging system
• ⚡ Async Support - Non-blocking queue handler included
• 🔒 SSL Verification - Configurable SSL/TLS settings
• 🎯 Multi-tenant - Support for Loki multi-tenancy

📦 Installation

pip install tjzegmott-python-logging-loki

Or using uv (recommended):

uv add logging_loki

🎯 Quick Start

Basic Usage

import logging
import logging_loki

handler = logging_loki.LokiHandler(
    url="https://loki.example.com/loki/api/v1/push",
    tags={"app": "my-application"},
    auth=("username", "password"),
    version="2"
)

logger = logging.getLogger("my-app")
logger.addHandler(handler)
logger.info("Application started", extra={"tags": {"env": "production"}})

Async/Non-blocking Mode

For high-throughput applications, use the queue handler to avoid blocking:

import logging.handlers
import logging_loki
from multiprocessing import Queue

handler = logging_loki.LokiQueueHandler(
    Queue(-1),
    url="https://loki.example.com/loki/api/v1/push",
    tags={"app": "my-application"},
    version="2"
)

logger = logging.getLogger("my-app")
logger.addHandler(handler)
logger.info("Non-blocking log message")

⚙️ Configuration Options

🚨 Error Handling

By default, if a log record can't be delivered to Loki (network failure, TLS error, or an unexpected HTTP status code such as 405 Method Not Allowed), Python's standard logging machinery prints a --- Logging error --- traceback to stderr for every failed record (see logging.Handler.handleError).

A 405 typically means the request never reached Loki's push endpoint as a POST - check for things like an http:// → https:// redirect, a reverse proxy/ingress that only allows GET on that path, or a URL that doesn't end in /loki/api/v1/push. Test with curl -X POST <url> to confirm the endpoint accepts POST requests directly.

If you'd rather not have delivery failures spam your application logs while you investigate (or you're fine losing occasional log lines), set suppress_errors=True:

handler = logging_loki.LokiHandler(
    url="https://loki.example.com/loki/api/v1/push",
    tags={"app": "my-application"},
    version="2",
    suppress_errors=True,
)

The handler still closes/resets its HTTP session on failure so subsequent attempts start clean; it just skips the noisy stderr traceback.

🏷️ Labels

Logs are automatically labeled with:

• severity - Log level (INFO, ERROR, etc.)
• logger - Logger name
• Custom tags - From handler and extra={"tags": {...}}

logger.error(
    "Database connection failed",
    extra={"tags": {"service": "api", "region": "us-east"}}
)

🔐 Multi-tenant Setup

handler = logging_loki.LokiHandler(
    url="https://loki.example.com/loki/api/v1/push",
    headers={"X-Scope-OrgID": "tenant-1"},
    tags={"app": "my-app"}
)

Development

Prerequisites

• Python 3.8+
• uv for package management

Setup

git clone https://github.com/tjzegmott/python-logging-loki.git
cd python-logging-loki
make install

Running Tests

make test

# With coverage
make test-cov

# Across all Python versions
make test-matrix

Code Quality

# Run all checks (lint, format, type-check)
make verify

# Auto-fix lint and format issues
make fix

Prek

prek install
prek run --all-files

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgements

Based on python-logging-loki by GreyZmeem.