log-foundry 0.10.2.dev3__tar.gz → 0.10.2.dev5__tar.gz

{log_foundry-0.10.2.dev3 → log_foundry-0.10.2.dev5}/PKG-INFO

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

{log_foundry-0.10.2.dev3 → log_foundry-0.10.2.dev5}/pyproject.toml

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

{log_foundry-0.10.2.dev3 → log_foundry-0.10.2.dev5}/src/log_foundry/__init__.py

@@ -3,8 +3,9 @@
 Public façade (module-function shape). Exposes configuration, the ``@trace`` decorator, the
 ``debug/info/warning/error/critical`` emitters, ``set_baggage``, the cross-process propagation
 pair (``continue_trace`` to adopt an inbound context; ``current_traceparent`` /
-``current_trace_context`` / ``current_baggage_header`` to publish this one), ``flush`` (drain and
-keep logging) and ``shutdown`` (drain, close the sink, and stop).
+``current_trace_context`` / ``current_baggage_header`` to publish this one), ``reset_context``
+(clear both for a caller who opens no span), ``flush`` (drain and keep logging) and ``shutdown``
+(drain, close the sink, and stop).
 """
 
 from importlib.metadata import PackageNotFoundError
@@ -16,6 +17,7 @@ from log_foundry.context import (
     current_baggage_header,
     current_trace_context,
     current_traceparent,
+    reset_context,
 )
 from log_foundry.decorator import continue_trace, trace
 from log_foundry.worker import Health
@@ -107,6 +109,7 @@ __all__ = [
     "get_config",
     "health",
     "info",
+    "reset_context",
     "set_baggage",
     "shutdown",
     "trace",

{log_foundry-0.10.2.dev3 → log_foundry-0.10.2.dev5}/src/log_foundry/context.py

@@ -29,8 +29,11 @@ __all__ = [
     "current_trace_context",
     "current_traceparent",
     "get_baggage",
+    "pop_baggage_scope",
     "pop_span",
+    "push_baggage_scope",
     "push_span",
+    "reset_context",
     "set_baggage",
 ]
 
@@ -81,6 +84,88 @@ def set_baggage(**kv: object) -> None:
     _baggage.set({**_baggage.get(), **kv})
 
 
+# -- the root-span scope (SPEC-024) ------------------------------------------------------
+
+
+def push_baggage_scope() -> contextvars.Token[dict[str, object]]:
+    """Open a root span's baggage scope; hand the token back to :func:`pop_baggage_scope`.
+
+    Setting the variable to its own current value is what mints the token — there is no other
+    way to say "restore whatever was here", including the case where nothing was ever set. It
+    is safe because no baggage dict is ever mutated in place (see this module's docstring).
+    """
+    return _baggage.set(_baggage.get())
+
+
+def pop_baggage_scope(token: contextvars.Token[dict[str, object]]) -> None:
+    """Close a root span's scope: restore baggage, discard any adopted trace context.
+
+    The two are deliberately **asymmetric**. Baggage is *restored*, so a process-level default
+    set before any span outlives the traces that run under it while a request's own keys do not
+    (SPEC-024 FR-001). The adopted context is *cleared*, because it is a one-shot handoff to the
+    trace it was adopted for: restoring it would leave the next invocation still joining the
+    previous caller's trace, which is the defect this scope exists to close (FR-002). A caller
+    who opens no span at all clears both with :func:`reset_context`.
+
+    Total — never raises, because a decorated function must not fail on the way out (arch §4).
+
+    One caveat the ``contextvars`` model makes unavoidable: both writes land in the context the
+    root span's ``finally`` runs in. An adoption made *outside* a span that then runs in a child
+    context — any ``asyncio.Task``, including the one ``asyncio.run`` creates — is cleared in
+    the copy, not in the parent that holds it. :func:`continue_trace` is documented to be called on
+    the entry point's first line, which is inside the span and unaffected; a caller who adopts
+    before dispatching across a task boundary clears it with :func:`reset_context`.
+    """
+    # Cleared first, and deliberately ahead of anything that could fail: a stale trace id puts
+    # *wrong* data in the log stream, while a missed baggage restore only leaves a stale field.
+    _adopted.set(None)
+    try:
+        _baggage.reset(token)
+    except Exception:
+        # `reset` rejects a token minted in another context (``ValueError``, reachable when a
+        # span body hands work to another thread) and one already used (``RuntimeError``).
+        # Setting the captured value directly is equivalent: this context never had the scope
+        # pushed onto it, so there is nothing else to unwind. Broad because the alternative is
+        # raising from a `finally` and replacing the caller's own exception (arch §4).
+        # `old_value` is ``Token.MISSING`` when the variable was unset at capture, and absent
+        # entirely if this was never a Token; neither can have come from `set_baggage`, so both
+        # land on empty rather than poisoning baggage with whatever was passed.
+        old = getattr(token, "old_value", None)
+        _baggage.set(old if isinstance(old, dict) else {})
+
+
+def reset_context() -> None:
+    """Clear baggage and any adopted trace context outright (SPEC-024 FR-003).
+
+    For the caller who uses the emitters **without** ``@trace``: the orphan path opens no span,
+    so there is no root-span exit to hang the release on, and both values would otherwise live
+    as long as the context does. A ``@trace`` user does not need this —
+    :func:`pop_baggage_scope` already runs at every root span's exit.
+
+    It is also the remedy for the one case that scope cannot reach: an adoption made outside a
+    span whose root span then runs in a child context, where the clear lands in the copy. Call
+    this in the context that made the adoption.
+
+    One function rather than two because the two values have the same lifetime and the same
+    failure mode, and a caller who wants one almost always wants the other.
+
+    Unlike the scope release this **clears** rather than restores — a process-level baggage
+    default set before any span is erased too, which is the point of an explicit reset. Safe
+    with nothing ever set, with no span open, and inside an open span. Never raises, like every
+    other entry point on this path (arch §4).
+
+    Prefer calling it **outside** a span. Inside one it does the obvious thing to the events
+    that follow, but SPEC-015 backfills ``span.start`` and ``span.end`` from the baggage live at
+    *close*, so a mid-span reset also empties the two boundary events — which describe the whole
+    span and carry ``duration_ms``/``status`` — of baggage that was live for most of it. That
+    span's exit then restores the baggage from before the span, as it always does.
+    """
+    # Cleared in the same order as `pop_baggage_scope`, for the reason given there: a stale
+    # trace id is wrong data, a stale baggage field is only stale.
+    _adopted.set(None)
+    _baggage.set({})
+
+
 # -- adopted inbound context (SPEC-014) --------------------------------------------------
 
 

{log_foundry-0.10.2.dev3 → log_foundry-0.10.2.dev5}/src/log_foundry/decorator.py

@@ -114,6 +114,12 @@ def continue_trace(
     Call it on the **first line** of the entry point: a child span that already finished has
     been handed to the worker and can no longer be rewritten.
 
+    The adoption is **consumed by that one root span** and does not survive it (SPEC-024): the
+    next root span opened with no fresh call of its own starts a new trace, which is what stops
+    a warm container from logging every later invocation into the first caller's trace. So a
+    batch that fans out to several *sibling* root spans needs one call per item — or, better, a
+    single ``@trace`` entry point so the items are nested spans of one trace.
+
     ``baggage`` is a W3C ``baggage`` header merged into the current context. It succeeds or
     fails independently of the trace context.
 
@@ -298,8 +304,11 @@ 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
                 try:
                     result = await fn(*args, **kwargs)
                     _close_span(span, "ok", None)
@@ -312,13 +321,18 @@ def trace(
                     raise
                 finally:
                     context.pop_span(token)
+                    if scope is not None:
+                        context.pop_baggage_scope(scope)
 
             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
             try:
                 result = fn(*args, **kwargs)
                 _close_span(span, "ok", None)
@@ -329,6 +343,8 @@ def trace(
                 raise
             finally:
                 context.pop_span(token)
+                if scope is not None:
+                    context.pop_baggage_scope(scope)
 
         return cast("F", wrapper)