log-foundry 0.10.2.dev30__tar.gz → 0.10.2.dev31__tar.gz

{log_foundry-0.10.2.dev30 → log_foundry-0.10.2.dev31}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: log-foundry
-Version: 0.10.2.dev30
+Version: 0.10.2.dev31
 Summary: Generate logs for your console and JSON events for downstream consumption.
 License-Expression: MIT
 License-File: LICENSE
@@ -862,6 +862,15 @@ logging is doing the right thing; it is the *pair* — retired, and still being
 means every log line since the shutdown has gone nowhere. That state used to read as perfectly
 healthy: `stopped_reason` is `None` after a clean shutdown, and the queue simply grows.
 
+`retired` is also the one field reported for a process that has **no worker at all**. A program
+that only ever calls `info()`/`error()` outside a span emits synchronously and builds no background
+worker, so every other field describes something that does not exist and reads zero. Its
+`shutdown()` still closes the sink, exactly once and without starting a thread, and `retired` reads
+`True` afterwards rather than staying vacuously `False`. `submitted_after_shutdown` stays `0` there
+by design: a later level call is *refused* at the closed sink and announced on stderr — if the sink
+guards its own post-close state — rather than queued where nothing will drain it, and those are not
+the same claim. A stateless sink such as the default `StdoutSink` still accepts it.
+
 Read a snapshot by attribute (`h.dropped`), as above. `Health` is a `NamedTuple` and has gained
 fields over time — a fourth (`stopped_reason`) in `v0.7.0`, and a fifth (`sink`) plus four more
 (`retired`, `submitted_after_shutdown`, `incomplete_swaps`, `closing_sinks`) not yet in a tagged

{log_foundry-0.10.2.dev30 → log_foundry-0.10.2.dev31}/README.md

@@ -826,6 +826,15 @@ logging is doing the right thing; it is the *pair* — retired, and still being
 means every log line since the shutdown has gone nowhere. That state used to read as perfectly
 healthy: `stopped_reason` is `None` after a clean shutdown, and the queue simply grows.
 
+`retired` is also the one field reported for a process that has **no worker at all**. A program
+that only ever calls `info()`/`error()` outside a span emits synchronously and builds no background
+worker, so every other field describes something that does not exist and reads zero. Its
+`shutdown()` still closes the sink, exactly once and without starting a thread, and `retired` reads
+`True` afterwards rather than staying vacuously `False`. `submitted_after_shutdown` stays `0` there
+by design: a later level call is *refused* at the closed sink and announced on stderr — if the sink
+guards its own post-close state — rather than queued where nothing will drain it, and those are not
+the same claim. A stateless sink such as the default `StdoutSink` still accepts it.
+
 Read a snapshot by attribute (`h.dropped`), as above. `Health` is a `NamedTuple` and has gained
 fields over time — a fourth (`stopped_reason`) in `v0.7.0`, and a fifth (`sink`) plus four more
 (`retired`, `submitted_after_shutdown`, `incomplete_swaps`, `closing_sinks`) not yet in a tagged

{log_foundry-0.10.2.dev30 → log_foundry-0.10.2.dev31}/pyproject.toml

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

{log_foundry-0.10.2.dev30 → log_foundry-0.10.2.dev31}/src/log_foundry/__init__.py

@@ -98,7 +98,9 @@ def health() -> Health:
       ``failed`` is an upper bound on loss rather than a count of it, since a sink that raises
       on total failure counts the attempt and hands the batch back for the worker to retry. A
       process that has never logged has no worker, and asking does not create one — the
-      snapshot is simply zeroed. Valid after :func:`shutdown`.
+      snapshot is simply zeroed, except for ``retired``, which stays truthful even for a
+      process that only ever logged outside a span and so built no worker at all (SPEC-031
+      FR-006). Valid after :func:`shutdown`.
 
     Raises:
       None.
@@ -122,6 +124,15 @@ def shutdown(timeout: float | None = DEFAULT_SHUTDOWN_TIMEOUT) -> None:
     non-zero ``submitted_after_shutdown``, and the first such submission writes one stderr line
     (SPEC-030). That pair is the reading that catches the mistake above.
 
