loki-reader-core

A lightweight Python library for querying Grafana Loki logs via REST API.

Features

• Simple, intuitive client for Loki's HTTP API
• Supports query, query_range, label discovery, and series matching
• SSL/TLS support including custom CA certificates for self-signed certs
• Multi-tenant support via X-Scope-OrgID header
• Basic authentication
• Clean dataclass models with to_dict()/from_dict() serialization
• All timestamps as Unix nanoseconds (Loki's native format)

Installation

From PyPI:

pip install loki-reader-core

From GitHub:

pip install loki-reader-core @ git+ssh://git@github.com/jmazzahacks/loki-reader-core.git@main

Usage

Basic Query

from loki_reader_core import LokiClient
from loki_reader_core.utils import hours_ago_ns, now_ns

client = LokiClient(base_url="https://loki.example.com")

result = client.query_range(
    logql='{job="api-server"} |= "error"',
    start=hours_ago_ns(1),
    end=now_ns(),
    limit=500
)

for stream in result.streams:
    print(f"Labels: {stream.labels}")
    for entry in stream.entries:
        print(f"  [{entry.timestamp}] {entry.message}")

With Authentication and Self-Signed Certificates

client = LokiClient(
    base_url="https://loki.internal.company.com:8443",
    auth=("username", "password"),
    ca_cert="/path/to/ca.pem"
)

Multi-Tenant Setup

client = LokiClient(
    base_url="https://loki.example.com",
    org_id="tenant-1"
)

Exploring Labels

labels = client.get_labels()
values = client.get_label_values("application")
series = client.get_series(match=['{application="my-app"}'])

Context Manager

with LokiClient(base_url="https://loki.example.com") as client:
    result = client.query(logql='{job="api"}')

API Reference

LokiClient

Methods

Timestamp Utilities

from loki_reader_core.utils import (
    now_ns,          # Current time as nanoseconds
    seconds_to_ns,   # Convert Unix seconds to nanoseconds
    ns_to_seconds,   # Convert nanoseconds to Unix seconds
    minutes_ago_ns,  # Timestamp N minutes ago
    hours_ago_ns,    # Timestamp N hours ago
    days_ago_ns,     # Timestamp N days ago
)

Development

Setup

# Create virtual environment
python -m venv .

# Activate virtual environment
source bin/activate

# Install dependencies
pip install -r dev-requirements.txt
pip install -e .

Running Tests

source bin/activate
pytest tests/ -v

License

MIT

Author

Jason Byteforge (@jmazzahacks)