loki-sdk 0.1.1

Loki-compatible logging SDK for hivetrace services. Provides a unified plain key=value log format and per-service field schemas.

loki-sdk

Loki-compatible logging SDK. Plain key=value wire format, per-service typed schemas, async-safe context propagation, auto-injected exception summary. Built on stdlib logging — no structlog/loguru.

Install

pip install loki-sdk

Usage

import logging
from loki_sdk import FieldSpec, LogSchema, LoggingConfig, bound, configure

SCHEMA = LogSchema(
    service_name="my-service",
    fields=(FieldSpec("status_code"), FieldSpec("duration_ms")),
)
configure(LoggingConfig.from_env(SCHEMA))
logger = logging.getLogger(__name__)

with bound(request_id="abc-123", endpoint="POST /clean-text"):
    logger.info("request_completed", extra={"status_code": 200, "duration_ms": 12.4})

Output:

2026-04-29T10:00:00Z [INFO] [my-service] [POST /clean-text] request_completed | status_code=200 duration_ms=12.4 request_id=abc-123

On exceptions, error="ClassName: msg" and caller=<module>:<func>:<lineno> are injected automatically.

Configuration

Read by LoggingConfig.from_env:

Variable	Default	Effect
LOG_LEVEL	INFO	Root log level.
LOG_FORMAT	plain	Wire format. Only plain is supported in v0.1.
LOG_CALLER_ON_ERROR	1	Inject caller= on records with levelno >= ERROR or exc_info.

Public API

Symbol	Purpose
LogSchema	Per-service field declaration.
FieldSpec	One field in a LogSchema.
LoggingConfig	Args for configure(). Prefer from_env(SCHEMA).
configure	Wires the SDK into stdlib logging.
bind / reset	Token-based contextvar binding.
bound	Context-manager flavor of bind.
clear	Reset the current logging context.
get_context	Read-only snapshot of the current context dict.
get_logger	Re-export of logging.getLogger.

License

Apache-2.0. See LICENSE.