+    A process that only ever logged **outside** a span built no worker, and this used to be a
+    no-op there, leaving the sink open forever: every event lost on a sink whose ``close()`` is
+    what delivers them, the flush and the resource on a synchronous one. It now closes that
+    sink — exactly once, and without creating a worker to do it — and ``health().retired``
+    reads ``True`` afterwards rather than staying vacuously ``False`` (SPEC-031 FR-006). A
+    later level call reaches a closed sink, so a sink that guards its own post-close state
+    refuses it and one stderr line is written; a stateless one such as ``StdoutSink`` still
+    accepts it (SPEC-032).
+
     Args:
       timeout: Seconds bounding the wait for the background thread and, carved from the same
         budget, a short grace for any sink still closing after a late ``configure(sink=...)``

{log_foundry-0.10.2.dev30 → log_foundry-0.10.2.dev31}/src/log_foundry/api.py

@@ -6,6 +6,7 @@ from log_foundry import _diag, context
 from log_foundry.config import _ensure_sink
 from log_foundry.console import ConsoleWriter
 from log_foundry.context import set_baggage
+from log_foundry.decorator import _note_orphan_emit
 from log_foundry.ids import new_span_id, new_trace_id
 from log_foundry.model import Span, build_event
 
@@ -36,6 +37,21 @@ def _log(level: str, message: str, echo: bool, fields: dict[str, object]) -> Non
     logs"). It carried a comment saying the worker "will later" own it long after the
     decision was made (SPEC-031 FR-003).
 
+    Because no worker is built here, nothing else in the library knows the sink was ever
+    written to — so this branch records it (SPEC-031 FR-006). That is what arms the exit-time
+    close for a process which only ever logs this way, and keying it on a sink this call is
+    about to write to, rather than on a *configured* sink, is deliberate: ``configure()``
+    materializes a ``StdoutSink`` whether or not anything is logged through it, and closing one
+    nothing was ever written to is cost with no benefit.
+
+    It is armed **before** the emit rather than after it, which matters for the sinks most
+    likely to need the close. SPEC-026 FR-001 makes a total failure raise, so an orphan-only
+    process against a dead syslog or HTTP destination raises on every call — and arming
+    afterwards would leave the socket that failure came from open forever, which is the leak
+    this FR exists to stop, in exactly the case that is leaking. A sink that raised is still a
+    sink that was written to. ``_ensure_sink`` is resolved first, so a sink that fails to
+    *construct* arms nothing: there is nothing to close.
+
     The orphan branch is the one that reaches the sink on the caller's own thread, with no
     worker between them to absorb a failure, so the whole branch is guarded (SPEC-025
     FR-003) — ``_ensure_sink`` constructs the sink on first use, so a sink that fails to
@@ -72,7 +88,9 @@ def _log(level: str, message: str, echo: bool, fields: dict[str, object]) -> Non
                 start_ts=0.0,
             )
             event = build_event(orphan, level, message, fields=fields, baggage=baggage)
-            _ensure_sink().emit([event])
+            sink = _ensure_sink()
+            _note_orphan_emit()
+            sink.emit([event])
         except Exception as exc:
             _diag.absorbed("emitting an orphan log", exc, "the event was lost")
     if echo and event is not None:

{log_foundry-0.10.2.dev30 → log_foundry-0.10.2.dev31}/src/log_foundry/decorator.py

@@ -32,6 +32,9 @@ __all__ = ["continue_trace", "trace"]
 _worker: Worker | None = None
 _worker_lock = threading.Lock()
 _atexit_registered = False
+_orphan_close_owed = False
+_orphan_sink_closed = False
+_orphan_retired = False
 
 F = TypeVar("F", bound=Callable[..., Any])
 
