semlog 0.2.0__py3-none-any.whl

semlog/__init__.py

@@ -0,0 +1,45 @@
+"""SEMLOG: a stdlib-only structured logging library (CP-015, 8 public
+names once every phase lands); ``__all__`` never lists a name before it
+exists."""
+
+from __future__ import annotations
+
+from ._config import configure
+from ._context import bind, inject, operation
+from ._identity import _dist_version
+from ._middleware import ASGIMiddleware, WSGIMiddleware
+from ._transport import flush
+
+# The only code copy of the semconv version pinned in STANDARDS.md §4 (design
+# #170 §17.3); `llm()`'s generated header cites it alongside the installed
+# semlog version, so the stored guide itself carries no version literal.
+_OTEL_SEMCONV_VERSION = "1.44.0"
+
+
+def llm() -> str:
+    """Return the version-matched agent guide from package data, preceded
+    by a header generated at read time; no cache (DOC-011, CP-018)."""
+    import importlib.resources
+
+    guide = (
+        importlib.resources.files(__package__)
+        .joinpath("agent_guide.md")
+        .read_text(encoding="utf-8")
+    )
+    header = (
+        f"---\nsemlog_version: {_dist_version('semlog')}\n"
+        f"otel_semconv_version: {_OTEL_SEMCONV_VERSION}\n---\n\n"
+    )
+    return header + guide
+
+
+__all__: tuple[str, ...] = (  # noqa: RUF022
+    "configure",
+    "WSGIMiddleware",
+    "ASGIMiddleware",
+    "operation",
+    "bind",
+    "inject",
+    "flush",
+    "llm",
+)

semlog/__main__.py

@@ -0,0 +1,21 @@
+"""`python -m semlog` entry point: only the `llm` subcommand, no
+console-script (design-decisions #170 §17.4; CP-018)."""
+
+from __future__ import annotations
+
+import sys
+
+from . import llm
+
+
+def main(argv: list[str]) -> int:
+    """Return the process exit code for `argv` (`sys.argv[1:]`-shaped)."""
+    if argv == ["llm"]:
+        sys.stdout.buffer.write(llm().encode("utf-8"))
+        return 0
+    sys.stderr.write("usage: python -m semlog llm\n")
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

semlog/_baggage.py

@@ -0,0 +1,65 @@
+"""W3C Baggage parsing and allowlist codec (STANDARDS §8, TCP-007).
+
+Splits an inbound baggage header into raw, percent-encoded members in
+header order, skipping malformed members and truncating (never rejecting
+outright) past the spec limits of 64 members or 8192 bytes.
+`to_log_attributes` copies only the allowlisted keys into flat,
+percent-decoded, UNPREFIXED attributes: the formatter applies the
+configured baggage prefix once, at format time (design #162 §2.1 step 3c;
+engram #239 follow-up) -- prefixing here too would double it once
+`operation()`/`bind()` (Phase 3) wire this straight into `Snapshot.baggage`
+(`baggage.baggage.x`). Outbound stripping at a trust boundary (TCP-008) is
+a later task (`inject()`, 3.11/3.12).
+"""
+
+from __future__ import annotations
+
+import re
+import urllib.parse
+from types import SimpleNamespace
+
+_MAX_MEMBERS = 64
+_MAX_BYTES = 8192
+_TOKEN_RE = re.compile(r"^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$")
+
+# Process-wide defaults set by `configure(baggage_allow=..., accept_inbound_
+# baggage=...)` (design #162/#170 §3.3). `_context.snapshot_from_headers`
+# reads this directly with no import cycle: `_config` imports `_format`,
+# which imports `_context`, so `_context` cannot import `_config` back --
+# this module sits below both, so both can depend on it safely.
+defaults = SimpleNamespace(accept_inbound_baggage=True, baggage_allow=())
+
+
+def parse_baggage(header: str | None) -> tuple[tuple[str, str], ...]:
+    """Parse an inbound baggage header into ``(key, value)`` members."""
+    if not header:
+        return ()
+    members: list[tuple[str, str]] = []
+    total_bytes = 0
+    for raw_member in header.split(","):
+        if len(members) >= _MAX_MEMBERS:
+            break
+        candidate = raw_member.strip()
+        if not candidate:
+            continue
+        member_bytes = len(candidate.encode("utf-8"))
+        if total_bytes + member_bytes > _MAX_BYTES:
+            break
+        key, separator, value = candidate.split(";", 1)[0].partition("=")
+        key = key.strip()
+        if not separator or not _TOKEN_RE.match(key):
+            continue
+        members.append((key, value.strip()))
+        total_bytes += member_bytes
+    return tuple(members)
+
+
+def to_log_attributes(
+    members: tuple[tuple[str, str], ...], allow: tuple[str, ...]
+) -> dict[str, str]:
+    """Copy allowlisted members into flat, percent-decoded, unprefixed log
+    attributes (TCP-007); the formatter applies the baggage prefix."""
+    allowed = set(allow)
+    return {
+        key: urllib.parse.unquote(value) for key, value in members if key in allowed
+    }

