log-foundry 0.10.2.dev12__tar.gz → 0.10.2.dev13__tar.gz

{log_foundry-0.10.2.dev12 → log_foundry-0.10.2.dev13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: log-foundry
-Version: 0.10.2.dev12
+Version: 0.10.2.dev13
 Summary: Generate logs for your console and JSON events for downstream consumption.
 License-Expression: MIT
 License-File: LICENSE

{log_foundry-0.10.2.dev12 → log_foundry-0.10.2.dev13}/pyproject.toml

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

{log_foundry-0.10.2.dev12 → log_foundry-0.10.2.dev13}/src/log_foundry/_diag.py

@@ -94,7 +94,10 @@ def lost(what: str, count: int, detail: str = "") -> None:
     Args:
         what: Singular noun for the unit lost — ``"event"``, ``"message"``, ``"row"``. Rendered
             with the corpus-wide ``(s)`` suffix, so it must be a literal, never a runtime value.
-        count: How many were lost. The caller's counter has already moved by this much.
+        count: How many this line reports as lost — normally the increment the caller's counter
+            has just taken. A **throttled** site instead passes its running total, because a line
+            written on every thousandth drop that said "lost 1" would read as one loss rather than
+            a thousand; such a site says so in ``detail``. Recorded before this call either way.
         detail: Optional circumstances — the sink's class name, the attempt count, an ``errno``,
             an exception *type*. Escaped and truncated to ``_MAX_DETAIL``.
     """

{log_foundry-0.10.2.dev12 → log_foundry-0.10.2.dev13}/src/log_foundry/decorator.py

@@ -24,7 +24,6 @@ from __future__ import annotations
 import asyncio
 import atexit
 import functools
-import sys
 import threading
 from collections.abc import Callable
 from time import monotonic
@@ -47,9 +46,6 @@ if TYPE_CHECKING:
 
 __all__ = ["continue_trace", "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
@@ -86,19 +82,6 @@ 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,
     *,
@@ -144,19 +127,19 @@ def continue_trace(
     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)
+            _diag.rejected("both traceparent and explicit ids given; traceparent wins", traceparent)
         parsed = parse_traceparent(traceparent)
         if parsed is None:
-            _warn_rejected("unparseable traceparent", traceparent)
+            _diag.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)
+            _diag.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)
+            _diag.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
@@ -175,7 +158,7 @@ def continue_trace(
         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)
+            _diag.rejected("unusable baggage header", baggage)
         else:
             context.set_baggage(**parsed_baggage)
 

{log_foundry-0.10.2.dev12 → log_foundry-0.10.2.dev13}/src/log_foundry/worker.py

@@ -20,7 +20,6 @@ nothing about spans or context (the same dumbness that makes sinks swappable).
 from __future__ import annotations
 
 import queue
-import sys
 import threading
 import time
 from typing import TYPE_CHECKING, NamedTuple, cast
@@ -162,15 +161,7 @@ class Worker:
             # submitters. Lines may therefore interleave out of order under concurrency; the
             # counts they carry are still exact.
             if total == 1 or total % _DROP_WARN_EVERY == 0:
-                try:
-                    sys.stderr.write(
-                        f"log-foundry: log queue full, dropped {total} submission(s) so far\n"
-                    )
-                except Exception:  # submit() runs on the *caller's* thread, so an
-                    # unwritable stderr (closed fd, broken pipe, daemonized process) would raise
-                    # straight into the app. A diagnostic about dropped logs must never itself be
-                    # the reason a decorated function fails. The counter is already recorded.
-                    pass
+                _diag.lost("submission", total, "log queue full; count is cumulative")
 
     def health(self) -> Health:
         """Snapshot the delivery counters (SPEC-017 FR-005, SPEC-019 FR-003). Never raises.
@@ -323,36 +314,36 @@ class Worker:
 
         Recording precedes announcing: stderr may be closed or wedged, and unlike the overflow
         warning this line is written exactly once and cannot be re-emitted later, so the record
-        must not be able to ride on it. The exception's *type* is reported and its message is
-        not — a sink's exception text can carry event data, and arch §6 keeps caller data out of
-        places it was not asked for (the same rule behind ``sanitize``'s type-name placeholder).
+        must not be able to ride on it. The exception's *type* is reported and its message is not
+        — the rule ``_diag`` now applies to every line the library writes (SPEC-029), and the
+        reason this site had it first.
 
-        The count reports what was *in hand* and what was still *queued behind it* (SPEC-021
-        FR-002). Held alone under-reads the loss: nothing will drain the queue either, so an
-        operator reading "1 undrained event-list(s)" could conclude far less was lost than was.
+        The announcement is an :func:`~log_foundry._diag.absorbed`, not a fourth kind of line: the
+        thread's death *is* an exception this method caught and did not propagate, and what it
+        cost belongs in the detail. The count reports what was *in hand* and what was still
+        *queued behind it* (SPEC-021 FR-002). Held alone under-reads the loss: nothing will drain
+        the queue either, so an operator reading "1 undrained event-list(s)" could conclude far
+        less was lost than was.
 
         The queued figure is "items", not "event-lists", and says so: like ``Health.queued`` it is
         read without stopping the world, so it counts any internal flush/shutdown marker sitting
         alongside real submissions, and a producer thread can add to the queue between the death
         and the read. It is a floor on what was lost, which is the useful direction.
         """
-        name = type(exc).__name__
         with self._lock:
-            self.stopped_reason = name
+            self.stopped_reason = type(exc).__name__
         try:
             # In its own guard, and after the record: ``qsize()`` is not guaranteed on every
             # platform's queue, and a diagnostic must not be the reason the diagnosis is lost.
             queued: object = self._queue.qsize()
         except Exception:
             queued = "?"
-        try:
-            sys.stderr.write(
-                f"log-foundry: worker thread stopped on {name}; {undrained} undrained "
-                f"event-list(s) held and {queued} queued item(s) undelivered, nothing further "
-                f"will be delivered\n"
-            )
-        except Exception:  # best-effort: the record above is what an operator reads.
-            pass
+        _diag.absorbed(
+            "draining the log queue",
+            exc,
+            f"worker thread stopped; {undrained} undrained event-list(s) held and {queued} "
+            f"queued item(s) undelivered, nothing further will be delivered",
+        )
 
     def _drain(self, pending: list[list[dict[str, object]]]) -> None:
         """The drain loop proper. ``pending`` is owned by :meth:`_run`, which reports its size.
@@ -477,9 +468,12 @@ class Worker:
                     # than a half-updated pair. No deadlock: shutdown() releases before join().
                     with self._lock:
                         self.failed_batches += 1
-                    sys.stderr.write(
-                        f"log-foundry: abandoned a batch of {len(batch)} event(s) after "
-                        f"{retries + 1} failed emit attempts\n"
+                    # Through ``_diag`` so the write is guarded: unguarded, a broken stderr raised
+                    # out of here, through ``_drain``, into ``_run``'s handler, and the drain
+                    # thread died for good — a diagnostic about one lost batch costing every batch
+                    # after it (SPEC-029 FR-003).
+                    _diag.lost(
+                        "event", len(batch), f"batch abandoned after {retries + 1} emit attempts"
                     )
                     return
                 # Backoff between attempts; _stop.wait returns at once during shutdown, so a