log-foundry 0.10.2.dev127__tar.gz → 0.10.2.dev129__tar.gz

{log_foundry-0.10.2.dev127 → log_foundry-0.10.2.dev129}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: log-foundry
-Version: 0.10.2.dev127
+Version: 0.10.2.dev129
 Summary: Generate logs for your console and JSON events for downstream consumption.
 License-Expression: MIT
 License-File: LICENSE
@@ -347,7 +347,7 @@ lands can arrive at a sink whose close has already run, and nothing owes that si
 
 ### `@trace`
 
-Decorate any **synchronous** function. Usable bare or with arguments:
+Decorate a function, sync or async. Usable bare or with arguments:
 
 ```python
 @lf.trace                                  # span name = func.__qualname__
@@ -363,7 +363,10 @@ def process(): ...
 
 `@trace` refuses at decoration what it cannot trace, with a `TypeError` naming the function:
 a `@classmethod` or `@staticmethod` written *below* it (put them above), a bare string
-(`@trace("checkout")` meant `@trace(name="checkout")`), and anything not callable.
+(`@trace("checkout")` meant `@trace(name="checkout")`), anything not callable, and a
+**generator function** (sync or async, including one behind `@contextmanager`, `@lru_cache` or
+any `functools.wraps` wrapper) — its body runs after the wrapper has returned, so the span would
+close before it started. Trace the consumer instead: the function that iterates it.
 
 The **outermost** decorated call starts a new trace; every nested decorated call becomes a
 child span within it. On an exception, the decorator records `status="error"` plus an `error`
@@ -1083,7 +1086,7 @@ They tell you different things, and they want different responses:
 
 | Field | Means | What to do |
 |---|---|---|
-| `dropped` | The queue filled — the destination is not keeping up. Delivery continues. | Make the destination keep up: scale the sink, or reduce what you log. The worker's batch size, flush interval and queue depth are **not** reachable from the public API, so tuning them is not an option this version offers you. |
+| `dropped` | The queue filled — the destination is not keeping up. Delivery continues. It counts **submissions** — one per span close, or per open span a `flush()` sweeps — so the events lost are a multiple of it. | Make the destination keep up: scale the sink, or reduce what you log. The worker's batch size, flush interval and queue depth are **not** reachable from the public API, so tuning them is not an option this version offers you. |
 | `failed_batches` | A sink stayed broken through the whole retry budget. Delivery continues. | Fix the destination. |
 | `stopped_reason` | The background thread **died** on that exception type. Nothing further will be delivered, ever. | Restart the process; investigate the named exception. |
 | `sink.dropped` | The sink discarded events **before** attempting delivery — an oversized record, or one the client refused outright. | Read the stderr line: it names the cause. An oversized record means shrink what you log; a refused local produce/publish (Kafka, Pub/Sub) points at the client — a saturated buffer, a bad topic, a credential. |
@@ -1092,12 +1095,13 @@ They tell you different things, and they want different responses:
 | `incomplete_swaps` | A late `configure(sink=...)` could not confirm the previous sink was drained. The swap took effect; that sink was left open and some queued events may have gone to the new one. | Investigate the previous sink — it was hung or failing. Configure the sink before the first log where you can. |
 | `inherited_sink` | This process is delivering to a sink it **inherited across a `fork`** and may not release, so it will not be closed here. Not a loss and not an alert term. | Nothing, usually. It explains a handle still open after `shutdown()`, and tells you a deployment shares one sink across a fork at all. `True` for a shared `StdoutSink` too, whose `close()` only flushes — so a `True` is not by itself evidence that anything is held. If you want the child to own its transport, build the sink in the worker process (see Forking). |
 | `orphan_lost` | An event logged **with no open span** never reached the sink. That call emits on your own thread with no worker behind it, so no other field here can carry it — it is not a batch, there was no retry, and there may be no worker at all. Covers a sink that failed to *construct* as well as one that raised. | Fix the destination, or the data. The stderr line names the exception type. If a process logs this way at all, this is the field to alert on: nothing else describes that path. |
-| `in_span_lost` | An event logged **inside a span** could not be built — a value that could not be turned into an event. Always the data, never the destination: the in-span path cannot fail at delivery, which is `failed_batches`. | Fix the call site. Passing a non-string message (an exception object, say) is the common cause. |
+| `in_span_lost` | An event logged **inside a span** was lost before delivery, for one of two reasons the count tells apart: **the data** — a value that could not be turned into an event, one per call — or **no drain thread at all** — the process could not start the worker, and the span's whole buffer is counted at once (SPEC-050). Never a destination that failed at delivery; that is `failed_batches`. | One event at a time: fix the call site — a non-string message (an exception object, say) is the common cause. A whole buffer at once: the process cannot start a thread; the stderr line names it. |
 | `closing_sinks` | Swapped-out sinks inside `close()` **right now** — a live gauge, not a counter. It and `queued` are the two fields here that fall as well as rise; the other integer counters only climb. Non-zero on a single read is normal during a swap. | Nothing, unless it stays non-zero. That means a destination is stuck in `close()` and will not release its resources. |
 
 `orphan_lost` and `in_span_lost` are deliberately two fields and their sum is deliberately not
 reported. They aggregate different failure populations — one can mean the destination *or* the
-data, the other can only mean the data — so a single number would hide which fix applies.
+data; the other never the destination — the data, or no drain thread at all (SPEC-050) — so a
+single number would hide which fix applies.
 
 `h.sink` is a `SinkLosses`, carrying `dropped` and `failed`, or `None` — `None` when no worker
 exists yet, or when the configured sink reports nothing (`losses()` is optional, and a sink whose

{log_foundry-0.10.2.dev127 → log_foundry-0.10.2.dev129}/README.md

@@ -296,7 +296,7 @@ lands can arrive at a sink whose close has already run, and nothing owes that si
 
 ### `@trace`
 
-Decorate any **synchronous** function. Usable bare or with arguments:
+Decorate a function, sync or async. Usable bare or with arguments:
 
 ```python
 @lf.trace                                  # span name = func.__qualname__
