python-logging-loki
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
tagsitem ofextradict - Property
foofrom 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.