log-foundry 0.5.1.dev8__tar.gz → 0.5.1.dev10__tar.gz

{log_foundry-0.5.1.dev8 → log_foundry-0.5.1.dev10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: log-foundry
-Version: 0.5.1.dev8
+Version: 0.5.1.dev10
 Summary: Generate logs for your console and JSON events for downstream consumption.
 License-Expression: MIT
 License-File: LICENSE
@@ -395,6 +395,9 @@ A few conventions hold across every sink below:
   open for you to manage.
 - **Never crashes the app.** A failing sink is retried with backoff and then counted (`.failed`,
   `.dropped_oversized`, …) rather than raised — a broken destination degrades logging, nothing more.
+  The one deliberate exception is a `MultiSink` whose children *all* failed: it re-raises so the
+  worker's retry engages, since nothing was delivered and there are no duplicates to risk. That
+  still doesn't reach your code — the worker is what catches it.
 
 #### Built-in, zero-dependency
 
@@ -612,7 +615,22 @@ background worker via a fast, non-blocking submit — your function returns with
 the sink. The worker batches events (by count and time), emits them on its own thread, retries
 a failing sink with backoff, and applies backpressure so a slow or down sink can never block or
 back-pressure the app: when its bounded queue is full it drops the newest submissions and counts
-them (`worker.dropped`) rather than stalling.
+them rather than stalling.
+
+Those losses are deliberate, so the library gives you a way to notice them. `log_foundry.health()`
+returns a snapshot of the worker's counters:
+
+```python
+h = log_foundry.health()
+if h.dropped or h.failed_batches:
+    ...  # logs were silently lost — worth an alert
+```
+
+`dropped` counts submissions discarded because the queue filled; `failed_batches` counts batches
+abandoned after the retry budget was spent. Overflow also warns on stderr — on the first drop and
+every thousandth after it, since overflow is a high-rate condition and a line per drop would be its
+own outage. A process that has never logged has no worker, and asking after its health does not
+create one.
 
 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:

{log_foundry-0.5.1.dev8 → log_foundry-0.5.1.dev10}/README.md

@@ -359,6 +359,9 @@ A few conventions hold across every sink below:
   open for you to manage.
 - **Never crashes the app.** A failing sink is retried with backoff and then counted (`.failed`,
   `.dropped_oversized`, …) rather than raised — a broken destination degrades logging, nothing more.
+  The one deliberate exception is a `MultiSink` whose children *all* failed: it re-raises so the
+  worker's retry engages, since nothing was delivered and there are no duplicates to risk. That
+  still doesn't reach your code — the worker is what catches it.
 
 #### Built-in, zero-dependency
 
@@ -576,7 +579,22 @@ background worker via a fast, non-blocking submit — your function returns with
 the sink. The worker batches events (by count and time), emits them on its own thread, retries
 a failing sink with backoff, and applies backpressure so a slow or down sink can never block or
 back-pressure the app: when its bounded queue is full it drops the newest submissions and counts
-them (`worker.dropped`) rather than stalling.
+them rather than stalling.
+
+Those losses are deliberate, so the library gives you a way to notice them. `log_foundry.health()`
+returns a snapshot of the worker's counters:
+
+```python
+h = log_foundry.health()
+if h.dropped or h.failed_batches:
+    ...  # logs were silently lost — worth an alert
+```
+
+`dropped` counts submissions discarded because the queue filled; `failed_batches` counts batches
+abandoned after the retry budget was spent. Overflow also warns on stderr — on the first drop and
+every thousandth after it, since overflow is a high-rate condition and a line per drop would be its
+own outage. A process that has never logged has no worker, and asking after its health does not
+create one.
 
 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:

{log_foundry-0.5.1.dev8 → log_foundry-0.5.1.dev10}/pyproject.toml

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

{log_foundry-0.5.1.dev8 → log_foundry-0.5.1.dev10}/src/log_foundry/__init__.py

@@ -18,6 +18,7 @@ from log_foundry.context import (
     current_traceparent,
 )
 from log_foundry.decorator import continue_trace, trace
+from log_foundry.worker import Health
 
 try:
     # Distribution name ("log-foundry") differs from the import name ("log_foundry").
@@ -49,6 +50,27 @@ def flush(timeout: float | None = 5.0) -> bool:
     return _flush_worker(timeout)
 
 
+def health() -> Health:
+    """Snapshot the background worker's delivery counters (SPEC-017 FR-005). Never raises.
+
+    Returns ``queued`` / ``dropped`` / ``failed_batches``. A non-zero ``dropped`` means the queue
+    filled and submissions were discarded to keep your code non-blocking; a non-zero
+    ``failed_batches`` means a sink stayed broken through the whole retry budget. Both are
+    losses the library absorbs on purpose, and this is how you notice them::
+
+        h = log_foundry.health()
+        if h.dropped or h.failed_batches:
+            ...  # raise an alert; logs were silently lost
+
+    A process that has never logged has no worker, and asking after its health does not create
+    one — the snapshot is simply zeroed. Valid after :func:`shutdown`, which leaves the final
+    counters readable.
+    """
+    from log_foundry.decorator import _worker_health
+
+    return _worker_health()
+
+
 def shutdown() -> None:
     """Flush buffered events and close the sink, blocking until drained. Idempotent.
 
@@ -80,5 +102,7 @@ __all__ = [
     "current_baggage_header",
     "flush",
     "shutdown",
+    "health",
+    "Health",
     "__version__",
 ]

{log_foundry-0.5.1.dev8 → log_foundry-0.5.1.dev10}/src/log_foundry/decorator.py

@@ -40,7 +40,7 @@ from log_foundry.ids import (
     parse_traceparent,
 )
 from log_foundry.model import Span, backfill_baggage, end_event, start_event
-from log_foundry.worker import Worker
+from log_foundry.worker import Health, Worker
 
 __all__ = ["trace", "continue_trace"]
 
@@ -235,6 +235,19 @@ def _flush_worker(timeout: float | None = 5.0) -> bool:
         return False
 
 
+def _worker_health() -> Health:
+    """Snapshot the process worker's counters, or zeros if none was ever created.
+
+    Backs :func:`log_foundry.health` (SPEC-017 FR-005). Like :func:`_flush_worker` this
+    deliberately does *not* call :func:`_get_worker`: starting a thread and registering an
+    ``atexit`` drain in order to report three zeros would be pure cost.
+    """
+    worker = _worker
+    if worker is None:
+        return Health(queued=0, dropped=0, failed_batches=0)
+    return worker.health()
+
+
 def _flush(span: Span) -> None:
     """Hand the finished span's events to the background worker — non-blocking (FR-001).
 

{log_foundry-0.5.1.dev8 → log_foundry-0.5.1.dev10}/src/log_foundry/model.py

@@ -70,8 +70,13 @@ def build_event(
     → per-call ``fields`` (arch §5.1). Later sources win on a key conflict.
 
     The merged mapping is coerced and size-bounded here (SPEC-017 FR-001/FR-002), which is what
-    makes every sink's bare ``json.dumps`` safe without any of them changing. ``message`` is
-    bounded too: it is a base field, but unlike the other eleven it is caller-supplied free text.
+    makes every sink's bare ``json.dumps`` safe without any of them changing.
+
+    ``message`` and ``function`` are bounded too. They are base fields, but unlike the other ten
+    both are caller-supplied text: ``message`` directly, and ``function`` via ``@trace(name=...)``
+    or — on the orphan path, where ``api`` names the standalone span after the message itself —
+    from the same unbounded string. Leaving either out would keep ``info(huge_string)`` unbounded,
+    which is the hole this ceiling exists to close.
     """
     from log_foundry.config import get_config
     from log_foundry.ids import new_log_id
@@ -80,6 +85,7 @@ def build_event(
     merged: dict[str, object] = {**cfg.defaults, **span.defaults, **baggage, **fields}
     safe, clipped = sanitize_fields(merged, cfg=cfg)
     bounded_message, message_clipped = truncate_str(message, cfg.max_value_bytes)
+    bounded_function, function_clipped = truncate_str(span.name, cfg.max_value_bytes)
     event: dict[str, object] = {
         "timestamp": _iso_now(),
         "level": level,
@@ -88,13 +94,13 @@ def build_event(
         "span_id": span.span_id,
         "parent_span_id": span.parent_span_id,
         "log_id": new_log_id(),
-        "function": span.name,
+        "function": bounded_function,
         "service": cfg.service,
         "version": cfg.version,
         "env": cfg.env,
     }
     # Before ``fields`` so it reads ahead of the payload blob in a rendered log line.
-    if clipped or message_clipped:
+    if clipped or message_clipped or function_clipped:
         event[_TRUNCATED] = True
     event["fields"] = safe
     return event

{log_foundry-0.5.1.dev8 → log_foundry-0.5.1.dev10}/src/log_foundry/sanitize.py

@@ -254,8 +254,9 @@ class _Coercer:
 def coerce(value: object, *, cfg: Config) -> object:
     """Return a JSON-serializable, size-bounded equivalent of ``value``. Never raises.
 
-    Use :func:`sanitize_fields` for a whole event mapping — it reports whether a ceiling fired,
-    which this cannot.
+    ``value`` is treated as a field value, i.e. depth 0 — the same level it would occupy inside
+    an event's ``fields``. Use :func:`sanitize_fields` for a whole event mapping; it reports
+    whether a ceiling fired, which this cannot.
     """
     return _Coercer(cfg).value(value, 0)
 
@@ -271,7 +272,11 @@ def sanitize_fields(
     """
     coercer = _Coercer(cfg)
     try:
-        result = coercer.mapping(fields, 0)
+        # ``-1`` so the *values* of the top-level mapping sit at depth 0: ``fields`` is the event's
+        # payload container, not a level of nesting the caller chose. Otherwise ``max_depth=1``
+        # would replace every field value with ``<depth limit>`` and emit a uniformly empty event,
+        # which is exactly what FR-006's validation exists to prevent.
+        result = coercer.mapping(fields, -1)
     except Exception:  # noqa: BLE001 — belt and braces: `_Coercer.value` is already total, but
         return {}, True  # a hostile top-level mapping must not reach the caller either.
     if not isinstance(result, dict):

{log_foundry-0.5.1.dev8 → log_foundry-0.5.1.dev10}/src/log_foundry/sinks/multi.py

@@ -27,7 +27,11 @@ class MultiSink:
     """A :class:`~log_foundry.sinks.base.Sink` that forwards each batch to every child sink.
 
     Attributes:
-        failed: Count of child ``emit``/``close`` calls that raised and were isolated.
+        failed: Count of child ``emit``/``close`` **calls** that raised. Note this counts calls,
+            not batches: since total failure re-raises (SPEC-017 FR-004), the worker retries the
+            same batch, so one batch against an all-down fan-out of *n* children increments this
+            by *n* per attempt — ``n * (max_retries + 1)`` in total, with a stderr line each.
+            That is the visible cost of the loss no longer being silent.
     """
 
     def __init__(self, *sinks: Sink) -> None:

{log_foundry-0.5.1.dev8 → log_foundry-0.5.1.dev10}/src/log_foundry/worker.py

@@ -23,16 +23,36 @@ import queue
 import sys
 import threading
 import time
-from typing import cast
+from typing import NamedTuple, cast
 
 from log_foundry.sinks.base import Sink
 
-__all__ = ["Worker"]
+__all__ = ["Health", "Worker"]
 
 # Sentinel enqueued by shutdown() to wake a worker blocked in queue.get() so it stops promptly
 # instead of waiting out the flush_interval. It is never emitted.
 _SHUTDOWN = object()
 
+# Queue overflow is a high-rate condition by nature: a line per dropped submission would be its
+# own outage. Warn on the first drop, then every this-many-th (SPEC-017 FR-005).
+_DROP_WARN_EVERY = 1000
+
+
+class Health(NamedTuple):
+    """A point-in-time snapshot of the worker's delivery counters (SPEC-017 FR-005).
+
+    Attributes:
+        queued: Submissions currently buffered. Approximate by nature — it is read without
+            stopping the world, and briefly counts the internal flush/shutdown markers
+            alongside real submissions.
+        dropped: Submissions discarded because the queue was full (backpressure).
+        failed_batches: Batches abandoned after the retry budget was spent.
+    """
+
+    queued: int
+    dropped: int
+    failed_batches: int
+
 
 class _FlushMarker:
     """A drain request travelling the queue in FIFO order (SPEC-013 FR-002).
@@ -87,13 +107,41 @@ class Worker:
 
         Enqueues via ``put_nowait`` and returns immediately without touching the sink. When the
         queue is full, drops this submission (drop-newest) and counts it in ``dropped`` rather
-        than blocking the caller (FR-001, FR-004).
+        than blocking the caller (FR-001, FR-004), warning on a throttle (SPEC-017 FR-005).
         """
         try:
             self._queue.put_nowait(events)
         except queue.Full:
             with self._lock:
                 self.dropped += 1
+                total = self.dropped  # read under the lock: every value is produced exactly once
+            # Written outside the lock deliberately. stderr can block on a slow reader, and
+            # ``_lock`` also guards flush()/shutdown()'s once-only flag — holding it across a
+            # blocking write would let a wedged console stall the drain path, not just other
+            # 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:  # noqa: BLE001 — 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
+
+    def health(self) -> Health:
+        """Snapshot the delivery counters (SPEC-017 FR-005). Never raises.
+
+        Valid after :meth:`shutdown` — the counters are plain integers that outlive the thread,
+        and the final drain consumes the queue, so ``queued`` reads 0 rather than a stale marker.
+        """
+        with self._lock:
+            dropped, failed_batches = self.dropped, self.failed_batches
+        return Health(
+            queued=self._queue.qsize(), dropped=dropped, failed_batches=failed_batches
+        )
 
     def flush(self, timeout: float | None = 5.0) -> bool:
         """Drain everything submitted before this call through the sink, without stopping.
@@ -221,7 +269,10 @@ class Worker:
                 return
             except Exception:  # noqa: BLE001 — any sink failure must not kill the worker thread
                 if attempt >= self.max_retries:
-                    self.failed_batches += 1
+                    # Under the lock so a concurrent health() sees a coherent snapshot rather
+                    # 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"{self.max_retries + 1} failed emit attempts\n"