obslog

AI-native, domain-agnostic observability SDK for Python. Structured logging is its first capability; the architecture extends to tracing, metrics, audit, and diagnostics without breaking changes.

Traditional logging answers "what happened?". obslog is built so its output also answers "why did it happen, what evidence exists, and how can an external AI agent reconstruct the root cause?" — by emitting stable, machine-readable, correlated evidence instead of prose. obslog never calls an LLM; it produces the deterministic evidence an LLM (or a human) consumes.

Status: feature-complete for 1.0 (M0–M6 delivered). Structured logging, configuration, processors, AI-native diagnostics, performance, and plugins are implemented and tested; docs and release automation are in place. The authoritative specification is PRODUCT.md — everything in this repo traces back to it. Full docs are built with MkDocs (docs/, mkdocs serve).

Why obslog

• Evidence, not narrative — events are stable dotted names + structured fields, not format strings.
• Deterministic & machine-readable — a published, versioned Record JSON Schema is the contract for AI and test consumers.
• Correlated by default — execution_id / trace_id / parent_execution flow across calls and async boundaries via contextvars, forming causal trees.
• Domain-agnostic — the SDK carries and structures metadata; it never interprets business semantics.
• Zero required dependencies — the core is stdlib-only; integrations are optional.
• Library-safe — no mandatory global logger; isolated providers are first-class.

Usage (see PRODUCT.md §10 and the docs)

import obslog

log = obslog.get_logger(__name__)
log.info("order.completed", order_id=oid, duration_ms=12)
log.error("db.query.failed", error=exc, error_code="DB_TIMEOUT", query_id=qid)

log = log.bind(component="checkout", request_id=rid)  # immutable bound context

with obslog.context(execution_id=obslog.new_id(), trace_id=tid):
    handle_request()  # correlation flows automatically

with log.operation("charge_card", phase="payment") as op:
    op.set(amount=100)  # auto duration + error capture

Project map

Path	Purpose
PRODUCT.md	The source-of-truth specification (RFC).
docs/adr/	Architecture Decision Records.
schemas/	Published Record JSON Schema (the data contract).
src/obslog/	SDK package (facade + back-end, by milestone).
tests/	Unit, integration, property, and benchmark tests.

License

Apache-2.0. See LICENSE.