@@ -312,7 +312,10 @@ def process(): ...
 
 `@trace` refuses at decoration what it cannot trace, with a `TypeError` naming the function:
 a `@classmethod` or `@staticmethod` written *below* it (put them above), a bare string
-(`@trace("checkout")` meant `@trace(name="checkout")`), and anything not callable.
+(`@trace("checkout")` meant `@trace(name="checkout")`), anything not callable, and a
+**generator function** (sync or async, including one behind `@contextmanager`, `@lru_cache` or
+any `functools.wraps` wrapper) — its body runs after the wrapper has returned, so the span would
+close before it started. Trace the consumer instead: the function that iterates it.
 
 The **outermost** decorated call starts a new trace; every nested decorated call becomes a
 child span within it. On an exception, the decorator records `status="error"` plus an `error`
@@ -1032,7 +1035,7 @@ They tell you different things, and they want different responses:
 
 | Field | Means | What to do |
 |---|---|---|
-| `dropped` | The queue filled — the destination is not keeping up. Delivery continues. | Make the destination keep up: scale the sink, or reduce what you log. The worker's batch size, flush interval and queue depth are **not** reachable from the public API, so tuning them is not an option this version offers you. |
+| `dropped` | The queue filled — the destination is not keeping up. Delivery continues. It counts **submissions** — one per span close, or per open span a `flush()` sweeps — so the events lost are a multiple of it. | Make the destination keep up: scale the sink, or reduce what you log. The worker's batch size, flush interval and queue depth are **not** reachable from the public API, so tuning them is not an option this version offers you. |
 | `failed_batches` | A sink stayed broken through the whole retry budget. Delivery continues. | Fix the destination. |
 | `stopped_reason` | The background thread **died** on that exception type. Nothing further will be delivered, ever. | Restart the process; investigate the named exception. |
 | `sink.dropped` | The sink discarded events **before** attempting delivery — an oversized record, or one the client refused outright. | Read the stderr line: it names the cause. An oversized record means shrink what you log; a refused local produce/publish (Kafka, Pub/Sub) points at the client — a saturated buffer, a bad topic, a credential. |
