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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: log-foundry
-Version: 0.10.2.dev4
+Version: 0.10.2.dev6
 Summary: Generate logs for your console and JSON events for downstream consumption.
 License-Expression: MIT
 License-File: LICENSE
@@ -184,8 +184,10 @@ span: if one exists, the new span copies its `trace_id` and records its `span_id
 new span is then pushed, so anything it calls sees *it* as the parent. On exit the span is
 popped by restoring the stack to its exact prior state (via a token, not a blind pop), which
 stays correct even when code branches into concurrent tasks. Because the stack lives in a
-context variable, every thread and asyncio task gets its own isolated copy — so `asyncio.gather`
-children share their parent's trace, and baggage set in one task never leaks into a sibling.
+context variable, every asyncio task gets its own isolated copy — so `asyncio.gather` children
+share their parent's trace, and baggage set in one task never leaks into a sibling. A new thread
+gets a fresh context rather than a copy, so nothing follows it there unless the caller copies one
+(as `asyncio.to_thread` does).
 
 ### When the worker flushes
 
@@ -291,7 +293,14 @@ def process_payment(user_id: int) -> str:
 
 - **`set_baggage(**kv)`** — attach trace-scoped context that is merged into the `fields` of
   every subsequent event in the same execution flow. Precedence, lowest to highest: config
-  `defaults` → span `defaults` → baggage → per-call `fields`.
+  `defaults` → span `defaults` → baggage → per-call `fields`. **Trace-scoped means it ends
+  with the trace:** when the outermost `@trace` call returns *or raises*, the baggage in effect
+  before it is restored, so one request's keys do not reach the next request's events. Nested
+  calls do not reset — baggage set three calls deep stays visible to its parent and to the
+  siblings after it. Set with no span open it becomes a process-level default that later traces
+  inherit and restore to (`configure(defaults=...)` is the better tool for that) — and a process
+  that logs *without* `@trace` has no root span to release anything, so it needs
+  [`reset_context()`](#clearing-context-in-a-long-lived-process).
 - **`echo=True`** — *additionally* write a human-readable `LEVEL   message` line to the console
   (`sys.stderr` by default), synchronously, without waiting for the async flush. The event
   still rides the normal pipeline to the sink — echo never redirects.
@@ -339,6 +348,7 @@ def handler(event, context):
 | `current_traceparent()` | This span as a W3C `traceparent` string, or `None` if no span is active. |
 | `current_trace_context()` | `(trace_id, span_id)`, for when moving two fields beats moving a string. |
 | `current_baggage_header()` | Current baggage in W3C `baggage` format (`""` when empty). |
+| `reset_context()` | Clear baggage and any adopted context. `@trace` users do not need it. Never raises. |
 
 Details worth knowing:
 
@@ -363,10 +373,45 @@ Details worth knowing:
   join because one field was malformed is worse. Headers over 8192 bytes are rejected. Values
   are percent-encoded, so `,` `=` and non-ASCII round-trip; non-string values are serialized
   with `str()`, so a dict arrives as its repr.
+- **An adopted context is consumed by one root span.** It applies to the next root span opened
+  and does not survive it, so the invocation after it starts a fresh trace unless it adopts
+  again. That is what stops a warm container from logging every later invocation into the first
+  caller's trace. A batch that fans out to several *sibling* root spans therefore needs one
+  `continue_trace()` per item — or, better, one `@trace` entry point so the items are nested
+  spans of a single trace.
 - **Sampling is not honoured.** `traceparent`'s flags byte is parsed and ignored, and outbound
   is always `01`: this library records every span, so respecting another system's sampling
   decision would mean dropping them.
 
+#### Clearing context in a long-lived process
+
+`@trace` releases both baggage and the adopted context when the outermost decorated call returns
+or raises, so **most callers never need `reset_context()`**. It exists for the two cases where no
+root-span exit releases them in *your* context:
+
+```python
+lf.reset_context()      # clears baggage *and* any adopted trace context
+```
+
+- **You use the emitters without `@trace`.** An orphan log opens no span, so nothing releases
+  what `set_baggage()` or `continue_trace()` set. In a process that reuses one thread across
+  requests — the main thread, a pooled worker, a warm Lambda container — that state reaches the
+  next request. Call `reset_context()` when a unit of work ends. (An orphan log never joins an
+  adopted trace either: it mints its own `trace_id`, and the adoption simply waits to claim the
+  next root span, whenever one happens to run.)
+- **You adopt outside the span and dispatch into a task.** The release runs in whichever
+  context the root span's `finally` runs in, so `continue_trace()` here followed by
+  `asyncio.run(main())` clears the adoption in the task's copy of the context while this one
+  keeps it. `contextvars` has no way to write back to a parent context, so clear it yourself.
+  Adopting on the entry point's first line — the documented placement — is inside the span and
+  needs nothing.
+
+It clears rather than restores: a process-level baggage default set before any span is erased
+too — permanently when you call it outside a span. Prefer that. Called *inside* a span it also
+empties the `span.start` / `span.end` events of baggage, because those are stamped with the
+span's *final* baggage at close, and that span's exit then restores the pre-span baggage anyway,
+undoing the erasure. It never raises.
+
 ### Sinks
 
 A **sink** is the swappable output transport — any object satisfying the `Sink` protocol. It

{log_foundry-0.10.2.dev4 → log_foundry-0.10.2.dev6}/README.md

@@ -148,8 +148,10 @@ span: if one exists, the new span copies its `trace_id` and records its `span_id
 new span is then pushed, so anything it calls sees *it* as the parent. On exit the span is
 popped by restoring the stack to its exact prior state (via a token, not a blind pop), which
 stays correct even when code branches into concurrent tasks. Because the stack lives in a