semlog/_config.py

@@ -0,0 +1,192 @@
+"""`configure()`, the library's single entry point (design #162 §3.3/3.4).
+No configuration object (engram #238; CP-015): state lives in one
+module-level `types.SimpleNamespace`, not a class -- a stdlib type never
+counts against the class budget. `current()` returns it directly."""
+
+from __future__ import annotations
+
+import logging
+import os
+from types import SimpleNamespace
+
+from . import _modes
+from ._baggage import defaults as _baggage_defaults
+from ._format import Formatter
+from ._identity import resolve_identity
+from ._transport import attach_root as _attach_root
+from ._transport import capture_loggers as _capture_loggers
+from ._transport import install as _install_pipeline
+
+_CATALOG_MODES = ("off", "warn", "strict")
+_OVERFLOW_MODES = ("block", "drop")
+# LP-010: stdlib leaves the root logger at WARNING when unset; this
+# library always sets an explicit, configurable level instead (default
+# INFO), so INFO records are never silently dropped by omission.
+_LEVELS = {"DEBUG": 10, "INFO": 20, "WARNING": 30, "ERROR": 40, "CRITICAL": 50}
+
+_state = SimpleNamespace(
+    identity=None,
+    namespace="app",
+    catalog=None,
+    catalog_mode=None,
+    max_attributes=128,
+    max_attribute_length=None,
+    queue=True,
+    queue_size=10000,
+    overflow="block",
+)
+
+
+def current() -> SimpleNamespace:
+    """Return the state of the last `configure()` call (test/internal use)."""
+    if _state.identity is None:
+        raise RuntimeError("configure() has not been called yet")
+    return _state
+
+
+def _resolve_limit(explicit: int | None, kind: str, default: int | None) -> int | None:
+    """LRC-010's precedence: parameter > log-record `OTEL_*` var > generic var > default."""
+    if explicit is not None:
+        return explicit
+    for env_name in (
+        f"OTEL_LOGRECORD_ATTRIBUTE_{kind}_LIMIT",
+        f"OTEL_ATTRIBUTE_{kind}_LIMIT",
+    ):
+        raw = os.environ.get(env_name)
+        if raw:
+            try:
+                return int(raw)
+            except ValueError:
+                continue
+    return default
+
+
+def configure(
+    *,
+    service_name: str | None = None,
+    service_version: str | None = None,
+    service_namespace: str | None = None,
+    service_instance_id: str | None = None,
+    environment: str | None = None,
+    identity: tuple[object, ...] | None = None,
+    identity_levels: tuple[str, ...] = ("role", "component"),
+    level: str = "INFO",
+    namespace: str = "app",
+    capture_loggers: tuple[str, ...] = (),
+    redact_keys: tuple[str, ...] = (),
+    baggage_allow: tuple[str, ...] = (),
+    baggage_prefix: str = "baggage.",
+    accept_inbound_baggage: bool = True,
+    catalog: dict | None = None,
+    catalog_mode: str | None = None,
+    max_attributes: int | None = None,
+    max_attribute_length: int | None = None,
+    queue: bool = True,
+    queue_size: int = 10000,
+    overflow: str = "block",
+    mode: str | None = None,
+    search_dir: str | None = None,
+) -> None:
+    """Resolve identity and validate configuration; last call wins. `mode`
+    (LM-001) resolves before any other work, so an invalid value raises
+    before anything else in this process is touched."""
+    resolved_mode = _modes.resolve_mode(mode, search_dir=search_dir)
+    if level not in _LEVELS:
+        raise ValueError(f"level must be one of {sorted(_LEVELS)}, got {level!r}")
+    if catalog is not None and not isinstance(catalog, dict):
+        raise TypeError(
+            f"catalog must be a JSON-shaped dict document, not {type(catalog).__name__}"
+        )
+    if overflow not in _OVERFLOW_MODES:
+        raise ValueError(f"overflow must be one of {_OVERFLOW_MODES}, got {overflow!r}")
+    if not (isinstance(queue_size, int) and queue_size > 0):
+        raise ValueError(f"queue_size must be a positive int, got {queue_size!r}")
+
+    default_catalog_mode = "off" if catalog is None else "warn"
+    resolved_catalog_mode = (
+        default_catalog_mode if catalog_mode is None else catalog_mode
+    )
+    if resolved_catalog_mode not in _CATALOG_MODES:
+        raise ValueError(
+            f"catalog_mode must be one of {_CATALOG_MODES}, got "
+            f"{resolved_catalog_mode!r}"
+        )
+    if resolved_mode == "hybrid" and capture_loggers:
+        # LM-003: hybrid never takes root, so there is no pipeline handler
+        # a captured logger's records could propagate to instead.
+        raise ValueError("capture_loggers is not supported in hybrid mode")
+
+    if resolved_mode == "off":
+        # LM-005: as if semlog were not installed -- nothing else runs.
+        _modes.state.mode = "off"
+        _modes.state.marking = False
+        return
+
+    # Hybrid defers its pyproject diagnostic (SI-005 erratum 8): no
+    # pipeline exists yet to carry it as JSON, so it is collected here and
+    # emitted after install(), marked `semlog=True`.
+    pending_diagnostics = [] if resolved_mode == "hybrid" else None
+    _state.identity = resolve_identity(
+        service_name=service_name,
+        service_version=service_version,
+        service_namespace=service_namespace,
+        service_instance_id=service_instance_id,
+        environment=environment,
+        identity=identity,
+        identity_levels=identity_levels,
+        namespace=namespace,
+        search_dir=search_dir,
+        diagnostics=pending_diagnostics,
+    )
+    _state.namespace, _state.catalog = namespace, catalog
+    _state.catalog_mode = resolved_catalog_mode
+    _state.max_attributes = _resolve_limit(max_attributes, "COUNT", 128)
+    _state.max_attribute_length = _resolve_limit(
+        max_attribute_length, "VALUE_LENGTH", None
+    )
+    _state.level = level
+    _state.queue, _state.queue_size, _state.overflow = queue, queue_size, overflow
+    _baggage_defaults.accept_inbound_baggage = accept_inbound_baggage
+    _baggage_defaults.baggage_allow = baggage_allow
+
+    formatter = Formatter(
+        identity=_state.identity,
+        namespace=namespace,
+        baggage_prefix=baggage_prefix,
+        catalog=catalog,
+        catalog_mode=resolved_catalog_mode,
+        max_attributes=_state.max_attributes,
+        max_attribute_length=_state.max_attribute_length,
+        redact_keys=redact_keys,
+    )
+    handler = _install_pipeline(
+        formatter,
+        namespace=namespace,
+        queue=queue,
+        queue_size=queue_size,
+        overflow=overflow,
+    )
+
+    if resolved_mode == "full":
+        # LP-010: full always sets an explicit root level; hybrid leaves
+        # root's handlers and level exactly as found.
+        _attach_root(handler, level=_LEVELS[level], replace_all=True)
+        _capture_loggers(capture_loggers)
+    else:
+        # Hybrid never takes root: only detach a handler THIS library left
+        # there from an earlier full configure(), never a foreign one.
+        root = logging.getLogger()
+        for existing in list(root.handlers):
+            if getattr(existing, "_semlog_root", False):
+                root.removeHandler(existing)
+        _modes.arm_routing()
+
+    # `marking`/`mode` are the very last things this call touches: a second
+    # call that raises during validation above must never reach this point,
+    # so it leaves both exactly as the last successful call left them
+    # (validation-4 minor).
+    _modes.state.mode = resolved_mode
+    _modes.state.marking = resolved_mode == "hybrid"
+
+    if pending_diagnostics:
+        logging.getLogger("semlog").info(pending_diagnostics[0], semlog=True)

