log-foundry 0.10.2.dev7__tar.gz → 0.10.2.dev9__tar.gz

{log_foundry-0.10.2.dev7 → log_foundry-0.10.2.dev9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: log-foundry
-Version: 0.10.2.dev7
+Version: 0.10.2.dev9
 Summary: Generate logs for your console and JSON events for downstream consumption.
 License-Expression: MIT
 License-File: LICENSE

{log_foundry-0.10.2.dev7 → log_foundry-0.10.2.dev9}/pyproject.toml

@@ -20,7 +20,7 @@ dependencies = [
 ]
 
 # Optional features. Install with: pip install log-foundry[aws]
-version = "0.10.2.dev7"
+version = "0.10.2.dev9"
 
 [project.optional-dependencies]
 aws = ["boto3>=1.43.61"]              # SQSSink, SNSSink, KinesisSink, FirehoseSink

log_foundry-0.10.2.dev9/src/log_foundry/_diag.py

@@ -0,0 +1,53 @@
+"""The library's own diagnostic channel — one line on stderr, for failures it absorbed.
+
+This library *is* the logger, so it cannot report its own faults through itself: an event
+describing a broken sink would be handed to that same broken sink. Stderr is the channel of last
+resort, and every site that swallows an exception to keep architecture §4's promise (logging never
+breaks the application) announces it through here, so the wording and the safety rules are decided
+once rather than per call site.
+
+Two rules, both load-bearing:
+
+* **The exception's type, never its message.** A message can carry a value from the event that
+  provoked it, and arch §6 keeps user data out of anything the library emits about itself — the
+  same rule SPEC-019 applies to ``Health.stopped_reason``. A type name is enough to tell a
+  ``ConnectionError`` from a ``TypeError``, which is what the reader needs.
+* **No stream fault escapes.** It is called from ``except`` and ``finally`` blocks whose entire
+  purpose is to stop an exception reaching the caller, so a failure here — a closed stderr at
+  interpreter shutdown, a stream that rejects the write, ``sys.stderr`` set to ``None`` — must not
+  become the exception those guards existed to prevent. A ``BaseException`` still passes through,
+  as everywhere else in this library: a ``KeyboardInterrupt`` landing mid-write is the operator's
+  intent, not a stream fault to swallow.
+
+SPEC-029 takes ownership of this module and moves the ``repr(exception)`` sink sites onto it.
+"""
+
+from __future__ import annotations
+
+import sys
+
+__all__ = ["absorbed"]
+
+
+def absorbed(where: str, exc: BaseException, detail: str = "") -> None:
+    """Report a failure the library swallowed rather than propagated.
+
+    Never raises on a stream fault; a ``BaseException`` from the write still propagates.
+
+    Args:
+        where: What was being attempted, as a participle phrase that reads after "while" —
+            ``"closing a span"``, ``"emitting an orphan log"``.
+        exc: The absorbed exception. Only ``type(exc).__name__`` is written.
+        detail: Optional consequence for the reader, appended after a semicolon — most usefully
+            what was lost, since an absorbed failure is invisible apart from this line.
+    """
+    try:
+        suffix = f"; {detail}" if detail else ""
+        sys.stderr.write(
+            f"log-foundry: absorbed a failure while {where} ({type(exc).__name__}){suffix}\n"
+        )
+    except Exception:
+        # The channel of last resort has no fallback of its own. Reporting is best-effort by
+        # construction: losing the line is bad, raising from the guard that exists to protect
+        # the caller's exception would be worse (arch §4).
+        pass

{log_foundry-0.10.2.dev7 → log_foundry-0.10.2.dev9}/src/log_foundry/api.py

@@ -12,7 +12,7 @@ the sink via the normal path.
 
 from __future__ import annotations
 
-from log_foundry import context
+from log_foundry import _diag, context
 from log_foundry.config import _ensure_sink
 from log_foundry.console import ConsoleWriter
 from log_foundry.context import set_baggage
@@ -40,9 +40,16 @@ def _log(level: str, message: str, echo: bool, fields: dict[str, object]) -> Non
     With no active span (orphan) it becomes a standalone one-event span — fresh ``trace_id``,
     ``parent_span_id=None`` — flushed directly so nothing is dropped (FR-004). ``echo`` writes
     the same event as a human-readable console line, additively.
+
+    The orphan branch is the one that reaches the sink **on the caller's own thread**, with no
+    worker between them to absorb a failure, so it is guarded end to end (SPEC-025 FR-003): a
+    bare ``log_foundry.info(...)`` must not hand the application a ``ConnectionError`` from a
+    destination the application never chose to talk to. The in-span branch is deliberately left
+    untouched — it only appends to a list, and FR-003 requires no behaviour change there.
     """
     baggage = context.get_baggage()
     span = context.current_span()
+    event: dict[str, object] | None = None
     if span is not None:
         event = build_event(span, level, message, fields=fields, baggage=baggage)
         span.events.append(event)
@@ -51,17 +58,29 @@ def _log(level: str, message: str, echo: bool, fields: dict[str, object]) -> Non
         # log is recorded, not silently dropped. Resolve the sink via _ensure_sink (as the
         # decorator does) so a zero-config orphan log falls back to StdoutSink instead of
         # crashing. SPEC-004's worker will later own this direct handoff.
-        orphan = Span(
-            trace_id=new_trace_id(),
-            span_id=new_span_id(),
-            parent_span_id=None,
-            name=message,
-            start_ts=0.0,
-        )
-        event = build_event(orphan, level, message, fields=fields, baggage=baggage)
-        _ensure_sink().emit([event])
-    if echo:
-        _console.write(event)
+        try:
+            orphan = Span(
+                trace_id=new_trace_id(),
+                span_id=new_span_id(),
+                parent_span_id=None,
+                name=message,
+                start_ts=0.0,
+            )
+            event = build_event(orphan, level, message, fields=fields, baggage=baggage)
+            _ensure_sink().emit([event])
+        except Exception as exc:
+            # The whole branch, not just `emit`: `_ensure_sink` constructs the sink on first
+            # use, so a sink that fails to *build* raises here too — and that is the shape the
+            # spec's own motivating case takes.
+            _diag.absorbed("emitting an orphan log", exc, "the event was lost")
+    if echo and event is not None:
+        try:
+            _console.write(event)
+        except Exception as exc:
+            # An echo is a diagnostic convenience and must not outrank the caller: the stream
+            # may be closed, redirected, or gone at interpreter shutdown. It runs *after* the
+            # emit, so a broken console never costs the event itself.
+            _diag.absorbed("echoing to the console", exc)
 
 
 def debug(message: str, *, echo: bool = False, **fields: object) -> None:

{log_foundry-0.10.2.dev7 → log_foundry-0.10.2.dev9}/src/log_foundry/context.py

@@ -91,8 +91,20 @@ def push_span(span: Span) -> contextvars.Token[tuple[Span, ...]]:
 
 
 def pop_span(token: contextvars.Token[tuple[Span, ...]]) -> None:
-    """Restore the span stack to its state before the matching :func:`push_span`."""
-    _span_stack.reset(token)
+    """Restore the span stack to its state before the matching :func:`push_span`.
+
+    Total — never raises, on the same terms and for the same reason as
+    :func:`pop_baggage_scope`: it runs in the decorator's ``finally``, where an exception would
+    replace the one the caller's own function raised (arch §4, SPEC-025).
+    """
+    try:
+        _span_stack.reset(token)
+    except Exception:
+        # `reset` rejects a token minted in another context and one already used. Restoring the
+        # captured stack directly is equivalent; anything that is not a tuple of spans cannot
+        # have come from `push_span`, so it falls back to empty rather than corrupting the stack.
+        old = getattr(token, "old_value", None)
+        _span_stack.set(old if isinstance(old, tuple) else ())
 
 
 def get_baggage() -> dict[str, object]:

{log_foundry-0.10.2.dev7 → log_foundry-0.10.2.dev9}/src/log_foundry/decorator.py

@@ -28,9 +28,9 @@ import sys
 import threading
 from collections.abc import Callable
 from time import monotonic
-from typing import Any, TypeVar, cast, overload
+from typing import TYPE_CHECKING, Any, TypeVar, cast, overload
 
-from log_foundry import context
+from log_foundry import _diag, context
 from log_foundry.config import _ensure_sink
 from log_foundry.ids import (
     is_valid_span_id,
@@ -42,6 +42,9 @@ from log_foundry.ids import (
 from log_foundry.model import Span, backfill_baggage, end_event, start_event
 from log_foundry.worker import Health, Worker
 
+if TYPE_CHECKING:
+    import contextvars
+
 __all__ = ["continue_trace", "trace"]
 
 # Bound on how much of a rejected inbound value is echoed into a stderr warning.
@@ -272,6 +275,97 @@ def _flush(span: Span) -> None:
     _get_worker().submit(span.events)
 
 
+type _SpanScope = tuple[
+    Span | None,
+    contextvars.Token[tuple[Span, ...]] | None,
+    contextvars.Token[dict[str, object]] | None,
+]
+
+
+def _begin(name: str, defaults: dict[str, object] | None) -> _SpanScope:
+    """Open a span and make it current, degrading rather than failing. Never raises.
+
+    Everything here runs **before** the caller's function body, so a failure would mean the
+    library prevented the application from doing its work at all — the worst reading of arch §4,
+    and worse than the close-path faults (SPEC-025 FR-001) because nothing has run yet.
+
+    Whatever succeeded is kept, and :func:`_end` releases exactly that much. Four shapes reach
+    it, and the *order of the three steps* is what keeps every one of them coherent:
+
+    * ``(span, token, scope)`` — everything worked; ``scope`` is ``None`` for a nested call,
+      which has no root scope to open.
+    * ``(span, token, None)`` — a nested call, or a root whose scope failed. **The scope is
+      taken first for this reason**: opened last, a root call that lost only its scope would
+      keep the span *and* leak its baggage into the next request, which is the SPEC-024 defect
+      reappearing through a failure path. Taken first, a lost scope means no span either.
+    * ``(None, None, scope)`` — the span could not be opened; the call runs untraced and the
+      scope is still released, so nothing leaks.
+    * ``(None, None, None)`` — nothing was set up.
+
+    A span that exists but was never pushed (``token is None``) is still closed and flushed by
+    :func:`_end`: it is not *current*, so nested calls will not parent to it and its own events
+    are all it carries, but that is more than discarding it would preserve.
+
+    The root test reads :func:`~log_foundry.context.current_span` before :func:`_open_span`,
+    which is what makes the new span current (SPEC-024).
+    """
+    span: Span | None = None
+    token: contextvars.Token[tuple[Span, ...]] | None = None
+    scope: contextvars.Token[dict[str, object]] | None = None
+    try:
+        if context.current_span() is None:
+            scope = context.push_baggage_scope()
+        span = _open_span(name, defaults)
+        token = context.push_span(span)
+    except Exception as exc:
+        _diag.absorbed(
+            "opening a span",
+            exc,
+            "this call runs untraced" if span is None else "this call is traced incompletely",
+        )
+    return span, token, scope
+
+
+def _end(
+    span: Span | None,
+    token: contextvars.Token[tuple[Span, ...]] | None,
+    scope: contextvars.Token[dict[str, object]] | None,
+    status: str,
+    error: BaseException | None,
+) -> None:
+    """Close the span and release the context. Never raises on a library fault.
+
+    Called from the wrappers' ``finally`` **once** per span, with the outcome the body actually
+    had (SPEC-025 FR-002) — the previous shape closed once in the ``try`` and again in the
+    ``except``, so a close that failed on the success path emitted a second, contradicting
+    ``span.end`` for a call that had returned normally.
+
+    The catch is ``Exception``, never ``BaseException``: a ``KeyboardInterrupt`` or
+    ``SystemExit`` arriving here is the operator's or the runtime's intent and must still reach
+    the caller. That is the same line SPEC-019 drew in the opposite direction for the worker
+    thread, where the *absence* of a handler was the defect.
+
+    One ordering constraint, and only one: the baggage scope is released **after** the close, so
+    SPEC-015's backfill still reads the baggage that was live inside the span. The stack pop is
+    order-independent — ``_close_span`` reads the span it is handed and the current baggage,
+    never the stack — and simply mirrors the setup. Both releases are total in their own right
+    (SPEC-024, SPEC-025), so neither needs a guard here.
+
+    The ``is not None`` checks are load-bearing, not defensive tidiness: ``pop_span(None)`` would
+    fall through that function's own guard to ``set(())`` and wipe the whole stack, detaching the
+    parent of an untraced *nested* call and splitting its trace.
+    """
+    if span is not None:
+        try:
+            _close_span(span, status, error)
+        except Exception as exc:
+            _diag.absorbed("closing a span", exc, "the span's events were lost")
+    if token is not None:
+        context.pop_span(token)
+    if scope is not None:
+        context.pop_baggage_scope(scope)
+
+
 def _close_span(span: Span, status: str, exc: BaseException | None) -> None:
     """Append the end event, complete the boundary events' baggage, then flush.
 
@@ -311,47 +405,49 @@ def trace(
 
             @functools.wraps(fn)
             async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
-                # Before _open_span, which is what makes the new span current (SPEC-024).
-                is_root = context.current_span() is None
-                span = _open_span(name or fn.__qualname__, defaults)
-                token = context.push_span(span)
-                scope = context.push_baggage_scope() if is_root else None
+                span, token, scope = _begin(name or fn.__qualname__, defaults)
+                status, error = "ok", None
                 try:
                     result = await fn(*args, **kwargs)
-                    _close_span(span, "ok", None)
-                    return result
                 except BaseException as exc:
-                    # Non-swallowing (arch §4): record the error, then re-raise unchanged.
+                    # Non-swallowing (arch §4): record the outcome, then re-raise unchanged.
                     # BaseException covers asyncio.CancelledError — a cancelled coroutine is
                     # recorded as an error end event, never left with an unclosed span.
-                    _close_span(span, "error", exc)
+                    status, error = "error", exc
                     raise
                 finally:
-                    context.pop_span(token)
-                    if scope is not None:
-                        context.pop_baggage_scope(scope)
+                    try:
+                        _end(span, token, scope, status, error)
+                    finally:
+                        # `except ... as exc` auto-deletes its target for exactly this reason.
+                        # `error` holds an exception whose traceback holds this frame, so
+                        # keeping it past the handler builds a cycle only the collector can
+                        # break — and pins the caller's own frames and locals along with it.
+                        del status, error
+                return result
 
             return cast("F", async_wrapper)
 
         @functools.wraps(fn)
         def wrapper(*args: Any, **kwargs: Any) -> Any:
-            # Before _open_span, which is what makes the new span current (SPEC-024).
-            is_root = context.current_span() is None
-            span = _open_span(name or fn.__qualname__, defaults)
-            token = context.push_span(span)
-            scope = context.push_baggage_scope() if is_root else None
+            span, token, scope = _begin(name or fn.__qualname__, defaults)
+            status, error = "ok", None
             try:
                 result = fn(*args, **kwargs)
-                _close_span(span, "ok", None)
-                return result
             except BaseException as exc:
-                # Non-swallowing (arch §4): record the error, then re-raise unchanged.
-                _close_span(span, "error", exc)
+                # Non-swallowing (arch §4): record the outcome, then re-raise unchanged.
+                status, error = "error", exc
                 raise
             finally:
-                context.pop_span(token)
-                if scope is not None:
-                    context.pop_baggage_scope(scope)
+                try:
+                    _end(span, token, scope, status, error)
+                finally:
+                    # `except ... as exc` auto-deletes its target for exactly this reason.
+                    # `error` holds an exception whose traceback holds this frame, so keeping
+                    # it past the handler builds a cycle only the collector can break — and
+                    # pins the caller's own frames and locals along with it.
+                    del status, error
+            return result
 
         return cast("F", wrapper)