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

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

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

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

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

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

@@ -12,6 +12,12 @@ import time
 import traceback
 from dataclasses import dataclass, field
 from datetime import datetime, timezone
+from typing import TYPE_CHECKING
+
+from log_foundry.sanitize import sanitize_fields, truncate_str, truncate_tail
+
+if TYPE_CHECKING:
+    from log_foundry.config import Config
 
 __all__ = ["Span", "build_event", "start_event", "end_event", "backfill_baggage"]
 
@@ -20,6 +26,11 @@ __all__ = ["Span", "build_event", "start_event", "end_event", "backfill_baggage"
 _START_MESSAGE = "span.start"
 _END_MESSAGE = "span.end"
 
+# Marks an event that a ceiling clipped (SPEC-017 FR-002). Set **only ever to True**, never to
+# False — that single invariant is what makes "OR with whatever an earlier stage set" and
+# "absent, not false, on a clean event" both fall out with no read-modify-write anywhere.
+_TRUNCATED = "truncated"
+
 
 @dataclass
 class Span:
@@ -57,16 +68,22 @@ def build_event(
 
     Field precedence, lowest to highest: config ``defaults`` → ``span.defaults`` → ``baggage``
     → 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.
     """
     from log_foundry.config import get_config
     from log_foundry.ids import new_log_id
 
     cfg = get_config()
     merged: dict[str, object] = {**cfg.defaults, **span.defaults, **baggage, **fields}
-    return {
+    safe, clipped = sanitize_fields(merged, cfg=cfg)
+    bounded_message, message_clipped = truncate_str(message, cfg.max_value_bytes)
+    event: dict[str, object] = {
         "timestamp": _iso_now(),
         "level": level,
-        "message": message,
+        "message": bounded_message,
         "trace_id": span.trace_id,
         "span_id": span.span_id,
         "parent_span_id": span.parent_span_id,
@@ -75,8 +92,12 @@ def build_event(
         "service": cfg.service,
         "version": cfg.version,
         "env": cfg.env,
-        "fields": merged,
     }
+    # Before ``fields`` so it reads ahead of the payload blob in a rendered log line.
+    if clipped or message_clipped:
+        event[_TRUNCATED] = True
+    event["fields"] = safe
+    return event
 
 
 def start_event(span: Span) -> dict[str, object]:
@@ -84,6 +105,57 @@ def start_event(span: Span) -> dict[str, object]:
     return build_event(span, "INFO", _START_MESSAGE, fields={}, baggage={})
 
 
+def _exception_message(exc: BaseException) -> str:
+    """``str(exc)`` — ``""`` for an exception raised with no arguments (SPEC-017 FR-003).
+
+    Guarded because a user exception may define a ``__str__`` that itself raises. This runs
+    inside the decorator's ``except`` block, so an exception escaping here would *replace* the
+    one the user's code raised, demoting theirs to ``__context__`` — logging breaking the app,
+    which is the thing this spec exists to stop.
+    """
+    try:
+        return str(exc)
+    except Exception:  # noqa: BLE001 — see above; a hostile __str__ must not escape.
+        return "<unprintable message>"
+
+
+def _exception_stack(exc: BaseException) -> str:
+    """The formatted traceback.
+
+    ``traceback.format_exception`` already renders a failing ``__str__`` as
+    ``<exception str() failed>`` rather than propagating, so this guard is for the rarer case of
+    a frame that cannot be rendered at all.
+    """
+    try:
+        return "".join(traceback.format_exception(type(exc), exc, exc.__traceback__))
+    except Exception:  # noqa: BLE001 — same reasoning as _exception_message.
+        return f"<unformattable traceback: {type(exc).__name__}>"
+
+
+def _error_fields(exc: BaseException, *, cfg: Config) -> tuple[dict[str, object], bool]:
+    """Build the bounded ``error`` sub-document; report whether a ceiling fired.
+
+    ``type`` keeps the bare class name consumers already index; ``module`` is added alongside it
+    so two same-named exception classes from different packages stay distinguishable, rather
+    than qualifying ``type`` in place and breaking every existing query (SPEC-017 FR-003).
+
+    ``stack`` gets its own, larger ceiling: a traceback is legitimately long and is the most
+    valuable thing on the event. It is clipped from the *head*, because ``format_exception``
+    puts the exception and the innermost frames last.
+    """
+    type_name, t1 = truncate_str(type(exc).__name__, cfg.max_value_bytes)
+    module, t2 = truncate_str(str(getattr(type(exc), "__module__", "")), cfg.max_value_bytes)
+    message, t3 = truncate_str(_exception_message(exc), cfg.max_value_bytes)
+    stack, t4 = truncate_tail(_exception_stack(exc), cfg.max_stack_bytes)
+    error: dict[str, object] = {
+        "type": type_name,
+        "module": module,
+        "message": message,
+        "stack": stack,
+    }
+    return error, (t1 or t2 or t3 or t4)
+
+
 def end_event(
     span: Span,
     status: str,
@@ -92,17 +164,20 @@ def end_event(
     """Build the span-end boundary event.
 
     Adds ``duration_ms`` (from a monotonic delta), ``status`` (``"ok"``/``"error"``), and on
-    failure a nested ``error`` with the exception type and formatted stack (arch §6).
+    failure a nested ``error`` with the exception type, module, message and formatted stack
+    (arch §6, SPEC-017 FR-003).
     """
+    from log_foundry.config import get_config
+
     level = "INFO" if status == "ok" else "ERROR"
     event = build_event(span, level, _END_MESSAGE, fields={}, baggage={})
     event["duration_ms"] = (time.monotonic() - span.start_ts) * 1000.0
     event["status"] = status
     if exc is not None:
-        event["error"] = {
-            "type": type(exc).__name__,
-            "stack": "".join(traceback.format_exception(type(exc), exc, exc.__traceback__)),
-        }
+        error, clipped = _error_fields(exc, cfg=get_config())
+        event["error"] = error
+        if clipped:
+            event[_TRUNCATED] = True  # only ever True — this *is* the OR with build_event's
     return event
 
 
@@ -123,13 +198,24 @@ def backfill_baggage(span: Span, baggage: dict[str, object]) -> None:
 
     The baggage is a parameter rather than read from ``context``: this module does not know where
     the current span lives (arch §6).
+
+    These values bypass :func:`build_event`'s pass entirely — ``set_baggage`` accepts arbitrary
+    objects — so they are coerced here, **once** above the loop rather than per event: the same
+    mapping is merged into every boundary event, and ``fields`` is already sanitized. The merge
+    can push a mapping past ``max_keys``; that is deliberate, because re-capping here would drop
+    the correlation keys SPEC-015 shipped to add (SPEC-017 FR-001).
     """
     if not baggage:
         return
+    from log_foundry.config import get_config
+
+    safe, clipped = sanitize_fields(baggage, cfg=get_config())
     for event in span.events:
         # Matched on the message constants, not a position — that ``span.start`` is index 0 is an
         # implementation detail of when it happens to be appended.
         if event.get("message") in (_START_MESSAGE, _END_MESSAGE):
             fields = event.get("fields")
             if isinstance(fields, dict):
-                event["fields"] = {**fields, **baggage}
+                event["fields"] = {**fields, **safe}
+                if clipped:
+                    event[_TRUNCATED] = True

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

@@ -6,6 +6,12 @@ whose ``emit`` (or ``close``) raises is isolated — the failure is counted on `
 logged to stderr, and its siblings still run — so one broken destination never fails the whole
 fan-out or the worker's retry. This mirrors the worker's own survive-a-sink-failure isolation
 boundary (arch §9; best-practices §7 sanctions the broad catch here).
+
+The one exception is **total** failure: if every child raised, ``emit`` re-raises rather than
+reporting success, so the worker's retry engages (SPEC-017 FR-004). Swallowing there meant a
+``MultiSink`` whose destinations were all down reported healthy on every batch and the loss was
+invisible. ``close()`` keeps the unconditional isolate-and-continue behaviour — a failed close
+has nothing to retry.
 """
 
 from __future__ import annotations
@@ -29,16 +35,35 @@ class MultiSink:
         self.failed = 0
 
     def emit(self, batch: list[dict[str, object]]) -> None:
-        """Forward ``batch`` to every child in construction order, isolating failures (FR-002)."""
+        """Forward ``batch`` to every child in construction order, isolating failures (FR-002).
+
+        When **every** child failed, re-raise the first child's exception so the worker's bounded
+        retry sees the total loss (SPEC-017 FR-004). Partial success stays isolated: a retry there
+        would re-deliver the batch to the children that already took it, and duplicates are worse
+        than the one failure already counted on ``failed`` and written to stderr. Total failure
+        delivered nothing, so it has no duplicates to create and is the one case worth retrying.
+        """
+        first_error: Exception | None = None
+        delivered = 0
         for sink in self._sinks:
             try:
                 sink.emit(batch)
             except Exception as err:  # isolation boundary: one child must not fail the rest
                 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"
                 )
+            else:
+                delivered += 1
+        if delivered == 0 and first_error is not None:
+            # Raised outside any ``except`` block, so ``__context__`` is untouched and the
+            # exception propagates by identity with its original traceback. The ``is not None``
+            # is also what keeps an empty ``MultiSink`` a no-op rather than a raise — otherwise a
+            # misconfigured fan-out with no children would retry every batch to exhaustion.
+            raise first_error
 
     def close(self) -> None:
         """Close every child, isolating a failing child so the rest still close (FR-002)."""