Skip to main content

python-logging-loki

PyPI version Python version License Build Status

Python logging handler for Loki.
https://grafana.com/loki

Installation

pip install inuits-python-logging-loki

Usage

import logging
import logging_loki


handler = logging_loki.LokiHandler(
    url="https://my-loki-instance/loki/api/v1/push",
    tags={"application": "my-app"},
    headers={"X-Scope-OrgID": "example-id"},
    auth=("username", "password"),
    props_to_labels = ["foo"]
)

logger = logging.getLogger("my-logger")
logger.addHandler(handler)
logger.error(
    "Something happened",
    extra={"tags": {"service": "my-service"}},
)

Example above will send Something happened message along with these labels:

  • Default labels from handler
  • Message level as serverity
  • Logger's name as logger
  • Labels from tags item of extra dict
  • Property foo from log record will be sent as loki label

Properties to label

Using a dict instead of a list for props_to_labels will enable renaming labels

handler = logging_loki.LokiHandler(
    url="https://my-loki-instance/loki/api/v1/push",
    tags={"application": "my-app"},
    props_to_labels = {
        "otelTraceID": "trace_id"
        "otelSpanID":  "span_id"
    }
)

In this case, the properties otelTraceID & otelSpanID will be renamed to trace_id & span_id loki labels

Non-blocking mode

Adding a LokiHandler to a logger directly is blocking: every log call does an HTTP POST to Loki on the calling thread and waits for the response. In a request handler that puts Loki's latency (and Loki's rate limiting) straight into your own response time.

Use LokiQueueHandler instead. It attaches to the logger, creates the LokiHandler and a QueueListener, and starts the listener, so the calling thread only puts the record on a queue.

import logging_loki
from queue import Queue


handler = logging_loki.LokiQueueHandler(
    Queue(-1),
    batch_interval=2,  # seconds; omit or pass 0 to push every record separately
    url="https://my-loki-instance/loki/api/v1/push",
    tags={"application": "my-app"},
    headers={"X-Scope-OrgID": "example-id"},
    auth=("username", "password"),
    props_to_labels=["foo"],
)

logger = logging.getLogger("my-logger")
logger.addHandler(handler)
logger.error(...)

If you wire the queue up by hand, you must start the listener yourself — a QueueListener that is never started means nothing ever drains the queue and no log line reaches Loki:

queue = Queue(-1)
handler = logging.handlers.QueueHandler(queue)
handler_loki = logging_loki.LokiHandler(url=..., tags=...)
listener = logging.handlers.QueueListener(queue, handler_loki)
listener.start()  # <- required

Batching and timeouts

With batch_interval set, records are buffered and pushed as one request. This is what keeps Loki from answering with 429 Too Many Requests: without it every log line is its own POST and its own stream.

Variable Default Meaning
LOKI_BATCH_INTERVAL 2 Seconds between batched pushes (LokiLogger only). 0 disables batching.
LOKI_MAX_BATCH_BUFFER_SIZE 1000 Records buffered before a push happens regardless of the interval.
LOKI_CONNECT_TIMEOUT 2 Connect timeout, in seconds, for a push to Loki.
LOKI_READ_TIMEOUT 5 Read timeout, in seconds, for a push to Loki.

A push that Loki rejects (429, or any other unexpected status) raises logging_loki.emitter.LokiPushError and the records in that batch are dropped. The HTTP session is kept open, since the connection is still healthy — only a transport-level failure closes it and forces a reconnect.

Forking servers

LokiQueueHandler does its work on background threads, and threads do not survive fork(). Handlers built before the fork — a logger created at import time under gunicorn --preload, for example — recreate their queue, listener and flush threads in the child automatically, so each worker delivers its own records and does not re-send the parent's.

Metadata

Release files for inuits-python-logging-loki 1.5.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for inuits-python-logging-loki 1.5.0
File Size Uploaded Provenance Actions
inuits_python_logging_loki-1.5.0.tar.gz 15.5 kB With provenance Details for inuits_python_logging_loki-1.5.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for inuits-python-logging-loki 1.5.0
File Interpreter ABI Platform Actions
inuits_python_logging_loki-1.5.0-py3-none-any.whl Python 3 none any Details for inuits_python_logging_loki-1.5.0-py3-none-any.whl

Total release size: 30.7 kB

Release files / inuits_python_logging_loki-1.5.0.tar.gz

Download URL inuits_python_logging_loki-1.5.0.tar.gz
Size 15.5 kB
Tags Source
SHA-256 checksum
How to use checksums
d986cba9084e46c641166bfd6e0be7bcb9c2351f87a4b1fef1d7d8e835cb6b5f
BLAKE2b-256 checksum
How to use checksums
d289afa6837e48ece0c8ef9bfcbb708b0e291cbfb7014d597df2851cc64e3706
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 1, 2026.

Transparency log

Release files / inuits_python_logging_loki-1.5.0-py3-none-any.whl

Download URL inuits_python_logging_loki-1.5.0-py3-none-any.whl
Size 15.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c071705175a8581902eac60d5e72bc3edfc0811d04078bd63b4a699df27cac00
BLAKE2b-256 checksum
How to use checksums
70041c0f7d39b0785c3c8e9e7030a7542e2a862ade6ddd34477adaaa2822dc6c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 1, 2026.

Transparency log

Security for inuits-python-logging-loki 1.5.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for inuits_python_logging_loki-1.5.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 1, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page