log-foundry 0.2.1.dev3__py3-none-any.whl → 0.2.1.dev5__py3-none-any.whl

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``, and ``shutdown`` (graceful
-drain of the background worker).
+``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").
@@ -19,11 +26,38 @@ except PackageNotFoundError:  # running from a source tree that isn't installed
     __version__ = "0.0.0"
 
 
+def flush(timeout: float | None = 5.0) -> bool:
+    """Drain buffered events through the sink without closing it.
+
+    Every event submitted before this call has been passed to ``sink.emit`` when it returns
+    ``True``. (Events submitted concurrently by another thread may or may not be included —
+    the caller cannot have meant those.) Unlike :func:`shutdown` the background worker stays
+    alive and the sink stays open, so logging continues normally afterwards.
+
+    This is the drain for a process that is *frozen* rather than exited — an AWS Lambda
+    handler must drain before it returns, but will be invoked again on the same warm
+    container. Call it in a ``finally``: the invocation worth logging is the one that failed.
+
+    ``timeout=None`` waits indefinitely, which is unsafe in any environment with an execution
+    deadline — it converts "some logs were lost" into "the invocation timed out".
+
+    Returns ``False`` if the drain did not complete within ``timeout``, or if the worker has
+    already been shut down. Never raises.
+    """
+    from log_foundry.decorator import _flush_worker
+
+    return _flush_worker(timeout)
+
+
 def shutdown() -> None:
     """Flush buffered events and close the sink, blocking until drained. Idempotent.
 
     Also registered via ``atexit``; call it explicitly before a fast process exit when you
     want to be certain the tail of the queue reached the sink (SPEC-004 FR-005).
+
+    This is **terminal** — the worker does not come back. Do not call it per-invocation in a
+    serverless handler: the first invocation on a warm container would log and every later one
+    would silently log nothing. Use :func:`flush` there, which drains and keeps the worker.
     """
     from log_foundry.decorator import _shutdown_worker
 
@@ -40,6 +74,11 @@ __all__ = [
     "error",
     "critical",
     "set_baggage",
+    "continue_trace",
+    "current_traceparent",
+    "current_trace_context",
+    "current_baggage_header",
+    "flush",
     "shutdown",
     "__version__",
 ]

log_foundry/context.py

@@ -16,6 +16,9 @@ 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
@@ -26,6 +29,9 @@ __all__ = [
     "pop_span",
     "get_baggage",
     "set_baggage",
+    "current_traceparent",
+    "current_trace_context",
+    "current_baggage_header",
 ]
 
 _span_stack: contextvars.ContextVar[tuple[Span, ...]] = contextvars.ContextVar(
@@ -34,6 +40,16 @@ _span_stack: contextvars.ContextVar[tuple[Span, ...]] = contextvars.ContextVar(
 _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:
@@ -60,3 +76,85 @@ def get_baggage() -> dict[str, object]:
 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/decorator.py

@@ -13,6 +13,10 @@ opens when the coroutine actually runs and closes when it finishes, with no new
 
 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
@@ -20,6 +24,7 @@ from __future__ import annotations
 import asyncio
 import atexit
 import functools
+import sys
 import threading
 from collections.abc import Callable
 from time import monotonic
@@ -27,11 +32,20 @@ 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.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"]
+__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.
@@ -43,12 +57,24 @@ 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)."""
+    """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=parent.trace_id if parent else new_trace_id(),
+        trace_id=trace_id,
         span_id=new_span_id(),
-        parent_span_id=parent.span_id if parent else None,
+        parent_span_id=parent_span_id,
         name=name,
         start_ts=monotonic(),
         defaults=defaults or {},
@@ -57,6 +83,116 @@ def _open_span(name: str, defaults: dict[str, object] | None) -> 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).
 
@@ -80,6 +216,25 @@ def _shutdown_worker() -> 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).
 

log_foundry/ids.py

@@ -1,9 +1,14 @@
-"""W3C Trace Context-compatible id generation (arch §3.1, guide Phase 2).
+"""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 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.
+``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
@@ -11,7 +16,26 @@ from __future__ import annotations
 import os
 import uuid
 
-__all__ = ["new_trace_id", "new_span_id", "new_log_id"]
+__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:
@@ -27,3 +51,59 @@ def new_span_id() -> str:
 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/worker.py

@@ -8,6 +8,11 @@ bounded and overflow is dropped-newest with a counter (arch §9). Emit failures
 with backoff; a graceful :meth:`shutdown` drains the queue, emits the tail, and closes the
 sink so buffered events survive process exit.
 