@@ -202,23 +205,127 @@ def _get_worker() -> Worker:
     Raises:
       Exception: Whatever constructing the sink or worker raises.
     """
-    global _worker, _atexit_registered
+    global _worker
     if _worker is None:
         with _worker_lock:
             if _worker is None:
-                if not _atexit_registered:
-                    atexit.register(_shutdown_worker)
-                    _atexit_registered = True
+                _register_exit_handler()
                 _worker = Worker(_ensure_sink())
     return _worker
 
 
+def _register_exit_handler() -> None:
+    """Registers the one ``atexit`` handler that covers both delivery paths (SPEC-031 FR-006).
+
+    One registration, not two, and one flag guarding it. :func:`_shutdown_worker` handles the
+    worker path *and* the orphan path, so an orphan log arming this does not cost a later
+    ``@trace`` its exit drain — which reusing a worker-only registration flag would. Two
+    handlers would be worse still: ``atexit`` runs LIFO, so the second would close a sink the
+    first had already closed. What is made once-only is the *close*, not the registration.
+
+    Callers hold ``_worker_lock``.
+
+    Args:
+      None.
+
+    Returns:
+      None.
+
+    Raises:
+      None.
+    """
+    global _atexit_registered
+    if not _atexit_registered:
+        atexit.register(_shutdown_worker)
+        _atexit_registered = True
+
+
+def _note_orphan_emit() -> None:
+    """Records that a level call with no span reached the sink (SPEC-031 FR-006).
+
+    This is what arms the exit-time close, and it is deliberately keyed on an event having
+    *landed* rather than on a sink existing: ``configure()`` runs ``_ensure_sink()``
+    unconditionally, so a bare ``configure(service=…)`` has already built a ``StdoutSink``,
+    and keying on that would close a sink nothing was ever written to.
+
+    The unlocked read is the fast path on a per-call route — the flag is written once and
+    never cleared, so a racing reader either sees it set or takes the lock and finds it set
+    there.
+
+    Args:
+      None.
+
+    Returns:
+      None.
+
+    Raises:
+      None.
+    """
+    global _orphan_close_owed
+    if _orphan_close_owed:
+        return
+    with _worker_lock:
+        if not _orphan_close_owed:
+            _register_exit_handler()
+            _orphan_close_owed = True
+
+
+def _close_orphan_sink() -> None:
+    """Closes a sink only the orphan path ever wrote to, once (SPEC-031 FR-006).
+
+    A process that never opens a span builds no worker, so nothing owned the sink's close and
+    nothing performed it: on a locally-buffering sink every event died in the client's batch,
+    on a synchronous one the flush and the resource were lost, and ``health()`` read all-clear
+    because every field it carries describes a worker that does not exist.
+
+    A live worker owns the close instead, and this returns — that is what makes a mixed
+    process exactly one ``close()`` in either order. It also inherits the worker's reasons for
+    *not* closing: an expired :meth:`Worker.shutdown` leaves the sink open because the drain
+    thread may still be inside ``emit``.
+
+    That check is read **under** ``_worker_lock``, not ahead of it, because :func:`_get_worker`
+    assigns ``_worker`` while holding that same lock. Unlocked, a ``shutdown()`` racing a first
+    ``@trace`` could read ``None``, block behind the worker's construction, and then close the
+    sink underneath the worker that had just captured it — reproduced with an injected
+    preemption point, the way SPEC-028 demonstrates the races that need one.
+
+    The once-only flag is set ahead of the close, as ``Worker.shutdown``'s is: a second
+    ``close()`` on a sink that partially released its resources is worse than an unclosed one.
+
+    Args:
+      None.
+
+    Returns:
+      None.
+
+    Raises:
+      None. This runs from ``atexit``, where an escaping exception makes CPython print a
+        traceback carrying the message arch §6 keeps out of anything the library says about
+        itself. ``Exception``, never ``BaseException`` (SPEC-025 FR-004).
+    """
+    global _orphan_sink_closed
+    with _worker_lock:
+        if _worker is not None or not _orphan_close_owed or _orphan_sink_closed:
+            return
+        _orphan_sink_closed = True
+    try:
+        _ensure_sink().close()
+    except Exception as exc:
+        _diag.absorbed("closing the sink", exc, "it may still hold its resources")
+
+
 def _shutdown_worker(timeout: float | None = DEFAULT_SHUTDOWN_TIMEOUT) -> None:
-    """Drains and closes the process worker if one was created, backing ``shutdown()``.
+    """Drains and closes the process worker, or closes an orphan-only sink, backing ``shutdown()``.
 
     The ``atexit`` registration binds this function, so the exit path gets the bounded form
     and its default (SPEC-027 FR-004) — an unbounded join in an ``atexit`` handler is a
-    process that will not exit. Idempotent.
+    process that will not exit. Idempotent on both paths.
+
+    ``_orphan_retired`` is set unconditionally and read only when there is no worker, which is
+    what makes ``health().retired`` truthful for a process that shut down without ever
+    building one (SPEC-031 FR-006). No worker is created here to answer it: standing up a
+    thread at exit to prove there is nothing to drain is pure cost, the same refusal
+    :func:`_swap_sink` and :func:`_flush_worker` already make.
 
     Args:
       timeout: Seconds to wait for the drain, or ``None`` to wait indefinitely.
@@ -229,8 +336,12 @@ def _shutdown_worker(timeout: float | None = DEFAULT_SHUTDOWN_TIMEOUT) -> None:
     Raises:
       None.
     """