@@ -1041,12 +1044,13 @@ They tell you different things, and they want different responses:
 | `incomplete_swaps` | A late `configure(sink=...)` could not confirm the previous sink was drained. The swap took effect; that sink was left open and some queued events may have gone to the new one. | Investigate the previous sink — it was hung or failing. Configure the sink before the first log where you can. |
 | `inherited_sink` | This process is delivering to a sink it **inherited across a `fork`** and may not release, so it will not be closed here. Not a loss and not an alert term. | Nothing, usually. It explains a handle still open after `shutdown()`, and tells you a deployment shares one sink across a fork at all. `True` for a shared `StdoutSink` too, whose `close()` only flushes — so a `True` is not by itself evidence that anything is held. If you want the child to own its transport, build the sink in the worker process (see Forking). |
 | `orphan_lost` | An event logged **with no open span** never reached the sink. That call emits on your own thread with no worker behind it, so no other field here can carry it — it is not a batch, there was no retry, and there may be no worker at all. Covers a sink that failed to *construct* as well as one that raised. | Fix the destination, or the data. The stderr line names the exception type. If a process logs this way at all, this is the field to alert on: nothing else describes that path. |
-| `in_span_lost` | An event logged **inside a span** could not be built — a value that could not be turned into an event. Always the data, never the destination: the in-span path cannot fail at delivery, which is `failed_batches`. | Fix the call site. Passing a non-string message (an exception object, say) is the common cause. |
+| `in_span_lost` | An event logged **inside a span** was lost before delivery, for one of two reasons the count tells apart: **the data** — a value that could not be turned into an event, one per call — or **no drain thread at all** — the process could not start the worker, and the span's whole buffer is counted at once (SPEC-050). Never a destination that failed at delivery; that is `failed_batches`. | One event at a time: fix the call site — a non-string message (an exception object, say) is the common cause. A whole buffer at once: the process cannot start a thread; the stderr line names it. |
 | `closing_sinks` | Swapped-out sinks inside `close()` **right now** — a live gauge, not a counter. It and `queued` are the two fields here that fall as well as rise; the other integer counters only climb. Non-zero on a single read is normal during a swap. | Nothing, unless it stays non-zero. That means a destination is stuck in `close()` and will not release its resources. |
 
 `orphan_lost` and `in_span_lost` are deliberately two fields and their sum is deliberately not
 reported. They aggregate different failure populations — one can mean the destination *or* the