+Two drains, deliberately distinct (SPEC-013): :meth:`shutdown` is terminal — it stops the thread
+and closes the sink, and the worker never comes back — while :meth:`flush` drains on demand and
+leaves everything running. A process that is frozen rather than exited (a serverless handler
+between invocations) needs the second, because it will be asked to log again.
+
 This module owns *delivery mechanics only*; it receives already-built event dicts and knows
 nothing about spans or context (the same dumbness that makes sinks swappable).
 """
@@ -29,6 +34,25 @@ __all__ = ["Worker"]
 _SHUTDOWN = object()
 
 
+class _FlushMarker:
+    """A drain request travelling the queue in FIFO order (SPEC-013 FR-002).
+
+    The mechanism follows from the queue being FIFO: everything submitted *before* ``flush()``
+    was called is necessarily ahead of the marker, so by the time the worker dequeues it those
+    events are either already emitted or sitting in ``pending``. The worker emits ``pending``,
+    then sets ``event``. No lock, no inspection of queue internals, and no coordination with the
+    batching triggers.
+
+    Like ``_SHUTDOWN`` it is never emitted — but unlike ``_SHUTDOWN`` it carries state, so it is
+    a class rather than a bare sentinel object.
+    """
+
+    __slots__ = ("event",)
+
+    def __init__(self) -> None:
+        self.event = threading.Event()
+
+
 class Worker:
     """Owns a bounded queue + daemon thread that batches and flushes events to ``sink``."""
 
@@ -71,6 +95,36 @@ class Worker:
             with self._lock:
                 self.dropped += 1
 
+    def flush(self, timeout: float | None = 5.0) -> bool:
+        """Drain everything submitted before this call through the sink, without stopping.
+
+        Returns ``True`` once the worker has emitted them, ``False`` on timeout or when the
+        worker has already been shut down. Unlike :meth:`shutdown` the thread keeps running, the
+        sink is **not** closed, and the once-only shutdown flag is untouched, so logging
+        continues normally afterwards (SPEC-013 FR-002).
+        """
+        with self._lock:
+            if self._shutdown_done:
+                # Nothing will ever consume a marker now, so report the failure immediately
+                # rather than make the caller wait out `timeout` for a drain that cannot happen.
+                # A caller with an execution deadline would pay that wait for nothing (FR-003).
+                return False
+        if not self._thread.is_alive():
+            return False
+        marker = _FlushMarker()
+        # One deadline shared by the put and the wait: a caller asked for a bound on the whole
+        # call, not on each half of it, so the two cannot add up to 2 * timeout.
+        deadline = None if timeout is None else time.monotonic() + timeout
+        try:
+            # A *blocking* put, never put_nowait: on a full queue put_nowait would skip the
+            # flush and return as though it had succeeded, which is the one outcome a flush must
+            # never produce silently. A put that times out is reported as False.
+            self._queue.put(marker, timeout=timeout)
+        except queue.Full:
+            return False
+        remaining = None if deadline is None else max(0.0, deadline - time.monotonic())
+        return marker.event.wait(remaining)
+
     def shutdown(self) -> None:
         """Stop the thread, drain + emit everything queued, then ``close()`` the sink.
 
@@ -101,6 +155,22 @@ class Worker:
                 item = self._queue.get(timeout=timeout)
             except queue.Empty:
                 item = None
+            if isinstance(item, _FlushMarker):
+                # Drain on demand: emit immediately, ignoring both the batch_size and the
+                # flush_interval trigger — a caller who asked for a flush is not interested in
+                # the batching policy. Note this branch *returns to the top of the loop*: the
+                # marker must never fall through to the append below, where it would be treated
+                # as a list of events and handed to sink.emit, killing this thread.
+                try:
+                    if pending:
+                        self._emit(pending)
+                        pending = []
+                finally:
+                    # Signal even if the emit died, so a waiter is released rather than left to
+                    # wait out its timeout on a thread that is no longer running.
+                    last_flush = time.monotonic()
+                    item.event.set()
+                continue
             if item is not None and item is not _SHUTDOWN:
                 pending.append(cast("list[dict[str, object]]", item))
             now = time.monotonic()
@@ -116,15 +186,24 @@ class Worker:
 
     def _final_drain(self, pending: list[list[dict[str, object]]]) -> None:
         """On stop, pull anything still queued and emit the tail as one final batch."""
+        markers: list[_FlushMarker] = []
         while True:
             try:
                 item = self._queue.get_nowait()
             except queue.Empty:
                 break