+    global _orphan_retired
+    _orphan_retired = True
     if _worker is not None:
         _worker.shutdown(timeout)
+        return
+    _close_orphan_sink()
 
 
 def _swap_sink(new_sink: Sink, timeout: float | None = DEFAULT_SWAP_TIMEOUT) -> None:
@@ -301,6 +412,24 @@ def _worker_health() -> Health:
     created has not died, which is why SPEC-019 reports the terminal failure as a reason
     rather than an ``alive`` flag.
 
+    ``retired`` is the one field synthesized rather than zeroed (SPEC-031 FR-006). It records
+    an action the caller took, not a state of the worker, so it stays true in a process that
+    called ``shutdown()`` without ever building one — where it was previously vacuous, and the
+    whole snapshot read all-clear over a sink that had just been closed.
+    ``submitted_after_shutdown`` is deliberately **not** synthesized alongside it: SPEC-030
+    defines that count as submissions queued where nothing will drain them, and a later orphan
+    log is refused at the closed sink and announced instead. The two are not the same claim.
+
+    The synthesis also survives a worker built *after* that shutdown, which is why it is an
+    ``or`` rather than a fallback. An orphan-only ``shutdown()`` leaves ``_worker`` unset, so a
+    later ``@trace`` constructs a fresh worker whose own ``retired`` is ``False`` — and reading
+    that alone would say the process was never shut down, contradicting this function's own
+    guarantee one call earlier. The events that worker carries are not lost silently: against a
+    sink that guards its post-close state they raise and land in ``failed_batches`` (measured),
+    and against one that releases nothing on ``close()`` they genuinely still deliver. So the
+    detection is ``failed_batches`` there rather than SPEC-030's ``retired`` +
+    ``submitted_after_shutdown`` pair, which stays the signal for the path it was built for.
+
     Args:
       None.
 
@@ -312,8 +441,11 @@ def _worker_health() -> Health:
     """
     worker = _worker
     if worker is None:
-        return Health(queued=0, dropped=0, failed_batches=0)
-    return worker.health()
+        return Health(queued=0, dropped=0, failed_batches=0, retired=_orphan_retired)
+    health = worker.health()
+    if _orphan_retired and not health.retired:
+        return health._replace(retired=True)
+    return health
 
 
 def _flush(span: Span) -> None:

{log_foundry-0.10.2.dev30 → log_foundry-0.10.2.dev31}/src/log_foundry/worker.py

@@ -90,12 +90,15 @@ class Health(NamedTuple):
         the sink reports nothing (SPEC-026 FR-003). Nested rather than folded into the
         integers above because they count different things: ``dropped`` here is backpressure
         at this queue, ``dropped`` on the sink is an event that never reached the wire.
-      retired: Whether :meth:`Worker.shutdown` has been called. It describes an action the
+      retired: Whether ``shutdown()`` has been called. It describes an action the
         caller took, not a failure the library detected, which is why it is a boolean where
         ``stopped_reason`` is a string — SPEC-019 rejected an ``alive`` flag because it would
         read ``False`` for a process that never logged, and that objection does not apply to a
         field which is simply ``False`` until someone calls ``shutdown()`` (SPEC-030 FR-001).
         On its own it is not a fault: a process that shuts down and stops logging is correct.
+        It is the one field ``decorator._worker_health`` synthesizes rather than zeroing, so
+        that a process which only ever logged outside a span — and therefore has no worker at
+        all — still reports its own shutdown truthfully (SPEC-031 FR-006).
       submitted_after_shutdown: Submissions accepted after ``shutdown()`` and queued where
         nothing will drain them. Non-zero alongside ``retired`` is the signature of the
         serverless mistake — ``shutdown()`` called per invocation on a warm container, so the