-data, the other can only mean the data — so a single number would hide which fix applies.
+data; the other never the destination — the data, or no drain thread at all (SPEC-050) — so a
+single number would hide which fix applies.
 
 `h.sink` is a `SinkLosses`, carrying `dropped` and `failed`, or `None` — `None` when no worker
 exists yet, or when the configured sink reports nothing (`losses()` is optional, and a sink whose

{log_foundry-0.10.2.dev127 → log_foundry-0.10.2.dev129}/pyproject.toml

@@ -74,7 +74,7 @@ keywords = [
 # vulnerability-reporting channel. The repository is still named `log-forge` — the ORIGINAL name,
 # which PyPI rejected for the distribution — so these URLs deliberately do not match the package
 # name. See the note on `name` above before "correcting" them.
-version = "0.10.2.dev127"
+version = "0.10.2.dev129"
 
 [project.urls]
 Homepage = "https://github.com/agriffi10/log-forge"

{log_foundry-0.10.2.dev127 → log_foundry-0.10.2.dev129}/src/log_foundry/__init__.py

@@ -87,8 +87,8 @@ def health() -> Health:
     an event that cannot be *built* never reaches a queue at all — so every other field here
     describes machinery those two losses never touched, and a process that only logs outside a
     span read all zeros over total loss until they existed. They stay separate because one can
-    mean the destination or the data and the other can only mean the data; their sum is a number
-    nobody can act on.
+    mean the destination or the data and the other never the destination — the data, or no drain
+    thread at all (SPEC-050 FR-003); their sum is a number nobody can act on.
 
     ``retired`` alone is not a fault — a process that shuts down and then stops logging is
     doing the right thing, which is why it is paired with the count rather than alerted on.

{log_foundry-0.10.2.dev127 → log_foundry-0.10.2.dev129}/src/log_foundry/config.py

@@ -271,7 +271,12 @@ def get_config() -> Config:
     validation :func:`configure` performs — ``max_value_bytes = 0`` was accepted and emptied
     every event it touched. Both measured. :func:`configure` is the only route to a change.
 
-    It is a **copy**, not the frozen original, and ``defaults`` is copied with it. A caller who
+    It is a **copy**, not the frozen original, and ``defaults`` is copied with it — **one level
+    deep**: the mapping is the caller's own, its values are shared with the library, so a nested
+    mutable value edited through the copy still reaches every later event (2026-09-04 audit,
+    N8). Deep-copying was declined because a default can be any object and copying an arbitrary
+    object can raise or be wrong; a caller who needs isolation for a nested value copies it. A
+    caller who
     defeats the freeze — ``object.__setattr__`` reaches through any frozen dataclass — then
     edits an object the library does not read, rather than the live config; and ``defaults`` is
     a plain mutable ``dict``, so sharing it would leave the freeze cosmetic at the one field
@@ -282,7 +287,8 @@ def get_config() -> Config:
       None.
 
     Returns:
-      A copy of the process-wide :class:`Config`, with its own ``defaults``.
+      A copy of the process-wide :class:`Config`, with its own top-level ``defaults`` mapping
+      whose values are shared.
 
     Raises:
       None.

{log_foundry-0.10.2.dev127 → log_foundry-0.10.2.dev129}/src/log_foundry/decorator.py

@@ -639,6 +639,21 @@ def _refuse_unusable(fn: object) -> None:
     ``self`` to a function declared without one. A ``str`` is the slip ``@trace("checkout")``,
     which meant ``name=``. Anything else that is not callable is refused by type.
 
+    A generator function or an async generator function is refused too (SPEC-055 FR-003): its
+    body runs after the wrapper has returned the generator object, so the span would open and
+    close before a single line of it ran, and every event the body logged would be an orphan on
+    a fresh trace — measured, ``['span.start', 'span.end']`` before the first ``next()``. The
+    check is the code flags, on ``fn``, on whatever ``fn`` advertises through ``__wrapped__``
+    — so ``@trace`` above ``@contextmanager``, ``@lru_cache`` or any ``functools.wraps`` wrapper
+    of a generator is refused too, each measured recording the same orphaned ``inside`` event —
+    and on the type's ``__call__`` for a callable instance; all of them see through a
+    ``functools.partial``. A plain function that merely *returns* a generator object without
+    advertising it is indistinguishable here and is not detected, which is a stated limit
+    rather than a gap to close at call time, where invariant 13 does not refuse. Wrapping the
+    iteration instead — a span per generator, pushed around every resumption — was considered
+    and deferred: a refusal can be lifted into a wrap later without breaking anyone, while a
+    wrap shipped first freezes its semantics at 1.0.
+
     Args:
       fn: Whatever was handed to the decorator.
 
@@ -646,8 +661,8 @@ def _refuse_unusable(fn: object) -> None:
       None.
 
     Raises:
-      TypeError: If ``fn`` is a ``classmethod`` or ``staticmethod`` object, a ``str``, or not
-        callable at all.
+      TypeError: If ``fn`` is a ``classmethod`` or ``staticmethod`` object, a ``str``, not
+        callable at all, or a generator function or async generator function.
       Exception: Whatever the callable's own attribute access raises — a ``__class__`` property,
         say — at decoration, in the caller's frame, which is invariant 13's moment.
     """
@@ -664,6 +679,61 @@ def _refuse_unusable(fn: object) -> None:
         )
     if not callable(fn):
         raise TypeError(f"@trace needs a callable, got {type(fn).__name__}")
+    if _is_generator_function(fn):
+        raise TypeError(
+            f"@trace cannot trace the iteration of the generator function {_span_name(fn)}: its "
+            f"body runs after the wrapper has returned, so the span would close before it "
+            f"starts. Trace the consumer instead: the function that iterates it"
+        )
+
+
+def _is_generator_function(fn: object) -> bool:
+    """Reports whether a callable's body is a generator or async generator (SPEC-055 FR-003).
+
+    The same shape as :func:`_is_async`: the code flags of ``fn`` itself, which see through a
+    ``functools.partial``; then of whatever ``fn`` advertises through ``__wrapped__``, which is
+    how ``@contextmanager``, ``@lru_cache`` and every ``functools.wraps`` wrapper point back at
+    the generator they wrap; and for anything that is not a plain function the type's
+    ``__call__`` as well, so a callable instance whose ``__call__`` yields is caught too. The
+    unwrap is guarded because :func:`inspect.unwrap` raises ``ValueError`` on a ``__wrapped__``
+    cycle, and a cycle is not a generator.
+
+    Args:
+      fn: The callable being decorated.
+
+    Returns:
+      Whether ``fn`` would return a generator or async generator object when called.
+
+    Raises:
+      Exception: Whatever the callable's own ``__class__``, ``__call__`` or ``__wrapped__``
+        lookup raises, at decoration, in the caller's frame.
+    """
+    if _yields(fn):
+        return True
+    try:
+        target = inspect.unwrap(cast("Callable[..., Any]", fn))
+    except ValueError:
+        target = fn
+    if target is not fn and _yields(target):
+        return True
+    if inspect.isfunction(fn):
+        return False
+    return _yields(type(fn).__call__)
+
+
+def _yields(fn: object) -> bool:
+    """Reads a callable's code flags for a generator or async generator body.
+
+    Args:
+      fn: The callable to inspect.
+
+    Returns:
+      Whether its body is a generator or an async generator.
+
+    Raises:
+      None.
+    """
+    return inspect.isgeneratorfunction(fn) or inspect.isasyncgenfunction(fn)
 
 
 def _span_name(fn: object) -> str:
@@ -749,8 +819,10 @@ def trace(
 
     Raises:
       TypeError: At decoration, for a ``classmethod`` or ``staticmethod`` object (the decorators
-        are in the wrong order), a ``str`` (``name=`` was meant), anything not callable, or a
-        ``name=`` that is not a ``str`` (SPEC-055 FR-002, invariant 13).
+        are in the wrong order), a ``str`` (``name=`` was meant), anything not callable, a
+        ``name=`` that is not a ``str`` (SPEC-055 FR-002), or a generator function, whose
+        iteration cannot be traced by a wrapper around the call (SPEC-055 FR-003) — invariant
+        13.
     """
     span_defaults = None if defaults is None else dict(defaults)
 

{log_foundry-0.10.2.dev127 → log_foundry-0.10.2.dev129}/src/log_foundry/ids.py

@@ -137,7 +137,9 @@ def parse_traceparent(value: object) -> tuple[str, str] | None:
     its own identity.
 
     Args:
-      value: An inbound header value of any type, from outside the process.
+      value: An inbound header value of any type, from outside the process. Surrounding
+        whitespace is stripped before parsing, since a header value arrives trimmed from some
+        transports and not others; whitespace anywhere else is a malformed field.
 
     Returns:
       A ``(trace_id, span_id)`` tuple, or ``None`` if the value is unusable.

{log_foundry-0.10.2.dev127 → log_foundry-0.10.2.dev129}/src/log_foundry/sinks/kinesis.py

@@ -282,11 +282,15 @@ class KinesisSink:
 
 
 MAX_PARTITION_KEY_BYTES = 256
-"""The service's ceiling on a ``PutRecords`` partition key, in UTF-8 bytes."""
+"""This sink's ceiling on a ``PutRecords`` partition key, in UTF-8 bytes.
+
+At or below the service's own limit, which its API reference states as 256 **characters**: a
+byte bound is stricter for any non-ASCII key and therefore safe (2026-09-04 audit, N12).
+"""
 
 
 def _partition_key(raw: str) -> str:
-    """Bounds a partition key to the service's 256 **bytes**, never 256 characters.
+    """Bounds a partition key to 256 UTF-8 **bytes**, at or below the service's 256-character limit.
 
     Both encodes carry an ``errors=`` and both are load-bearing. Assembly replaces a lone
     surrogate since SPEC-055 FR-001, so an event field cannot carry one — but this key is derived
@@ -319,7 +323,8 @@ def _record_size(record: dict[str, Any]) -> int:
     """Measures one request entry, partition key included (SPEC-038 FR-009).
 
     ``PutRecords`` charges the partition key against the 5 MiB request limit, and a key may be up
-    to 256 bytes, so a 500-record request could understate itself by ~128 KB — enough to have the
+    to 256 characters at the service (bounded here to 256 bytes), so a 500-record request could
+    understate itself by ~128 KB — enough to have the
     service reject a chunk this sink believed was inside the budget. ``SQSSink`` charges its FIFO
     ids for the same reason and records the same rationale.