+            if isinstance(item, _FlushMarker):
+                # This guard is a second copy of _run's and needs the same exclusion. Markers
+                # are answered *after* the final emit below, so a flush() that raced shutdown()
+                # still returns True — and truthfully: its events really did reach the sink.
+                markers.append(item)
+                continue
             if item is not None and item is not _SHUTDOWN:
                 pending.append(cast("list[dict[str, object]]", item))
         if pending:
             self._emit(pending)
+        for marker in markers:
+            marker.event.set()
 
     def _emit(self, event_lists: list[list[dict[str, object]]]) -> None:
         """Flatten queued per-span event-lists into one batch and emit, retrying with backoff.

{log_foundry-0.2.1.dev3.dist-info → log_foundry-0.2.1.dev5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: log-foundry
-Version: 0.2.1.dev3
+Version: 0.2.1.dev5
 Summary: Generate logs for your console and JSON events for downstream consumption.
 License-Expression: MIT
 License-File: LICENSE
@@ -206,6 +206,12 @@ never crashes the worker or the app. If the bounded queue fills completely, new
 dropped (newest-first) and counted rather than blocking your code. On `shutdown()` the worker
 stops, sweeps anything still queued into one final batch, emits it, and closes the sink.
 
+Both triggers can be pre-empted: `flush()` puts a marker in the queue and the worker emits the
+pending pile the moment it reaches it, ignoring the count and time triggers. Because the queue
+is FIFO, everything submitted before the call is necessarily ahead of that marker — which is
+exactly why the guarantee is "events submitted before this call", and why concurrent
+submissions from other threads may or may not be included.
+
 ## Usage
 
 ### `configure(...)`
@@ -292,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
@@ -494,17 +569,70 @@ a failing sink with backoff, and applies backpressure so a slow or down sink can
 back-pressure the app: when its bounded queue is full it drops the newest submissions and counts
 them (`worker.dropped`) rather than stalling.
 
-Because delivery is asynchronous, drain before the process exits:
+Because delivery is asynchronous, drain before the process exits. There are two drains, and
+which one you want depends on whether the process is about to end:
 
 ```python
 import log_foundry as lf
 
-lf.shutdown()   # flush buffered events and close the sink; blocks until drained
+lf.flush()      # drain to the sink and keep going; returns True when everything landed
+lf.shutdown()   # drain, close the sink, and stop for good; blocks until drained
 ```
 
+| | `flush()` | `shutdown()` |
+|---|---|---|
+| Drains buffered events | yes | yes |
+| Closes the sink | no | yes |
+| Worker survives | yes | **no** — it never comes back |
+| Repeatable | yes | idempotent, but only the first call does anything |
+| Use it | before returning from a handler, or at a checkpoint | once, as the process exits |
+
 `shutdown()` is also registered via `atexit`, so a normal exit flushes automatically — call it
-explicitly when you need to be certain the tail reached the sink before a fast exit (e.g. at the
-end of a short script or an AWS Lambda handler). It is idempotent.
+explicitly when you need to be certain the tail reached the sink before a fast exit, e.g. at the
+end of a short script. It is idempotent.
+
+`flush(timeout=5.0)` returns `True` when every event submitted before the call has been passed
+to the sink, and `False` if that did not happen within `timeout` (or the worker was already shut
+down). It never raises — a logging call must not be the reason your function fails. Passing
+`timeout=None` waits indefinitely, which is unsafe anywhere with an execution deadline.
+
+#### Serverless / short-lived processes
+
+In AWS Lambda (and anything else that freezes rather than exits) the rules are different, and
+getting them wrong is silent:
+
+- **Flush before the handler returns.** Lambda freezes the execution environment the instant
+  your handler returns, so the worker's interval-based flush stops mid-interval and whatever is
+  still queued is lost when the container is eventually reaped. `atexit` does not save you —
+  a frozen environment is killed without running exit handlers, so `flush()` is the *only*
+  guaranteed drain there.
+- **Put it in a `finally`.** A flush written as the last line of the handler body is precisely
+  the line that does not run when the handler raises, and the invocation whose logs are most
+  worth having is the one that failed.
+- **Never call `shutdown()` per invocation.** It is terminal: the worker does not come back, so
+  the first invocation on a warm container would log and every later one would silently log
+  nothing. That failure reads as "works locally, broken in production".
+
+```python
+import log_foundry as lf
+from log_foundry.sinks.sqs import SQSSink
+
+lf.configure(service="billing-api", env="prod", sink=SQSSink(queue_url=QUEUE_URL))
+
+@lf.trace
+def handler(event, context):
+    lf.info("received", records=len(event["Records"]))
+    try:
+        return do_work(event)
+    finally:
+        lf.flush()      # in `finally`: the failed invocation is the one worth logging.
+                        # NEVER shutdown() here — the worker does not come back, and every
+                        # later invocation on this warm container would log nothing.
+```
+
+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.dev3.dist-info → log_foundry-0.2.1.dev5.dist-info}/RECORD

@@ -1,10 +1,10 @@
-log_foundry/__init__.py,sha256=omYgsLnsjBuqEuD9J3gzSCUuiY9md_eh79333klUus0,1384
+log_foundry/__init__.py,sha256=EKW6sdftIsRGPFYgFQBtStObf5aT5Fhpcup10D4l-o4,3287
 log_foundry/api.py,sha256=X4q1EnJCfqtfUglCoZkpUN4uHRs3lXCLBRB6hU8WI8k,3813
 log_foundry/config.py,sha256=vv0WkDffEmbSw3PjOiHBH0OHmyaqWcCUHXyRJsMBSiU,2700
 log_foundry/console.py,sha256=etACHsfxwx_lUF3bej-Hzj63VU_5hxa9g2_Ecpc-0ZI,1199
-log_foundry/context.py,sha256=MnqBFngMB0joOU3ybpXwmK1TwWqsHwAG5Tdye5B2768,2168
-log_foundry/decorator.py,sha256=0a_O7Cwsv1a8IxB_QXrWoCr_ZiDjoQ_i4E6q52SUSDk,5983
-log_foundry/ids.py,sha256=yKJPdCEepG9ZgVP3c-CQyvraHyKRzRUBhUp2-1A8-8g,912
+log_foundry/context.py,sha256=Pq1H5eL8ZMWSw1PgrVi-NHERjBbstLcDr9ANMRPWsxM,6565
+log_foundry/decorator.py,sha256=5UVsol6P2im0qOqrA6zeEe8Re1DLK-NuesOTfmL-Mzo,13566
+log_foundry/ids.py,sha256=68hwM9NwliY4pvSMjMpJeTkQybEjDhqnfD7ko5WFMBo,4541
 log_foundry/model.py,sha256=yL8RRBkHcPvTut5XfVNnm4vztN2YkRIAfFaC6i-U8qY,3591
 log_foundry/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 log_foundry/sinks/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -44,8 +44,8 @@ log_foundry/sinks/stdout.py,sha256=X_hVTUAAsppx1k8znuBveOZZwj3FqcTwLH185_JWJUU,1
 log_foundry/sinks/syslog.py,sha256=CAQ957jBIlAzrLyrOmtzspqcnAFBfYHGrIN8I35DGMw,3381
 log_foundry/sinks/transform.py,sha256=eeZpaMxc7urrZ07Vc4GQ-sIq2mTYhoA_dI4Ur4Mmb4s,1613
 log_foundry/sinks/util.py,sha256=SCYFxW9Jm-bIVsyOKir5JWWbwP7u5VFnhNmncMIkwBM,2759
-log_foundry/worker.py,sha256=9sX6-Zqq4bChlAAM26nDcV3CZGPkgaKHzolIvTeWRjk,6689
-log_foundry-0.2.1.dev3.dist-info/METADATA,sha256=0tkkYzwkQ4xQ6bEQ5R0iBtkxDAqdq-NMcAeMcbDSSX8,31265
-log_foundry-0.2.1.dev3.dist-info/WHEEL,sha256=eY7nduwzv-ldUxpzbRlxwvC693Hg6PX8bWDjEHjZ_dk,88
-log_foundry-0.2.1.dev3.dist-info/licenses/LICENSE,sha256=HaCckyCX8P6TR8gY5xyEsFi050Hs2kl-JqaO9Vi0Sw0,1072
-log_foundry-0.2.1.dev3.dist-info/RECORD,,
+log_foundry/worker.py,sha256=bbBwMwecVOBu1k6rbSLPwM0zzxN-ebGdy5X2Mo5Q14s,11014
+log_foundry-0.2.1.dev5.dist-info/METADATA,sha256=DVktJPh6HCxVxd-_0Bbh8afWkI_B91pTjdHUKxg8rjs,38154
+log_foundry-0.2.1.dev5.dist-info/WHEEL,sha256=eY7nduwzv-ldUxpzbRlxwvC693Hg6PX8bWDjEHjZ_dk,88
+log_foundry-0.2.1.dev5.dist-info/licenses/LICENSE,sha256=HaCckyCX8P6TR8gY5xyEsFi050Hs2kl-JqaO9Vi0Sw0,1072
+log_foundry-0.2.1.dev5.dist-info/RECORD,,