-context variable, every thread and asyncio task gets its own isolated copy — so `asyncio.gather`
-children share their parent's trace, and baggage set in one task never leaks into a sibling.
+context variable, every asyncio task gets its own isolated copy — so `asyncio.gather` children
+share their parent's trace, and baggage set in one task never leaks into a sibling. A new thread
+gets a fresh context rather than a copy, so nothing follows it there unless the caller copies one
+(as `asyncio.to_thread` does).
 
 ### When the worker flushes
 
@@ -255,7 +257,14 @@ def process_payment(user_id: int) -> str:
 
 - **`set_baggage(**kv)`** — attach trace-scoped context that is merged into the `fields` of
   every subsequent event in the same execution flow. Precedence, lowest to highest: config
-  `defaults` → span `defaults` → baggage → per-call `fields`.
+  `defaults` → span `defaults` → baggage → per-call `fields`. **Trace-scoped means it ends
+  with the trace:** when the outermost `@trace` call returns *or raises*, the baggage in effect
+  before it is restored, so one request's keys do not reach the next request's events. Nested
+  calls do not reset — baggage set three calls deep stays visible to its parent and to the
+  siblings after it. Set with no span open it becomes a process-level default that later traces
+  inherit and restore to (`configure(defaults=...)` is the better tool for that) — and a process
+  that logs *without* `@trace` has no root span to release anything, so it needs
+  [`reset_context()`](#clearing-context-in-a-long-lived-process).
 - **`echo=True`** — *additionally* write a human-readable `LEVEL   message` line to the console
   (`sys.stderr` by default), synchronously, without waiting for the async flush. The event
   still rides the normal pipeline to the sink — echo never redirects.
@@ -303,6 +312,7 @@ def handler(event, context):
 | `current_traceparent()` | This span as a W3C `traceparent` string, or `None` if no span is active. |
 | `current_trace_context()` | `(trace_id, span_id)`, for when moving two fields beats moving a string. |
 | `current_baggage_header()` | Current baggage in W3C `baggage` format (`""` when empty). |
+| `reset_context()` | Clear baggage and any adopted context. `@trace` users do not need it. Never raises. |
 
 Details worth knowing:
 
@@ -327,10 +337,45 @@ Details worth knowing:
   join because one field was malformed is worse. Headers over 8192 bytes are rejected. Values
   are percent-encoded, so `,` `=` and non-ASCII round-trip; non-string values are serialized
   with `str()`, so a dict arrives as its repr.
+- **An adopted context is consumed by one root span.** It applies to the next root span opened
+  and does not survive it, so the invocation after it starts a fresh trace unless it adopts
+  again. That is what stops a warm container from logging every later invocation into the first
+  caller's trace. A batch that fans out to several *sibling* root spans therefore needs one
+  `continue_trace()` per item — or, better, one `@trace` entry point so the items are nested
+  spans of a single trace.
 - **Sampling is not honoured.** `traceparent`'s flags byte is parsed and ignored, and outbound
   is always `01`: this library records every span, so respecting another system's sampling
   decision would mean dropping them.
 
+#### Clearing context in a long-lived process
+
+`@trace` releases both baggage and the adopted context when the outermost decorated call returns
+or raises, so **most callers never need `reset_context()`**. It exists for the two cases where no
+root-span exit releases them in *your* context:
+
+```python
+lf.reset_context()      # clears baggage *and* any adopted trace context
+```
+
+- **You use the emitters without `@trace`.** An orphan log opens no span, so nothing releases
+  what `set_baggage()` or `continue_trace()` set. In a process that reuses one thread across
+  requests — the main thread, a pooled worker, a warm Lambda container — that state reaches the
+  next request. Call `reset_context()` when a unit of work ends. (An orphan log never joins an
+  adopted trace either: it mints its own `trace_id`, and the adoption simply waits to claim the
+  next root span, whenever one happens to run.)
+- **You adopt outside the span and dispatch into a task.** The release runs in whichever
+  context the root span's `finally` runs in, so `continue_trace()` here followed by
+  `asyncio.run(main())` clears the adoption in the task's copy of the context while this one
+  keeps it. `contextvars` has no way to write back to a parent context, so clear it yourself.
+  Adopting on the entry point's first line — the documented placement — is inside the span and
+  needs nothing.
+
+It clears rather than restores: a process-level baggage default set before any span is erased
+too — permanently when you call it outside a span. Prefer that. Called *inside* a span it also
+empties the `span.start` / `span.end` events of baggage, because those are stamped with the
+span's *final* baggage at close, and that span's exit then restores the pre-span baggage anyway,
+undoing the erasure. It never raises.
+
 ### Sinks
 
 A **sink** is the swappable output transport — any object satisfying the `Sink` protocol. It

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

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

{log_foundry-0.10.2.dev4 → log_foundry-0.10.2.dev6}/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.dev4 → log_foundry-0.10.2.dev6}/src/log_foundry/context.py

