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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: log-foundry
-Version: 0.10.2.dev128
+Version: 0.10.2.dev129
 Summary: Generate logs for your console and JSON events for downstream consumption.
 License-Expression: MIT
 License-File: LICENSE
@@ -1086,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. |
@@ -1095,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.dev128 → log_foundry-0.10.2.dev129}/README.md

@@ -1035,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. |
@@ -1044,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.dev128 → 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.dev128"
+version = "0.10.2.dev129"
 
 [project.urls]
 Homepage = "https://github.com/agriffi10/log-forge"

{log_foundry-0.10.2.dev128 → 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.dev128 → 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.dev128 → 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.dev128 → 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.