log-foundry 0.10.2.dev2__tar.gz → 0.10.2.dev4__tar.gz

{log_foundry-0.10.2.dev2 → log_foundry-0.10.2.dev4}/PKG-INFO

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

{log_foundry-0.10.2.dev2 → log_foundry-0.10.2.dev4}/pyproject.toml

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

{log_foundry-0.10.2.dev2 → log_foundry-0.10.2.dev4}/src/log_foundry/context.py

@@ -29,7 +29,9 @@ __all__ = [
     "current_trace_context",
     "current_traceparent",
     "get_baggage",
+    "pop_baggage_scope",
     "pop_span",
+    "push_baggage_scope",
     "push_span",
     "set_baggage",
 ]
@@ -81,6 +83,56 @@ 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 {})
+
+
 # -- adopted inbound context (SPEC-014) --------------------------------------------------
 
 

{log_foundry-0.10.2.dev2 → log_foundry-0.10.2.dev4}/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)