log-foundry 0.2.1.dev4__tar.gz → 0.3.0__tar.gz

{log_foundry-0.2.1.dev4 → log_foundry-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: log-foundry
-Version: 0.2.1.dev4
+Version: 0.3.0
 Summary: Generate logs for your console and JSON events for downstream consumption.
 License-Expression: MIT
 License-File: LICENSE
@@ -298,6 +298,75 @@ def process_payment(user_id: int) -> str:
 - **Orphan logs** — a level call made with no active span is not dropped: it emits a standalone
   one-event span with a fresh `trace_id`, flushed straight to the sink.
 
+### Continuing a trace across processes
+
+A trace stops at the process boundary: `@trace` mints a fresh `trace_id` whenever no span is
+open, so two processes cooperating on one logical operation produce two unrelated traces. Pass
+the context across and they join up. Nothing here is serverless-specific — the same two calls
+join an HTTP client to its server, or a Celery caller to its worker.
+
+**The producer publishes where it is:**
+
+```python
+@lf.trace
+def enqueue_check(location: str) -> None:
+    sqs.send_message(
+        QueueUrl=QUEUE_URL,
+        MessageBody=json.dumps({
+            "location": location,
+            "traceparent": lf.current_traceparent(),      # "00-<trace_id>-<span_id>-01"
+            "baggage": lf.current_baggage_header(),       # "request_id=req-123,tenant=acme"
+        }),
+    )
+```
+
+**The consumer adopts it — one line, and make it the first line:**
+
+```python
+@lf.trace
+def handler(event, context):
+    lf.continue_trace(event.get("traceparent"), baggage=event.get("baggage"))
+    lf.info("inspecting")          # same trace_id as the producer; parent is its span
+    try:
+        return inspect(event)
+    finally:
+        lf.flush()
+```
+
+| Call | Does |
+|---|---|
+| `continue_trace(traceparent=None, *, trace_id=None, parent_span_id=None, baggage=None)` | Adopt an inbound context. `True` if adopted, `False` if nothing valid was supplied. Never raises. |
+| `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). |
+
+Details worth knowing:
+
+- **Call `continue_trace()` on the first line.** `@trace` opens the handler's span *before* the
+  body runs, so the call re-parents that span in place and rewrites the events it has already
+  buffered. A child span that already finished has been handed to the worker and can no longer
+  be moved.
+- **Only a root span is re-parented.** A nested span already belongs to an in-process trace, and
+  moving it would sever it from its own parent. The adopted context still applies to the next
+  root span opened in that context.
+- **Your `span_id` is never overwritten.** The adopting span keeps its own identity and takes the
+  inbound span as its `parent_span_id` — otherwise two processes would share a span id.
+- **`parent_span_id` may be omitted.** With only `trace_id` you join the trace as another root,
+  which beats being in a fresh trace when you know the trace but not the specific parent.
+- **Inbound context is untrusted and validated strictly** — 32/16 lowercase hex, all-zero ids
+  rejected, higher `traceparent` versions accepted per the W3C forward-compatibility rule.
+  Anything unusable is ignored with a single bounded warning on stderr and a fresh trace is
+  minted; a malformed id never reaches the event stream. Adopting a context grants **nothing**
+  — it selects a correlation id and confers no authority.
+- **Baggage fails independently of the trace.** A malformed `baggage` header is skipped with a
+  warning while the trace is still adopted: losing correlating fields is bad, losing the trace
+  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.
+- **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.
+
 ### Sinks
 
 A **sink** is the swappable output transport — any object satisfying the `Sink` protocol. It
@@ -561,9 +630,9 @@ def handler(event, context):
                         # later invocation on this warm container would log nothing.
 ```
 
-Note that each invocation is its own trace: trace context does not cross a process boundary
-today, so N invocations produce N `trace_id`s. Correlate them with a shared
-[`set_baggage`](#logging-inside-a-span) field until cross-process continuation ships.
+By default each invocation is its own trace, so N invocations produce N `trace_id`s. To join
+them into one — a step function, a producer and its consumer — pass the context across with
+[`continue_trace()`](#continuing-a-trace-across-processes).
 
 ## Event schema
 

{log_foundry-0.2.1.dev4 → log_foundry-0.3.0}/README.md

@@ -262,6 +262,75 @@ def process_payment(user_id: int) -> str:
 - **Orphan logs** — a level call made with no active span is not dropped: it emits a standalone
   one-event span with a fresh `trace_id`, flushed straight to the sink.
 
+### Continuing a trace across processes
+
+A trace stops at the process boundary: `@trace` mints a fresh `trace_id` whenever no span is
+open, so two processes cooperating on one logical operation produce two unrelated traces. Pass
+the context across and they join up. Nothing here is serverless-specific — the same two calls
+join an HTTP client to its server, or a Celery caller to its worker.
+
+**The producer publishes where it is:**
+
+```python
+@lf.trace
+def enqueue_check(location: str) -> None:
+    sqs.send_message(
+        QueueUrl=QUEUE_URL,
+        MessageBody=json.dumps({
+            "location": location,
+            "traceparent": lf.current_traceparent(),      # "00-<trace_id>-<span_id>-01"
+            "baggage": lf.current_baggage_header(),       # "request_id=req-123,tenant=acme"
+        }),
+    )
+```
+
+**The consumer adopts it — one line, and make it the first line:**
+
+```python
+@lf.trace
+def handler(event, context):
+    lf.continue_trace(event.get("traceparent"), baggage=event.get("baggage"))
+    lf.info("inspecting")          # same trace_id as the producer; parent is its span
+    try:
+        return inspect(event)
+    finally:
+        lf.flush()
+```
+
+| Call | Does |
+|---|---|
+| `continue_trace(traceparent=None, *, trace_id=None, parent_span_id=None, baggage=None)` | Adopt an inbound context. `True` if adopted, `False` if nothing valid was supplied. Never raises. |
+| `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). |
+
+Details worth knowing:
+
+- **Call `continue_trace()` on the first line.** `@trace` opens the handler's span *before* the
+  body runs, so the call re-parents that span in place and rewrites the events it has already
+  buffered. A child span that already finished has been handed to the worker and can no longer
+  be moved.
+- **Only a root span is re-parented.** A nested span already belongs to an in-process trace, and
+  moving it would sever it from its own parent. The adopted context still applies to the next
+  root span opened in that context.
+- **Your `span_id` is never overwritten.** The adopting span keeps its own identity and takes the
+  inbound span as its `parent_span_id` — otherwise two processes would share a span id.
+- **`parent_span_id` may be omitted.** With only `trace_id` you join the trace as another root,
+  which beats being in a fresh trace when you know the trace but not the specific parent.
+- **Inbound context is untrusted and validated strictly** — 32/16 lowercase hex, all-zero ids
+  rejected, higher `traceparent` versions accepted per the W3C forward-compatibility rule.
+  Anything unusable is ignored with a single bounded warning on stderr and a fresh trace is
+  minted; a malformed id never reaches the event stream. Adopting a context grants **nothing**
+  — it selects a correlation id and confers no authority.
+- **Baggage fails independently of the trace.** A malformed `baggage` header is skipped with a
+  warning while the trace is still adopted: losing correlating fields is bad, losing the trace
+  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.
+- **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.
+
 ### Sinks
 
 A **sink** is the swappable output transport — any object satisfying the `Sink` protocol. It
@@ -525,9 +594,9 @@ def handler(event, context):
                         # later invocation on this warm container would log nothing.
 ```
 
-Note that each invocation is its own trace: trace context does not cross a process boundary
-today, so N invocations produce N `trace_id`s. Correlate them with a shared
-[`set_baggage`](#logging-inside-a-span) field until cross-process continuation ships.
+By default each invocation is its own trace, so N invocations produce N `trace_id`s. To join
+them into one — a step function, a producer and its consumer — pass the context across with
+[`continue_trace()`](#continuing-a-trace-across-processes).
 
 ## Event schema
 

{log_foundry-0.2.1.dev4 → log_foundry-0.3.0}/pyproject.toml

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

{log_foundry-0.2.1.dev4 → log_foundry-0.3.0}/src/log_foundry/__init__.py

@@ -1,8 +1,10 @@
 """log_foundry — consistent, structured logs per decorated function call.
 
 Public façade (module-function shape). Exposes configuration, the ``@trace`` decorator, the
-``debug/info/warning/error/critical`` emitters, ``set_baggage``, ``flush`` (drain and keep
-logging) and ``shutdown`` (drain, close the sink, and stop).
+``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).
 """
 
 from importlib.metadata import PackageNotFoundError
@@ -10,7 +12,12 @@ from importlib.metadata import version as _dist_version
 
 from log_foundry.api import critical, debug, error, info, set_baggage, warning
 from log_foundry.config import configure, get_config
-from log_foundry.decorator import trace
+from log_foundry.context import (
+    current_baggage_header,
+    current_trace_context,
+    current_traceparent,
+)
+from log_foundry.decorator import continue_trace, trace
 
 try:
     # Distribution name ("log-foundry") differs from the import name ("log_foundry").
@@ -67,6 +74,10 @@ __all__ = [
     "error",
     "critical",
     "set_baggage",
+    "continue_trace",
+    "current_traceparent",
+    "current_trace_context",
+    "current_baggage_header",
     "flush",
     "shutdown",
     "__version__",

log_foundry-0.3.0/src/log_foundry/context.py

@@ -0,0 +1,160 @@
+"""Context propagation: span stack + baggage via contextvars (arch §5, guide Phase 4).
+
+``contextvars`` (not thread-locals) is correct under both threads and asyncio — each task
+inherits its own copy — so ``log_foundry.info(...)`` can find "the span I'm inside" with no
+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.
+
+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.
+  * Use the token/``reset`` pattern, not a manual pop — ``reset(token)`` restores the exact
+    prior state even when tasks branch.
+"""
+
+from __future__ import annotations
+
+import contextvars
+from typing import TYPE_CHECKING
+from urllib.parse import quote, unquote
+
+from log_foundry.ids import format_traceparent
+
+if TYPE_CHECKING:
+    from log_foundry.model import Span
+
+__all__ = [
+    "current_span",
+    "push_span",
+    "pop_span",
+    "get_baggage",
+    "set_baggage",
+    "current_traceparent",
+    "current_trace_context",
+    "current_baggage_header",
+]
+
+_span_stack: contextvars.ContextVar[tuple[Span, ...]] = contextvars.ContextVar(
+    "log_foundry_span_stack", default=()
+)
+_baggage: contextvars.ContextVar[dict[str, object]] = contextvars.ContextVar(
+    "log_foundry_baggage", default={}
+)
+# An inbound trace context adopted via ``continue_trace`` (SPEC-014), applied by ``_open_span``
+# to the next *root* span. A ContextVar for the same reason as the two above: it is then correct
+# under threads and asyncio for free, and a task that adopts a context cannot leak it to siblings.
+_adopted: contextvars.ContextVar[tuple[str, str | None] | None] = contextvars.ContextVar(
+    "log_foundry_adopted_context", default=None
+)
+
+# W3C suggests 8192 bytes for the whole `baggage` header. Bounded on the way in so a hostile or
+# runaway header cannot inflate every subsequent event emitted by this process.
+BAGGAGE_MAX_BYTES = 8192
+
+
+def current_span() -> Span | None:
+    """Return the innermost active span, or ``None`` when no span is active."""
+    stack = _span_stack.get()
+    return stack[-1] if stack else None
+
+
+def push_span(span: Span) -> contextvars.Token[tuple[Span, ...]]:
+    """Push ``span`` onto the stack; return a token to hand back to :func:`pop_span`."""
+    return _span_stack.set((*_span_stack.get(), 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)
+
+
+def get_baggage() -> dict[str, object]:
+    """Return the current trace's baggage (do not mutate the returned dict in place)."""
+    return _baggage.get()
+
+
+def set_baggage(**kv: object) -> None:
+    """Merge key/values into the current trace's baggage (replaces with a new dict)."""
+    _baggage.set({**_baggage.get(), **kv})
+
+
+# -- adopted inbound context (SPEC-014) --------------------------------------------------
+
+
+def get_adopted_context() -> tuple[str, str | None] | None:
+    """Return the adopted ``(trace_id, parent_span_id)``, or ``None`` if none was adopted."""
+    return _adopted.get()
+
+
+def set_adopted_context(trace_id: str, parent_span_id: str | None) -> None:
+    """Record an inbound trace context for the next root span opened in this context."""
+    _adopted.set((trace_id, parent_span_id))
+
+
+# -- the producer side: publish where this process is ------------------------------------
+
+
+def current_traceparent() -> str | None:
+    """Return the current span as a W3C ``traceparent`` string, or ``None`` if none is active."""
+    span = current_span()
+    return format_traceparent(span.trace_id, span.span_id) if span else None
+
+
+def current_trace_context() -> tuple[str, str] | None:
+    """Return ``(trace_id, span_id)`` for the current span, or ``None`` if none is active.
+
+    For callers who would rather move two fields than a formatted string — a Step Functions
+    payload, a queue message attribute. It exists so nobody is pushed into
+    :func:`current_span`, which is internal and hands back a mutable :class:`~.model.Span`.
+    """
+    span = current_span()
+    return (span.trace_id, span.span_id) if span else None
+
+
+# -- the W3C `baggage` header codec ------------------------------------------------------
+
+
+def current_baggage_header() -> str:
+    """Return the current baggage in W3C ``baggage`` header format (``""`` when empty).
+
+    The baggage store is ``dict[str, object]`` but the wire format is text, so **non-string
+    values are serialized with ``str()``** — put a dict in baggage and it arrives at the next
+    process as its repr, not as a dict. Keys and values are percent-encoded, so a value
+    containing ``,``, ``=`` or non-ASCII round-trips through :func:`parse_baggage_header`.
+    """
+    return format_baggage_header(get_baggage())
+
+
+def format_baggage_header(baggage: dict[str, object]) -> str:
+    """Serialize a baggage mapping to the W3C ``key1=value1,key2=value2`` format."""
+    # safe="" so the separators themselves (`,` `=` `;`) are encoded rather than corrupting the
+    # framing — the whole reason a value containing a comma can survive the hop.
+    return ",".join(f"{quote(k, safe='')}={quote(str(v), safe='')}" for k, v in baggage.items())
+
+
+def parse_baggage_header(header: object) -> dict[str, object] | None:
+    """Parse a W3C ``baggage`` header into a mapping, or ``None`` if it is unusable.
+
+    Total, like the ``traceparent`` parser: the header arrives from outside the process. Returns
+    ``None`` for a non-string, an empty header, one over :data:`BAGGAGE_MAX_BYTES`, or a
+    malformed member — never a partial parse, which would silently drop correlating fields.
+    """
+    if not isinstance(header, str) or not header.strip():
+        return None
+    if len(header.encode("utf-8", "replace")) > BAGGAGE_MAX_BYTES:
+        return None
+    parsed: dict[str, object] = {}
+    for member in header.split(","):
+        # W3C allows per-member properties after a `;` (e.g. `k=v;metadata`). Nothing here
+        # consumes them, so they are dropped rather than treated as part of the value.
+        entry = member.split(";", 1)[0].strip()
+        if not entry:
+            continue
+        key, sep, value = entry.partition("=")
+        if not sep:
+            return None
+        key = unquote(key.strip())
+        if not key:
+            return None
+        parsed[key] = unquote(value.strip())
+    return parsed or None

log_foundry-0.3.0/src/log_foundry/decorator.py

@@ -0,0 +1,312 @@
+"""The ``@trace`` decorator — synchronous and async (arch §4–5, guide Phases 6, 8).
+
+Opens a span on enter and closes it on exit (success *or* exception), maintaining the
+trace/parent hierarchy from the context stack, then flushes the finished span straight to
+the configured sink. The decorator is **non-swallowing**: it records the failure and
+re-raises the original exception unchanged (arch §4).
+
+At decoration time :func:`asyncio.iscoroutinefunction` selects a sync or async wrapper. The
+two are deliberate near-duplicates — the only difference is ``await fn(...)`` — because the
+sync/async split is a hard boundary; ``contextvars`` already propagates the span stack and
+baggage correctly across ``await`` points and concurrent tasks (arch §5), so the async span
+opens when the coroutine actually runs and closes when it finishes, with no new machinery.
+
+Flushing is synchronous here; the background worker (SPEC-004) later swaps only
+:func:`_flush` for a non-blocking handoff — the lifecycle below is untouched.
+
+:func:`continue_trace` (SPEC-014) lives here rather than in ``api`` because it is the other half
+of :func:`_open_span`'s hierarchy rules: it decides which trace the *next* root span joins, and
+re-parents an already-open one. The ``traceparent`` codec it validates with stays in ``ids``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import atexit
+import functools
+import sys
+import threading
+from collections.abc import Callable
+from time import monotonic
+from typing import Any, TypeVar, cast, overload
+
+from log_foundry import context
+from log_foundry.config import _ensure_sink
+from log_foundry.ids import (
+    is_valid_span_id,
+    is_valid_trace_id,
+    new_span_id,
+    new_trace_id,
+    parse_traceparent,
+)
+from log_foundry.model import Span, end_event, start_event
+from log_foundry.worker import Worker
+
+__all__ = ["trace", "continue_trace"]
+
+# Bound on how much of a rejected inbound value is echoed into a stderr warning.
+_MAX_REJECTED_ECHO = 64
+
+# One background worker per process (SPEC-004), created lazily from the configured sink on the
+# first flush. The double-checked lock makes concurrent first-flushes create exactly one.
+_worker: Worker | None = None
+_worker_lock = threading.Lock()
+_atexit_registered = False  # register the drain exactly once per process, not per worker
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def _open_span(name: str, defaults: dict[str, object] | None) -> Span:
+    """Mint a span, inheriting the trace/parent from the current context (arch §3).
+
+    An inbound context adopted via :func:`continue_trace` is consulted **only** when no span is
+    open (SPEC-014 FR-001): a nested call still inherits from its in-process parent, because
+    moving it to the inbound span would sever it from the parent it actually ran inside.
+    """
+    parent = context.current_span()
+    trace_id: str
+    parent_span_id: str | None
+    if parent is not None:
+        trace_id, parent_span_id = parent.trace_id, parent.span_id
+    else:
+        adopted = context.get_adopted_context()
+        trace_id, parent_span_id = adopted if adopted else (new_trace_id(), None)
+    span = Span(
+        trace_id=trace_id,
+        span_id=new_span_id(),
+        parent_span_id=parent_span_id,
+        name=name,
+        start_ts=monotonic(),
+        defaults=defaults or {},
+    )
+    span.events.append(start_event(span))
+    return span
+
+
+def _warn_rejected(reason: str, value: object) -> None:
+    """Report a rejected inbound context on stderr, as ``worker`` and ``SQSSink`` do.
+
+    The offending value is echoed only as a **bounded ``repr``**. Unbounded is a log-injection
+    surface — the value is attacker-controllable, and `repr` additionally escapes newlines and
+    control characters so it cannot forge a second log line in an operator's console.
+    """
+    shown = repr(value)
+    if len(shown) > _MAX_REJECTED_ECHO:
+        shown = shown[:_MAX_REJECTED_ECHO] + "…"
+    sys.stderr.write(f"log-foundry: ignoring inbound trace context ({reason}): {shown}\n")
+
+
+def continue_trace(
+    traceparent: str | None = None,
+    *,
+    trace_id: str | None = None,
+    parent_span_id: str | None = None,
+    baggage: str | None = None,
+) -> bool:
+    """Adopt an inbound trace context so this process's spans join the caller's trace.
+
+    Accepts a W3C ``traceparent`` string or the ids directly. **If a span is already open and
+    it is a root** (``parent_span_id is None`` — the ``@trace``-decorated entry point calling
+    this on its first line), that span is re-parented in place and its buffered events are
+    rewritten to match. A span that is *not* a root is left alone; a call with no span open
+    re-parents nothing. In every case the context applies to the next root span opened here.
+
+    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.
+
+    ``baggage`` is a W3C ``baggage`` header merged into the current context. It succeeds or
+    fails independently of the trace context.
+
+    Returns ``True`` when a context was adopted, ``False`` when nothing valid was supplied and
+    a fresh trace is in use. Never raises.
+
+    Adopting a context grants **nothing** — it selects a correlation id and confers no
+    authority. The validation below is about output integrity (never emitting a malformed id
+    into the event stream), not authorization; this is not a trust boundary.
+    """
+    adopted: tuple[str, str | None] | None = None
+    if traceparent is not None:
+        if trace_id is not None or parent_span_id is not None:
+            # A programming error, not bad input: the caller supplied the same thing twice.
+            _warn_rejected("both traceparent and explicit ids given; traceparent wins", traceparent)
+        parsed = parse_traceparent(traceparent)
+        if parsed is None:
+            _warn_rejected("unparseable traceparent", traceparent)
+        else:
+            adopted = parsed
+    elif trace_id is not None:
+        if not is_valid_trace_id(trace_id):
+            _warn_rejected("invalid trace_id", trace_id)
+        elif parent_span_id is not None and not is_valid_span_id(parent_span_id):
+            # Drop just the parent and join as another root rather than reject the whole
+            # context: being in the right trace without a parent beats being in a fresh one.
+            _warn_rejected("invalid parent_span_id; joining as a root", parent_span_id)
+            adopted = (trace_id, None)
+        else:
+            # parent_span_id may legitimately be omitted — a consumer that knows the trace but
+            # not the specific parent span is better off in the right trace than a fresh one.
+            adopted = (trace_id, parent_span_id)
+    # Nothing supplied at all is a silent no-op, not a rejection: `event.get("traceparent")`
+    # legitimately yields None whenever the caller did not propagate one, and warning on that
+    # would write a line on every uninstrumented invocation.
+
+    if adopted is not None:
+        context.set_adopted_context(*adopted)
+        _reparent_current_span(*adopted)
+
+    if baggage is not None:
+        parsed_baggage = context.parse_baggage_header(baggage)
+        if parsed_baggage is None:
+            # Deliberately independent of the trace context above: losing correlating fields is
+            # bad, and losing the trace join because one field was malformed is worse.
+            _warn_rejected("unusable baggage header", baggage)
+        else:
+            context.set_baggage(**parsed_baggage)
+
+    return adopted is not None
+
+
+def _reparent_current_span(trace_id: str, parent_span_id: str | None) -> None:
+    """Move an already-open **root** span into the adopted trace, events included.
+
+    ``@trace`` opened the entry point's span before its body ran, so by the time
+    :func:`continue_trace` is called on the first line that span already exists *and* has its
+    ``span.start`` event buffered. :func:`~log_foundry.model.build_event` **snapshots** the ids
+    into each event dict, so re-parenting only the dataclass would leave the buffered start
+    event on the old trace — one span emitting its start on trace A and its end on trace B. A
+    split trace is worse than no continuation at all, because it looks like data rather than a
+    bug.
+    """
+    span = context.current_span()
+    if span is None or span.parent_span_id is not None:
+        # Not a root: it already belongs to an in-process trace, and moving it would sever it
+        # from its own parent. The adopted context still applies to the next root span.
+        return
+    span.trace_id = trace_id
+    span.parent_span_id = parent_span_id
+    for event in span.events:
+        event["trace_id"] = trace_id
+        # `span_id` is never overwritten — the adopting span keeps its own identity and takes
+        # the inbound span as its parent. Overwriting would give two processes the same span id
+        # and break parent/child reconstruction downstream.
+        if event.get("span_id") == span.span_id:
+            event["parent_span_id"] = parent_span_id
+
+
+def _get_worker() -> Worker:
+    """Return the process worker, creating it lazily from the configured sink (FR-006).
+
+    Registers the graceful drain via ``atexit`` exactly once, on first creation, so a program
+    that logs and exits immediately still flushes its buffered events.
+    """
+    global _worker, _atexit_registered
+    if _worker is None:
+        with _worker_lock:
+            if _worker is None:
+                if not _atexit_registered:
+                    atexit.register(_shutdown_worker)
+                    _atexit_registered = True
+                _worker = Worker(_ensure_sink())
+    return _worker
+
+
+def _shutdown_worker() -> None:
+    """Drain + close the process worker if one was created (idempotent). Backs ``shutdown()``."""
+    if _worker is not None:
+        _worker.shutdown()
+
+
+def _flush_worker(timeout: float | None = 5.0) -> bool:
+    """Drain the process worker without retiring it. Backs ``flush()`` (SPEC-013 FR-003).
+
+    Returns ``True`` when no worker exists: a process that never logged has nothing to drain,
+    and building one here — with the thread and ``atexit`` registration :func:`_get_worker`
+    brings — in order to flush nothing would be pure cost. So this deliberately does *not* call
+    :func:`_get_worker`.
+    """
+    worker = _worker
+    if worker is None:
+        return True
+    try:
+        return worker.flush(timeout)
+    except Exception:  # noqa: BLE001 — a flush is the call most likely to be made in a
+        # `finally`, so the library must never be the reason a caller's function fails. Any
+        # failure is reported by the return value instead (FR-003).
+        return False
+
+
+def _flush(span: Span) -> None:
+    """Hand the finished span's events to the background worker — non-blocking (FR-001).
+
+    Resolves/creates the worker via :func:`_get_worker` (whose sink comes from ``_ensure_sink``,
+    so a zero-config ``@trace`` still falls back to ``StdoutSink`` rather than crashing).
+    """
+    _get_worker().submit(span.events)
+
+
+def _close_span(span: Span, status: str, exc: BaseException | None) -> None:
+    """Append the end event (so the flushed queue is complete), then flush."""
+    span.events.append(end_event(span, status, exc))
+    _flush(span)
+
+
+@overload
+def trace(func: F) -> F: ...
+@overload
+def trace(
+    *, name: str | None = ..., defaults: dict[str, object] | None = ...
+) -> Callable[[F], F]: ...
+
+
+def trace(
+    func: F | None = None,
+    *,
+    name: str | None = None,
+    defaults: dict[str, object] | None = None,
+) -> F | Callable[[F], F]:
+    """Trace a function call as a span. Usable bare (``@trace``) or with args.
+
+    ``@trace(name=..., defaults=...)`` overrides the span name (default:
+    ``func.__qualname__``) and adds per-decorator default fields.
+    """
+
+    def decorate(fn: F) -> F:
+        if asyncio.iscoroutinefunction(fn):
+
+            @functools.wraps(fn)
+            async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+                span = _open_span(name or fn.__qualname__, defaults)
+                token = context.push_span(span)
+                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.
+                    # 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)
+                    raise
+                finally:
+                    context.pop_span(token)
+
+            return cast(F, async_wrapper)
+
+        @functools.wraps(fn)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            span = _open_span(name or fn.__qualname__, defaults)
+            token = context.push_span(span)
+            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)
+                raise
+            finally:
+                context.pop_span(token)
+
+        return cast(F, wrapper)
+
+    return decorate(func) if func is not None else decorate

log_foundry-0.3.0/src/log_foundry/ids.py

@@ -0,0 +1,109 @@
+"""W3C Trace Context-compatible id generation and ``traceparent`` codec (arch §3.1, §12).
+
+``trace_id`` and ``span_id`` use the W3C wire formats (not arbitrary UUIDs) so adopting an
+inbound request's trace is just a header parse and the emitted records stay compatible with
+standard distributed-tracing tooling. ``log_id`` is internal-only, so a UUID is fine.
+
+SPEC-014 cashes that in: the ``traceparent`` parser and formatter live here, beside the
+generators whose formats they mirror, so the definition of "a valid trace id" has exactly one
+home. Everything here is **total** — the parser takes ``object`` and returns ``None`` rather than
+raising, because its input arrives from outside the process and a logging call must never be the
+reason a caller's function fails.
+"""
+
+from __future__ import annotations
+
+import os
+import uuid
+
+__all__ = [
+    "new_trace_id",
+    "new_span_id",
+    "new_log_id",
+    "parse_traceparent",
+    "format_traceparent",
+    "is_valid_trace_id",
+    "is_valid_span_id",
+]
+
+_HEX = frozenset("0123456789abcdef")
+
+# W3C: the sampled bit. This library records every span, so "sampled" is always true. An
+# *inbound* flags byte is deliberately never round-tripped — honouring another system's sampling
+# decision would mean dropping spans, which this library does not do (arch §10).
+_FLAGS_SAMPLED = "01"
+
+_VERSION = "00"
+# Version ff is reserved and invalid per the W3C spec — it is not a "higher version".
+_INVALID_VERSION = "ff"
+
+
+def new_trace_id() -> str:
+    """Return a fresh trace id: 32 lowercase hex chars (16 random bytes)."""
+    return os.urandom(16).hex()
+
+
+def new_span_id() -> str:
+    """Return a fresh span id: 16 lowercase hex chars (8 random bytes)."""
+    return os.urandom(8).hex()
+
+
+def new_log_id() -> str:
+    """Return a fresh log id: a UUID4 hex string (internal-only, format is our choice)."""
+    return uuid.uuid4().hex
+
+
+def _is_hex(value: str, length: int) -> bool:
+    """True when ``value`` is exactly ``length`` *lowercase* hex characters.
+
+    Uppercase is rejected rather than normalized: the W3C formats are defined as lowercase, and
+    silently accepting ``4BF9...`` here would let a non-conforming id reach the event stream.
+    """
+    return len(value) == length and not (set(value) - _HEX)
+
+
+def is_valid_trace_id(value: object) -> bool:
+    """True for a W3C-valid trace id: exactly 32 lowercase hex chars, not all zero."""
+    # All-zero is explicitly invalid per the W3C spec — it is the "unset" sentinel, not an id.
+    return isinstance(value, str) and _is_hex(value, 32) and value != "0" * 32
+
+
+def is_valid_span_id(value: object) -> bool:
+    """True for a W3C-valid span id: exactly 16 lowercase hex chars, not all zero."""
+    return isinstance(value, str) and _is_hex(value, 16) and value != "0" * 16
+
+
+def parse_traceparent(value: object) -> tuple[str, str] | None:
+    """Parse a W3C ``traceparent`` into ``(trace_id, span_id)``, or ``None`` if unusable.
+
+    The format is ``version-trace_id-span_id-flags``, e.g.
+    ``00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01``. Takes ``object`` and never
+    raises: the value arrives from outside the process and may be any type at all.
+
+    The returned ``span_id`` is the *caller's* span — the adopting span's parent, never its own
+    identity. ``flags`` is parsed for validity and then ignored (see ``_FLAGS_SAMPLED``).
+    """
+    if not isinstance(value, str):
+        return None
+    parts = value.strip().split("-")
+    if len(parts) < 4:
+        return None
+    version, trace_id, span_id, flags = parts[0], parts[1], parts[2], parts[3]
+    if not _is_hex(version, 2) or version == _INVALID_VERSION:
+        return None
+    if version == _VERSION:
+        # Version 00 is defined as exactly four fields; a trailing field is malformed, not a
+        # forward-compatible extension.
+        if len(parts) != 4 or not _is_hex(flags, 2):
+            return None
+    # A *higher* version is deliberately not rejected. The W3C forward-compatibility rule says to
+    # parse the first three fields and ignore any extra ones — "reject anything that isn't 00" is
+    # the intuitive-and-wrong reading, and would strand us the moment version 01 ships.
+    if not is_valid_trace_id(trace_id) or not is_valid_span_id(span_id):
+        return None
+    return trace_id, span_id
+
+
+def format_traceparent(trace_id: str, span_id: str) -> str:
+    """Format ``(trace_id, span_id)`` as a version-``00`` W3C ``traceparent`` string."""
+    return f"{_VERSION}-{trace_id}-{span_id}-{_FLAGS_SAMPLED}"

log_foundry-0.2.1.dev4/src/log_foundry/context.py

@@ -1,62 +0,0 @@
-"""Context propagation: span stack + baggage via contextvars (arch §5, guide Phase 4).
-
-``contextvars`` (not thread-locals) is correct under both threads and asyncio — each task
-inherits its own copy — so ``log_foundry.info(...)`` can find "the span I'm inside" with no
-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.
-
-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.
-  * Use the token/``reset`` pattern, not a manual pop — ``reset(token)`` restores the exact
-    prior state even when tasks branch.
-"""
-
-from __future__ import annotations
-
-import contextvars
-from typing import TYPE_CHECKING
-
-if TYPE_CHECKING:
-    from log_foundry.model import Span
-
-__all__ = [
-    "current_span",
-    "push_span",
-    "pop_span",
-    "get_baggage",
-    "set_baggage",
-]
-
-_span_stack: contextvars.ContextVar[tuple[Span, ...]] = contextvars.ContextVar(
-    "log_foundry_span_stack", default=()
-)
-_baggage: contextvars.ContextVar[dict[str, object]] = contextvars.ContextVar(
-    "log_foundry_baggage", default={}
-)
-
-
-def current_span() -> Span | None:
-    """Return the innermost active span, or ``None`` when no span is active."""
-    stack = _span_stack.get()
-    return stack[-1] if stack else None
-
-
-def push_span(span: Span) -> contextvars.Token[tuple[Span, ...]]:
-    """Push ``span`` onto the stack; return a token to hand back to :func:`pop_span`."""
-    return _span_stack.set((*_span_stack.get(), 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)
-
-
-def get_baggage() -> dict[str, object]:
-    """Return the current trace's baggage (do not mutate the returned dict in place)."""
-    return _baggage.get()
-
-
-def set_baggage(**kv: object) -> None:
-    """Merge key/values into the current trace's baggage (replaces with a new dict)."""
-    _baggage.set({**_baggage.get(), **kv})

log_foundry-0.2.1.dev4/src/log_foundry/decorator.py

@@ -1,176 +0,0 @@
-"""The ``@trace`` decorator — synchronous and async (arch §4–5, guide Phases 6, 8).
-
-Opens a span on enter and closes it on exit (success *or* exception), maintaining the
-trace/parent hierarchy from the context stack, then flushes the finished span straight to
-the configured sink. The decorator is **non-swallowing**: it records the failure and
-re-raises the original exception unchanged (arch §4).
-
-At decoration time :func:`asyncio.iscoroutinefunction` selects a sync or async wrapper. The
-two are deliberate near-duplicates — the only difference is ``await fn(...)`` — because the
-sync/async split is a hard boundary; ``contextvars`` already propagates the span stack and
-baggage correctly across ``await`` points and concurrent tasks (arch §5), so the async span
-opens when the coroutine actually runs and closes when it finishes, with no new machinery.
-
-Flushing is synchronous here; the background worker (SPEC-004) later swaps only
-:func:`_flush` for a non-blocking handoff — the lifecycle below is untouched.
-"""
-
-from __future__ import annotations
-
-import asyncio
-import atexit
-import functools
-import threading
-from collections.abc import Callable
-from time import monotonic
-from typing import Any, TypeVar, cast, overload
-
-from log_foundry import context
-from log_foundry.config import _ensure_sink
-from log_foundry.ids import new_span_id, new_trace_id
-from log_foundry.model import Span, end_event, start_event
-from log_foundry.worker import Worker
-
-__all__ = ["trace"]
-
-# One background worker per process (SPEC-004), created lazily from the configured sink on the
-# first flush. The double-checked lock makes concurrent first-flushes create exactly one.
-_worker: Worker | None = None
-_worker_lock = threading.Lock()
-_atexit_registered = False  # register the drain exactly once per process, not per worker
-
-F = TypeVar("F", bound=Callable[..., Any])
-
-
-def _open_span(name: str, defaults: dict[str, object] | None) -> Span:
-    """Mint a span, inheriting the trace/parent from the current context (arch §3)."""
-    parent = context.current_span()
-    span = Span(
-        trace_id=parent.trace_id if parent else new_trace_id(),
-        span_id=new_span_id(),
-        parent_span_id=parent.span_id if parent else None,
-        name=name,
-        start_ts=monotonic(),
-        defaults=defaults or {},
-    )
-    span.events.append(start_event(span))
-    return span
-
-
-def _get_worker() -> Worker:
-    """Return the process worker, creating it lazily from the configured sink (FR-006).
-
-    Registers the graceful drain via ``atexit`` exactly once, on first creation, so a program
-    that logs and exits immediately still flushes its buffered events.
-    """
-    global _worker, _atexit_registered
-    if _worker is None:
-        with _worker_lock:
-            if _worker is None:
-                if not _atexit_registered:
-                    atexit.register(_shutdown_worker)
-                    _atexit_registered = True
-                _worker = Worker(_ensure_sink())
-    return _worker
-
-
-def _shutdown_worker() -> None:
-    """Drain + close the process worker if one was created (idempotent). Backs ``shutdown()``."""
-    if _worker is not None:
-        _worker.shutdown()
-
-
-def _flush_worker(timeout: float | None = 5.0) -> bool:
-    """Drain the process worker without retiring it. Backs ``flush()`` (SPEC-013 FR-003).
-
-    Returns ``True`` when no worker exists: a process that never logged has nothing to drain,
-    and building one here — with the thread and ``atexit`` registration :func:`_get_worker`
-    brings — in order to flush nothing would be pure cost. So this deliberately does *not* call
-    :func:`_get_worker`.
-    """
-    worker = _worker
-    if worker is None:
-        return True
-    try:
-        return worker.flush(timeout)
-    except Exception:  # noqa: BLE001 — a flush is the call most likely to be made in a
-        # `finally`, so the library must never be the reason a caller's function fails. Any
-        # failure is reported by the return value instead (FR-003).
-        return False
-
-
-def _flush(span: Span) -> None:
-    """Hand the finished span's events to the background worker — non-blocking (FR-001).
-
-    Resolves/creates the worker via :func:`_get_worker` (whose sink comes from ``_ensure_sink``,
-    so a zero-config ``@trace`` still falls back to ``StdoutSink`` rather than crashing).
-    """
-    _get_worker().submit(span.events)
-
-
-def _close_span(span: Span, status: str, exc: BaseException | None) -> None:
-    """Append the end event (so the flushed queue is complete), then flush."""
-    span.events.append(end_event(span, status, exc))
-    _flush(span)
-
-
-@overload
-def trace(func: F) -> F: ...
-@overload
-def trace(
-    *, name: str | None = ..., defaults: dict[str, object] | None = ...
-) -> Callable[[F], F]: ...
-
-
-def trace(
-    func: F | None = None,
-    *,
-    name: str | None = None,
-    defaults: dict[str, object] | None = None,
-) -> F | Callable[[F], F]:
-    """Trace a function call as a span. Usable bare (``@trace``) or with args.
-
-    ``@trace(name=..., defaults=...)`` overrides the span name (default:
-    ``func.__qualname__``) and adds per-decorator default fields.
-    """
-
-    def decorate(fn: F) -> F:
-        if asyncio.iscoroutinefunction(fn):
-
-            @functools.wraps(fn)
-            async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
-                span = _open_span(name or fn.__qualname__, defaults)
-                token = context.push_span(span)
-                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.
-                    # 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)
-                    raise
-                finally:
-                    context.pop_span(token)
-
-            return cast(F, async_wrapper)
-
-        @functools.wraps(fn)
-        def wrapper(*args: Any, **kwargs: Any) -> Any:
-            span = _open_span(name or fn.__qualname__, defaults)
-            token = context.push_span(span)
-            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)
-                raise
-            finally:
-                context.pop_span(token)
-
-        return cast(F, wrapper)
-
-    return decorate(func) if func is not None else decorate

log_foundry-0.2.1.dev4/src/log_foundry/ids.py

@@ -1,29 +0,0 @@
-"""W3C Trace Context-compatible id generation (arch §3.1, guide Phase 2).
-
-``trace_id`` and ``span_id`` use the W3C wire formats (not arbitrary UUIDs) so a future
-"adopt the inbound request's trace" feature is just a header parse (arch §12) and the
-emitted records stay compatible with standard distributed-tracing tooling. ``log_id`` is
-internal-only, so a UUID is fine.
-"""
-
-from __future__ import annotations
-
-import os
-import uuid
-
-__all__ = ["new_trace_id", "new_span_id", "new_log_id"]
-
-
-def new_trace_id() -> str:
-    """Return a fresh trace id: 32 lowercase hex chars (16 random bytes)."""
-    return os.urandom(16).hex()
-
-
-def new_span_id() -> str:
-    """Return a fresh span id: 16 lowercase hex chars (8 random bytes)."""
-    return os.urandom(8).hex()
-
-
-def new_log_id() -> str:
-    """Return a fresh log id: a UUID4 hex string (internal-only, format is our choice)."""
-    return uuid.uuid4().hex