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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: log-foundry
-Version: 0.10.2.dev12
+Version: 0.10.2.dev14
 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.dev14}/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.dev14"
 
 [project.optional-dependencies]
 aws = ["boto3>=1.43.61"]              # SQSSink, SNSSink, KinesisSink, FirehoseSink

{log_foundry-0.10.2.dev12 → log_foundry-0.10.2.dev14}/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.dev14}/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.dev14}/src/log_foundry/sinks/_socket.py

@@ -12,9 +12,10 @@ substitute a fake socket without any network access.
 from __future__ import annotations
 
 import socket
-import sys
 import time
 
+from log_foundry import _diag
+
 __all__ = ["SocketTransport"]
 
 _BACKOFF_BASE = 0.1  # seconds; delay for retry attempt n is _BACKOFF_BASE * 2**n
@@ -81,9 +82,15 @@ class SocketTransport:
                     time.sleep(_BACKOFF_BASE * (2**attempt))
                     continue
                 self.failed += 1
-                sys.stderr.write(
-                    f"log-foundry: SocketTransport abandoned a message after "
-                    f"{self._max_retries + 1} attempt(s) ({err!r})\n"
+                # Guarded now (SPEC-029 FR-003): this runs on the worker thread, and the bare
+                # ``sys.stderr.write`` this replaced could end delivery for good. ``errno``
+                # because an ``OSError`` type name alone does not tell "connection refused" from
+                # "host unknown", and the code is an integer from the OS — not caller data.
+                _diag.lost(
+                    "message",
+                    1,
+                    f"SocketTransport, {self._max_retries + 1} attempt(s), "
+                    f"{type(err).__name__} {_diag.errno_of(err)}".rstrip(),
                 )
                 return
 

{log_foundry-0.10.2.dev12 → log_foundry-0.10.2.dev14}/src/log_foundry/sinks/clickhouse.py

@@ -9,10 +9,10 @@ idempotent ``MergeTree`` ``create_table`` convenience is off by default. Write-o
 from __future__ import annotations
 
 import json
-import sys
 import time
 from typing import Any
 
+from log_foundry import _diag
 from log_foundry.sinks._chunk import chunk_list, valid_identifier
 
 __all__ = ["ClickHouseSink"]
@@ -97,9 +97,10 @@ class ClickHouseSink:
                     time.sleep(_BACKOFF_BASE * (2**attempt))
                     continue
                 self.failed += len(rows)
-                sys.stderr.write(
-                    f"log-foundry: ClickHouseSink abandoned {len(rows)} row(s) after "
-                    f"{self.max_retries + 1} attempts ({err!r})\n"
+                _diag.lost(
+                    "row",
+                    len(rows),
+                    f"ClickHouseSink, {self.max_retries + 1} attempts, {type(err).__name__}",
                 )
                 return
 

{log_foundry-0.10.2.dev12 → log_foundry-0.10.2.dev14}/src/log_foundry/sinks/elasticsearch.py

@@ -10,8 +10,8 @@ without discarding the successfully-indexed items. OpenSearch speaks the same bu
 from __future__ import annotations
 
 import json
-import sys
 
+from log_foundry import _diag
 from log_foundry.sinks.http import HTTPSink
 
 __all__ = ["ElasticsearchSink", "OpenSearchSink"]
@@ -61,7 +61,7 @@ class ElasticsearchSink(HTTPSink):
                 errors += 1
         if errors:
             self.item_errors += errors
-            sys.stderr.write(f"log-foundry: ElasticsearchSink saw {errors} failed bulk item(s)\n")
+            _diag.lost("bulk item", errors, f"{type(self).__name__}, rejected by the server")
 
 
 class OpenSearchSink(ElasticsearchSink):

{log_foundry-0.10.2.dev12 → log_foundry-0.10.2.dev14}/src/log_foundry/sinks/eventhubs.py

@@ -10,10 +10,11 @@ send errors are retried within a bound. ``close()`` closes the producer.
 from __future__ import annotations
 
 import json
-import sys
 import time
 from typing import Any
 
+from log_foundry import _diag
+
 __all__ = ["AzureEventHubsSink"]
 
 _BACKOFF_BASE = 0.1
@@ -62,10 +63,7 @@ class AzureEventHubsSink:
             current = self.producer.create_batch()
             if not _try_add(current, data):
                 self.dropped_oversized += 1
-                sys.stderr.write(
-                    "log-foundry: AzureEventHubsSink dropped an event too large for an "
-                    "empty 1 MB batch\n"
-                )
+                _diag.lost("event", 1, "AzureEventHubsSink, too large for an empty 1 MB batch")
         self._send(current)
 
     def close(self) -> None:
@@ -87,9 +85,11 @@ class AzureEventHubsSink:
                     time.sleep(_BACKOFF_BASE * (2**attempt))
                     continue
                 self.failed += len(event_batch)
-                sys.stderr.write(
-                    f"log-foundry: AzureEventHubsSink abandoned a batch of {len(event_batch)} "
-                    f"event(s) after {self.max_retries + 1} attempts ({err!r})\n"
+                _diag.lost(
+                    "event",
+                    len(event_batch),
+                    f"AzureEventHubsSink, one batch, {self.max_retries + 1} attempts, "
+                    f"{type(err).__name__}",
                 )
                 return
 

{log_foundry-0.10.2.dev12 → log_foundry-0.10.2.dev14}/src/log_foundry/sinks/firehose.py

@@ -9,9 +9,9 @@ retried within a bounded count.
 from __future__ import annotations
 
 import json
-import sys
 from typing import Any
 
+from log_foundry import _diag
 from log_foundry.sinks._batch import adjudicate_positional, usable_results
 from log_foundry.sinks._chunk import chunk_items
 
@@ -69,9 +69,11 @@ class FirehoseSink:
             data = json.dumps(event).encode("utf-8")
             if len(data) > self.MAX_RECORD_BYTES:
                 self.dropped_oversized += 1
-                sys.stderr.write(
-                    f"log-foundry: FirehoseSink dropped an event of {len(data)} bytes exceeding "
-                    f"the {self.MAX_RECORD_BYTES}-byte per-record limit\n"
+                _diag.lost(
+                    "event",
+                    1,
+                    f"FirehoseSink, {len(data)} bytes exceeds the "
+                    f"{self.MAX_RECORD_BYTES}-byte per-record limit",
                 )
                 continue
             records.append({"Data": data})
@@ -89,10 +91,12 @@ class FirehoseSink:
             verdict = adjudicate_positional(records, results)
             if verdict.unadjudicated:
                 self.dropped_unadjudicated += verdict.unadjudicated
-                sys.stderr.write(
-                    f"log-foundry: FirehoseSink could not adjudicate a put_record_batch response "
+                _diag.lost(
+                    "record",
+                    verdict.unadjudicated,
+                    f"FirehoseSink could not adjudicate a put_record_batch response "
                     f"({len(records)} record(s) sent, {len(results)} result(s) returned); "
-                    f"{verdict.unadjudicated} record(s) abandoned\n"
+                    f"abandoned, not retried",
                 )
                 return
             records = verdict.retry
@@ -100,8 +104,9 @@ class FirehoseSink:
                 return
             if attempt >= self.max_retries:
                 self.failed += len(records)
-                sys.stderr.write(
-                    f"log-foundry: {len(records)} Firehose record(s) still failing after "
-                    f"{self.max_retries + 1} attempts; abandoned\n"
+                _diag.lost(
+                    "record",
+                    len(records),
+                    f"FirehoseSink, still failing after {self.max_retries + 1} attempts; abandoned",
                 )
                 return

{log_foundry-0.10.2.dev12 → log_foundry-0.10.2.dev14}/src/log_foundry/sinks/http.py

@@ -15,13 +15,14 @@ from __future__ import annotations
 
 import gzip as _gzip
 import json
-import sys
 import time
 import urllib.error
 import urllib.request
 from base64 import b64encode
 from typing import TYPE_CHECKING, Any
 
+from log_foundry import _diag
+
 if TYPE_CHECKING:
     from collections.abc import Callable
 
@@ -128,7 +129,11 @@ class HTTPSink:
                 if attempt < self.max_retries:
                     self._sleep_backoff(attempt, None)
                     continue
-                self._abandon(f"connection error: {err!r}")
+                # The type plus the OS code, never the message: a ``URLError``'s text embeds the
+                # URL and whatever the resolver said (SPEC-029 FR-002).
+                self._abandon(
+                    f"connection error, {type(err).__name__} {_diag.errno_of(err)}".rstrip()
+                )
                 return None
             if 200 <= status < 300:
                 return payload
@@ -198,11 +203,14 @@ class HTTPSink:
         time.sleep(delay)
 
     def _abandon(self, reason: str) -> None:
-        """Count and log a request abandoned past the retry bound (FR-012)."""
+        """Count and log a request abandoned past the retry bound (FR-012).
+
+        ``reason`` carries only library-controlled values — an HTTP status, an exception type, an
+        ``errno`` — never a server-supplied body or an exception's text (SPEC-029 FR-002).
+        """
         self.failed += 1
-        sys.stderr.write(
-            f"log-foundry: {type(self).__name__} abandoned a request after "
-            f"{self.max_retries + 1} attempt(s) ({reason})\n"
+        _diag.lost(
+            "request", 1, f"{type(self).__name__}, {self.max_retries + 1} attempt(s), {reason}"
         )
 
 

{log_foundry-0.10.2.dev12 → log_foundry-0.10.2.dev14}/src/log_foundry/sinks/kafka.py

@@ -10,9 +10,10 @@ raised out of ``emit``.
 from __future__ import annotations
 
 import json
-import sys
 from typing import Any
 
+from log_foundry import _diag
+
 __all__ = ["KafkaSink"]
 
 
@@ -65,7 +66,34 @@ class KafkaSink:
         return str(value).encode("utf-8") if value is not None else None
 
     def _on_delivery(self, err: object, msg: object) -> None:
-        """confluent-kafka delivery callback: count and log failures (FR-002)."""
+        """confluent-kafka delivery callback: count and log failures (FR-002).
+
+        ``err`` is a ``KafkaError``, not an exception, so it goes to :func:`~_diag.lost` rather
+        than :func:`~_diag.absorbed`. Its ``str`` is a human message that can quote the record, so
+        only the type and the numeric ``code()`` are written — the code is librdkafka's own
+        enumeration and is what makes a delivery failure diagnosable (SPEC-029 FR-002).
+        """
         if err is not None:
             self.failed += 1
-            sys.stderr.write(f"log-foundry: KafkaSink delivery failed: {err!r}\n")
+            _diag.lost("message", 1, f"KafkaSink delivery, {type(err).__name__}{_code(err)}")
+
+
+def _code(err: object) -> str:
+    """Render a ``KafkaError``'s numeric code as ``" code=N"``, or ``""`` if it has none.
+
+    ``code()`` is a method on confluent-kafka's ``KafkaError``, returns one of librdkafka's
+    integer constants, and carries no caller data. Deliberately narrow: only an ``int`` is written,
+    so a stub or a future version returning something else contributes nothing rather than
+    smuggling text past the type-name rule.
+
+    Total, and the ``int()`` is inside the guard for the same reason ``_diag.errno_of`` puts it
+    there: ``isinstance(code, int)`` admits a *subclass*, whose ``__int__`` is Python that can
+    raise — and this runs in a delivery callback, so an escaping exception would surface from
+    ``emit`` and cost the whole batch. A diagnostic can never be the failure (SPEC-029 FR-003).
+    """
+    try:
+        code = getattr(err, "code", None)
+        value = code() if callable(code) else None
+        return f" code={int(value)}" if isinstance(value, int) else ""
+    except Exception:
+        return ""

{log_foundry-0.10.2.dev12 → log_foundry-0.10.2.dev14}/src/log_foundry/sinks/kinesis.py

@@ -10,9 +10,9 @@ unless a sink is built without an injected client. Each incoming batch is re-chu
 from __future__ import annotations
 
 import json
-import sys
 from typing import Any
 
+from log_foundry import _diag
 from log_foundry.sinks._batch import adjudicate_positional, usable_results
 from log_foundry.sinks._chunk import chunk_items
 
@@ -77,9 +77,11 @@ class KinesisSink:
             data = json.dumps(event).encode("utf-8")
             if len(data) > self.MAX_RECORD_BYTES:
                 self.dropped_oversized += 1
-                sys.stderr.write(
-                    f"log-foundry: KinesisSink dropped an event of {len(data)} bytes exceeding "
-                    f"the {self.MAX_RECORD_BYTES}-byte per-record limit\n"
+                _diag.lost(
+                    "event",
+                    1,
+                    f"KinesisSink, {len(data)} bytes exceeds the "
+                    f"{self.MAX_RECORD_BYTES}-byte per-record limit",
                 )
                 continue
             key = str(event.get(self.partition_key_field) or "log-foundry")[:256]
@@ -96,10 +98,11 @@ class KinesisSink:
             verdict = adjudicate_positional(records, results)
             if verdict.unadjudicated:
                 self.dropped_unadjudicated += verdict.unadjudicated
-                sys.stderr.write(
-                    f"log-foundry: KinesisSink could not adjudicate a put_records response "
-                    f"({len(records)} record(s) sent, {len(results)} result(s) returned); "
-                    f"{verdict.unadjudicated} record(s) abandoned\n"
+                _diag.lost(
+                    "record",
+                    verdict.unadjudicated,
+                    f"KinesisSink could not adjudicate a put_records response ({len(records)} "
+                    f"record(s) sent, {len(results)} result(s) returned); abandoned, not retried",
                 )
                 return
             records = verdict.retry
@@ -107,8 +110,9 @@ class KinesisSink:
                 return
             if attempt >= self.max_retries:
                 self.failed += len(records)
-                sys.stderr.write(
-                    f"log-foundry: {len(records)} Kinesis record(s) still failing after "
-                    f"{self.max_retries + 1} attempts; abandoned\n"
+                _diag.lost(
+                    "record",
+                    len(records),
+                    f"KinesisSink, still failing after {self.max_retries + 1} attempts; abandoned",
                 )
                 return

{log_foundry-0.10.2.dev12 → log_foundry-0.10.2.dev14}/src/log_foundry/sinks/mongodb.py

@@ -10,10 +10,11 @@ documents retained. Write-only — querying is the downstream tool's job.
 from __future__ import annotations
 
 import json
-import sys
 import time
 from typing import Any
 
+from log_foundry import _diag
+
 __all__ = ["MongoDBSink"]
 
 _BACKOFF_BASE = 0.1
@@ -66,18 +67,18 @@ class MongoDBSink:
                     # do not retry (successes are already in, a retry would duplicate/re-error).
                     rejects = len(details["writeErrors"])
                     self.failed += rejects
-                    sys.stderr.write(
-                        f"log-foundry: MongoDBSink had {rejects} document(s) rejected by a bulk "
-                        f"write; the rest were inserted\n"
+                    _diag.lost(
+                        "document", rejects, "MongoDBSink bulk write; the rest were inserted"
                     )
                     return
                 if attempt < self.max_retries:
                     time.sleep(_BACKOFF_BASE * (2**attempt))
                     continue
                 self.failed += len(documents)
-                sys.stderr.write(
-                    f"log-foundry: MongoDBSink abandoned {len(documents)} document(s) after "
-                    f"{self.max_retries + 1} attempts ({err!r})\n"
+                _diag.lost(
+                    "document",
+                    len(documents),
+                    f"MongoDBSink, {self.max_retries + 1} attempts, {type(err).__name__}",
                 )
                 return
 
@@ -97,9 +98,7 @@ class MongoDBSink:
         for event in batch:
             if len(json.dumps(event).encode("utf-8")) > _MAX_DOC_BYTES:
                 self.dropped_oversized += 1
-                sys.stderr.write(
-                    "log-foundry: MongoDBSink dropped a document exceeding the 16 MB limit\n"
-                )
+                _diag.lost("document", 1, "MongoDBSink, exceeds the 16 MB limit")
                 continue
             documents.append(dict(event))
         return documents

{log_foundry-0.10.2.dev12 → log_foundry-0.10.2.dev14}/src/log_foundry/sinks/multi.py

@@ -16,9 +16,10 @@ has nothing to retry.
 
 from __future__ import annotations
 
-import sys
 from typing import TYPE_CHECKING
 
+from log_foundry import _diag
+
 if TYPE_CHECKING:
     from log_foundry.sinks.base import Sink
 
@@ -58,9 +59,10 @@ class MultiSink:
                 self.failed += 1
                 if first_error is None:
                     first_error = err
-                sys.stderr.write(
-                    f"log-foundry: MultiSink child {type(sink).__name__}.emit "
-                    f"failed and was skipped: {err!r}\n"
+                # The class name goes in the *detail*, not in ``where``: only the detail is
+                # bounded, and a child's ``__name__`` is a runtime value (SPEC-029 FR-002).
+                _diag.absorbed(
+                    "emitting to a MultiSink child", err, f"{type(sink).__name__} skipped"
                 )
             else:
                 delivered += 1
@@ -78,7 +80,4 @@ class MultiSink:
                 sink.close()
             except Exception as err:  # close-all: an earlier failure must not skip the rest
                 self.failed += 1
-                sys.stderr.write(
-                    f"log-foundry: MultiSink child {type(sink).__name__}.close "
-                    f"failed and was skipped: {err!r}\n"
-                )
+                _diag.absorbed("closing a MultiSink child", err, f"{type(sink).__name__} skipped")

{log_foundry-0.10.2.dev12 → log_foundry-0.10.2.dev14}/src/log_foundry/sinks/nats.py

@@ -11,9 +11,10 @@ from __future__ import annotations
 
 import asyncio
 import json
-import sys
 from typing import Any
 
+from log_foundry import _diag
+
 __all__ = ["NATSSink"]
 
 
@@ -64,7 +65,7 @@ class NATSSink:
                 await target.publish(self._subject, json.dumps(event).encode("utf-8"))
             except Exception as err:  # isolation boundary: never crash the worker (FR-011)
                 self.failed += 1
-                sys.stderr.write(f"log-foundry: NATSSink publish failed: {err!r}\n")
+                _diag.lost("event", 1, f"NATSSink publish, {type(err).__name__}")
 
     async def _drain(self) -> None:
         drain = getattr(self._client, "drain", None)

{log_foundry-0.10.2.dev12 → log_foundry-0.10.2.dev14}/src/log_foundry/sinks/postgres.py

@@ -10,10 +10,10 @@ convenience is off by default — the user owns their schema and indexes.
 from __future__ import annotations
 
 import json
-import sys
 import time
 from typing import Any
 
+from log_foundry import _diag
 from log_foundry.sinks._chunk import chunk_list, valid_identifier
 
 __all__ = ["PostgresSink"]
@@ -71,9 +71,14 @@ class PostgresSink:
                     time.sleep(_BACKOFF_BASE * (2**attempt))
                     continue
                 self.failed += len(batch)
-                sys.stderr.write(
-                    f"log-foundry: PostgresSink abandoned {len(batch)} event(s) after "
-                    f"{self.max_retries + 1} attempts ({err!r})\n"
+                # The type, never the repr. ``_row`` binds the whole ``json.dumps(event)`` as a
+                # statement parameter, and a psycopg error repr routinely reprints the failing
+                # statement *and* its parameters — so the old line reprinted the event, PII
+                # included, into a stream nobody was asked to secure (SPEC-029 FR-002, arch §6).
+                _diag.lost(
+                    "event",
+                    len(batch),
+                    f"PostgresSink, {self.max_retries + 1} attempts, {type(err).__name__}",
                 )
                 return
 

{log_foundry-0.10.2.dev12 → log_foundry-0.10.2.dev14}/src/log_foundry/sinks/pubsub.py

@@ -9,9 +9,10 @@ are counted and logged.
 from __future__ import annotations
 
 import json
-import sys
 from typing import Any
 
+from log_foundry import _diag
+
 __all__ = ["GooglePubSubSink"]
 
 
@@ -41,5 +42,5 @@ class GooglePubSubSink:
                 future.result()
             except Exception as err:  # isolation boundary: never crash the worker (FR-011)
                 self.failed += 1
-                sys.stderr.write(f"log-foundry: GooglePubSubSink publish failed: {err!r}\n")
+                _diag.lost("event", 1, f"GooglePubSubSink publish, {type(err).__name__}")
         self._futures.clear()

{log_foundry-0.10.2.dev12 → log_foundry-0.10.2.dev14}/src/log_foundry/sinks/rabbitmq.py

@@ -9,10 +9,11 @@ and counted; ``close()`` closes the channel and connection.
 from __future__ import annotations
 
 import json
-import sys
 import time
 from typing import Any
 
+from log_foundry import _diag
+
 __all__ = ["RabbitMQSink"]
 
 _BACKOFF_BASE = 0.1
@@ -83,9 +84,10 @@ class RabbitMQSink:
                     time.sleep(_BACKOFF_BASE * (2**attempt))
                     continue
                 self.failed += 1
-                sys.stderr.write(
-                    f"log-foundry: RabbitMQSink abandoned a message after "
-                    f"{self._max_retries + 1} attempts ({err!r})\n"
+                _diag.lost(
+                    "message",
+                    1,
+                    f"RabbitMQSink, {self._max_retries + 1} attempts, {type(err).__name__}",
                 )
                 return
 

{log_foundry-0.10.2.dev12 → log_foundry-0.10.2.dev14}/src/log_foundry/sinks/redis.py

@@ -11,10 +11,11 @@ shadows or requires the real ``redis`` package at import time.
 from __future__ import annotations
 
 import json
-import sys
 import time
 from typing import Any
 
+from log_foundry import _diag
+
 __all__ = ["RedisListSink", "RedisStreamsSink"]
 
 _BACKOFF_BASE = 0.1
@@ -49,9 +50,10 @@ class _RedisSink:
                     time.sleep(_BACKOFF_BASE * (2**attempt))
                     continue
                 self.failed += len(batch)
-                sys.stderr.write(
-                    f"log-foundry: {type(self).__name__} abandoned {len(batch)} event(s) after "
-                    f"{self.max_retries + 1} attempts ({err!r})\n"
+                _diag.lost(
+                    "event",
+                    len(batch),
+                    f"{type(self).__name__}, {self.max_retries + 1} attempts, {type(err).__name__}",
                 )
                 return
 

{log_foundry-0.10.2.dev12 → log_foundry-0.10.2.dev14}/src/log_foundry/sinks/sns.py

@@ -8,9 +8,9 @@ request, ≤ 256 KB total). ``boto3`` is the optional ``aws`` extra, imported la
 from __future__ import annotations
 
 import json
-import sys
 from typing import Any
 
+from log_foundry import _diag
 from log_foundry.sinks._chunk import chunk_items
 
 __all__ = ["SNSSink"]
@@ -53,10 +53,7 @@ class SNSSink:
             body = json.dumps(event)
             if len(body.encode("utf-8")) > self.MAX_BYTES:
                 self.dropped_oversized += 1
-                sys.stderr.write(
-                    f"log-foundry: SNSSink dropped an event exceeding the "
-                    f"{self.MAX_BYTES}-byte message limit\n"
-                )
+                _diag.lost("event", 1, f"SNSSink, exceeds the {self.MAX_BYTES}-byte message limit")
                 continue
             bodies.append(body)
         return bodies
@@ -75,8 +72,9 @@ class SNSSink:
             entries = [entry for entry in entries if entry["Id"] in failed_ids]
             if attempt >= self.max_retries:
                 self.failed += len(entries)
-                sys.stderr.write(
-                    f"log-foundry: {len(entries)} SNS message(s) still failing after "
-                    f"{self.max_retries + 1} attempts; abandoned\n"
+                _diag.lost(
+                    "message",
+                    len(entries),
+                    f"SNSSink, still failing after {self.max_retries + 1} attempts; abandoned",
                 )
                 return

{log_foundry-0.10.2.dev12 → log_foundry-0.10.2.dev14}/src/log_foundry/sinks/sqs.py

@@ -31,10 +31,11 @@ is not done.
 from __future__ import annotations
 
 import json
-import sys
 from collections.abc import Callable
 from typing import Any, NamedTuple
 
+from log_foundry import _diag
+
 __all__ = ["SQSSink"]
 
 DEFAULT_GROUP_ID = "log-foundry"
@@ -173,9 +174,10 @@ class SQSSink:
                 size += len(group_id.encode("utf-8")) + len(dedup_id.encode("utf-8"))
             if size > self.MAX_BYTES:
                 self.dropped_oversized += 1
-                sys.stderr.write(
-                    f"log-foundry: dropped an event of {size} bytes exceeding the "
-                    f"{self.MAX_BYTES}-byte SQS message limit\n"
+                _diag.lost(
+                    "event",
+                    1,
+                    f"SQSSink, {size} bytes exceeds the {self.MAX_BYTES}-byte message limit",
                 )
                 continue
             if current and (
@@ -223,9 +225,14 @@ class SQSSink:
             sender_faults = [item for item in failed if item.get("SenderFault")]
             if sender_faults:
                 self.failed += len(sender_faults)
-                sys.stderr.write(
-                    f"log-foundry: {len(sender_faults)} SQS message(s) rejected as invalid "
-                    f"(first code: {sender_faults[0].get('Code', 'unknown')}); not retried\n"
+                # The AWS error code is library-controlled in the sense that matters — it is an
+                # enumerated API constant, not the event — and ``_diag`` bounds and escapes it
+                # regardless, so a surprising response shape cannot forge a line (SPEC-029).
+                _diag.lost(
+                    "message",
+                    len(sender_faults),
+                    f"SQSSink, rejected as invalid (first code: "
+                    f"{sender_faults[0].get('Code', 'unknown')}); not retried",
                 )
 
             retryable_ids = {item["Id"] for item in failed if not item.get("SenderFault")}
@@ -234,8 +241,9 @@ class SQSSink:
             entries = [entry for entry in entries if entry["Id"] in retryable_ids]
             if attempt >= self.max_retries:
                 self.failed += len(entries)
-                sys.stderr.write(
-                    f"log-foundry: {len(entries)} SQS message(s) still failing after "
-                    f"{self.max_retries + 1} attempts; abandoned\n"
+                _diag.lost(
+                    "message",
+                    len(entries),
+                    f"SQSSink, still failing after {self.max_retries + 1} attempts; abandoned",
                 )
                 return

{log_foundry-0.10.2.dev12 → log_foundry-0.10.2.dev14}/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