@@ -5,9 +5,30 @@ inherits its own copy — so ``log_foundry.info(...)`` can find "the span I'm in
 manual passing. This module holds a *stack* of active spans (the top is the current span and
 the parent of the next nested call) plus trace-scoped baggage.
 
+**The three variables and how long each lives** (SPEC-024 — before it, the last two lived as
+long as the context did, so one request's data reached the next request's events):
+
+``_span_stack``
+    One entry per active decorated call. Pushed on enter, popped in the ``finally`` on exit.
+
+``_baggage``
+    Restored to its pre-span value when the **root** span closes — the span opened when no
+    other was active. Nested spans do not reset, so baggage set three calls deep stays visible
+    to its parent and to later siblings in the same trace: that is what "trace-scoped" means.
+    Baggage set before any span is a process-level default and is restored *to*, not erased.
+
+``_adopted``
+    Cleared when the root span closes, and consumed by that one span — an inbound context is a
+    one-shot handoff to the trace it names, not a standing setting. Restoring it instead would
+    leave a warm container joining the first caller's trace forever.
+
+The last two are released together by :func:`pop_baggage_scope`; the span stack is released by
+:func:`pop_span`. A caller who opens no span clears both with :func:`reset_context`.
+
 Two footguns, both avoided below:
   * Never mutate a ContextVar's default mutable value — the ``()`` / ``{}`` defaults are shared
-    across all contexts. Always ``.set()`` a new tuple/dict.
+    across all contexts. Always ``.set()`` a new tuple/dict. The same applies to any value a
+    *parent* context can still see: emptying a baggage dict in place reaches back into it.
   * Use the token/``reset`` pattern, not a manual pop — ``reset(token)`` restores the exact
     prior state even when tasks branch.
 """
@@ -33,6 +54,7 @@ __all__ = [
     "pop_span",
     "push_baggage_scope",
     "push_span",
+    "reset_context",
     "set_baggage",
 ]
 
@@ -74,12 +96,25 @@ def pop_span(token: contextvars.Token[tuple[Span, ...]]) -> None:
 
 
 def get_baggage() -> dict[str, object]:
-    """Return the current trace's baggage (do not mutate the returned dict in place)."""
+    """Return the current trace's baggage (do not mutate the returned dict in place).
+
+    The trace's own keys are discarded when the enclosing **root** span closes, restoring the
+    baggage in effect before it — so a later trace sees only a process-level default set before
+    any span opened. With no span open at all nothing releases them and they accumulate for the
+    life of the context; :func:`reset_context` is the release on that path.
+    """
     return _baggage.get()
 
 
 def set_baggage(**kv: object) -> None:
-    """Merge key/values into the current trace's baggage (replaces with a new dict)."""
+    """Merge key/values into the current trace's baggage (replaces with a new dict).
+
+    The keys live until the enclosing **root** span closes, then the baggage in effect before
+    that span is restored — so they ride every event at or below this point in the trace and
+    none of the next trace's. Called with no span open they become a process-level default that
+    later traces inherit and restore to; :func:`reset_context` is what erases those, and
+    ``configure(defaults=...)`` is the better tool for setting them in the first place.
+    """
     _baggage.set({**_baggage.get(), **kv})
 
 
@@ -133,6 +168,38 @@ def pop_baggage_scope(token: contextvars.Token[dict[str, object]]) -> 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.dev4 → log_foundry-0.10.2.dev6}/src/log_foundry/decorator.py

@@ -120,6 +120,13 @@ def continue_trace(
     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.
 
+    One constraint on that release: it happens in whichever context the root span's ``finally``
+    runs in. Adopt here and then dispatch the span into a **child** context — any
+    ``asyncio.Task``, including the one ``asyncio.run`` creates — and the clear lands in the
+    copy while this context keeps the adoption. Calling this on the entry point's first line, as
+    above, is inside the span and unaffected; a caller who adopts before dispatching should call
+    :func:`~log_foundry.reset_context` when the work is done.
+
     ``baggage`` is a W3C ``baggage`` header merged into the current context. It succeeds or
     fails independently of the trace context.