semlog/_context.py

@@ -0,0 +1,157 @@
+"""One immutable context snapshot per ``ContextVar`` (TCP-005), shared by
+``operation()``, ``bind()`` and the middlewares."""
+
+from __future__ import annotations
+
+import contextlib
+import contextvars
+import dataclasses
+import logging
+import urllib.parse
+from collections.abc import Mapping
+from types import MappingProxyType
+
+from . import _modes
+from ._baggage import defaults as _baggage_defaults
+from ._baggage import parse_baggage, to_log_attributes
+from ._request_id import generate_request_id
+from ._trace import new_span, parse_traceparent
+
+# Shared empty default. Python 3.11's dataclasses reject an unhashable default
+# (mappingproxy only became hashable in 3.12), so it is supplied by a factory.
+_EMPTY: Mapping[str, object] = MappingProxyType({})
+
+
+@dataclasses.dataclass(frozen=True)
+class Snapshot:
+    """An immutable, point-in-time view of the bound operation context."""
+
+    trace_id: str | None = None
+    span_id: str | None = None
+    trace_flags: str | None = None
+    tracestate: str | None = None
+    request_id: str | None = None
+    baggage: Mapping[str, str] = dataclasses.field(default_factory=lambda: _EMPTY)
+    attributes: Mapping[str, object] = dataclasses.field(default_factory=lambda: _EMPTY)
+
+
+_current: contextvars.ContextVar[Snapshot | None] = contextvars.ContextVar(
+    "semlog_context", default=None
+)
+
+# `current`/`push`/`pop`: the ContextVar's own bound get/set/reset need no
+# wrapper -- `current()` reads the bound snapshot (or `None`); `push()`
+# binds one and returns a reset token; `pop()` resets to the prior value.
+current, push, pop = _current.get, _current.set, _current.reset
+
+
+def snapshot_from_headers(get_header, *, baggage_allow=None) -> Snapshot:
+    """Build an inbound `Snapshot` from a header getter (design #162 §2.2/§2.3):
+    the shared primitive both middlewares and `operation()` bind from. The
+    formatter applies the configured baggage prefix at format time, not here.
+    `baggage_allow=None` (the default) falls back to `configure(baggage_
+    allow=...)`'s process-wide default; `configure(accept_inbound_baggage=
+    False)` ignores the inbound header entirely, regardless of any allowlist."""
+    inbound = parse_traceparent(get_header("traceparent"))
+    tracestate = get_header("tracestate") if inbound is not None else None
+    (trace_id, span_id, trace_flags), tracestate = new_span(inbound, tracestate)
+    if _baggage_defaults.accept_inbound_baggage:
+        allow = (
+            baggage_allow
+            if baggage_allow is not None
+            else _baggage_defaults.baggage_allow
+        )
+        baggage = to_log_attributes(parse_baggage(get_header("baggage")), allow)
+    else:
+        baggage = {}
+    return Snapshot(
+        trace_id=trace_id,
+        span_id=span_id,
+        trace_flags=trace_flags,
+        tracestate=tracestate,
+        request_id=generate_request_id(),
+        baggage=baggage,
+    )
+
+
+@contextlib.contextmanager
+def operation(headers=None, *, baggage_allow=None):
+    """Bind a trace/baggage scope for non-HTTP work (design #162 §2.3,
+    TCP-005): the same primitive the HTTP middlewares use. With `headers`,
+    parses them like an inbound request; without, starts a child of the
+    current operation if one is active, else a fresh trace. In `off` mode
+    (LM-005), this stays a working context manager but never actually
+    binds anything: it yields a fresh, unbound `Snapshot()` and every
+    field-generation cost (trace/span ids, baggage parsing) is skipped."""
+    if _modes.is_off():
+        yield Snapshot()
+        return
+    parent = current()
+    if headers is not None:
+        snapshot = snapshot_from_headers(headers.get, baggage_allow=baggage_allow)
+    elif parent is not None and parent.trace_id is not None:
+        inbound = (parent.trace_id, parent.span_id, parent.trace_flags)
+        (trace_id, span_id, trace_flags), tracestate = new_span(
+            inbound, parent.tracestate
+        )
+        snapshot = dataclasses.replace(
+            parent,
+            trace_id=trace_id,
+            span_id=span_id,
+            trace_flags=trace_flags,
+            tracestate=tracestate,
+            request_id=generate_request_id(),
+        )
+    else:
+        snapshot = snapshot_from_headers(
+            lambda _name: None, baggage_allow=baggage_allow
+        )
+    token = push(snapshot)
+    try:
+        yield snapshot
+    finally:
+        pop(token)
+
+
+_bind_warned = False
+
+
+def bind(attributes: Mapping[str, object]) -> None:
+    """Merge `attributes` into the active scope (TCP-005); outside a scope,
+    warn once through the `semlog` logger and no-op (TCP-012). In `off`
+    mode, that diagnostic is suppressed entirely (LM-005): `off`'s
+    `operation()` never binds anything either, so `bind()` already has no
+    effect there; only the once-per-process warning needs its own gate."""
+    global _bind_warned
+    snapshot = current()
+    if snapshot is None:
+        if not _bind_warned and not _modes.is_off():
+            _bind_warned = True
+            logging.getLogger("semlog").warning(
+                "semlog.log.bind_ignored", stack_info=True, semlog=True
+            )
+        return
+    push(
+        dataclasses.replace(snapshot, attributes={**snapshot.attributes, **attributes})
+    )
+
+
+def inject(headers: dict, *, trusted: bool = True) -> None:
+    """Add outbound `traceparent`/`tracestate`/`baggage` to `headers` in
+    place, client-agnostic (TCP-006/008/009/011); a no-op with no bound
+    trace or an already-present `traceparent` (any case)."""
+    snapshot = current()
+    if snapshot is None or snapshot.trace_id is None:
+        return
+    if any(key.lower() == "traceparent" for key in headers):
+        return
+    headers["traceparent"] = (
+        f"00-{snapshot.trace_id}-{snapshot.span_id}-{snapshot.trace_flags}"
+    )
+    if snapshot.tracestate is not None:
+        headers["tracestate"] = snapshot.tracestate
+    if trusted and snapshot.baggage:
+        headers["baggage"] = ",".join(
+            f"{key}={urllib.parse.quote(str(value))}"
+            for key, value in snapshot.baggage.items()
+        )