log-foundry 0.10.2.dev24__tar.gz → 0.10.2.dev26__tar.gz

{log_foundry-0.10.2.dev24 → log_foundry-0.10.2.dev26}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: log-foundry
-Version: 0.10.2.dev24
+Version: 0.10.2.dev26
 Summary: Generate logs for your console and JSON events for downstream consumption.
 License-Expression: MIT
 License-File: LICENSE
@@ -234,6 +234,34 @@ lf.configure(
 If you never set a `sink`, the first decorated call falls back to `StdoutSink()`, so `@trace`
 works with zero configuration.
 
+**Passing `sink=` after logging has started swaps the live destination.** The background worker
+captures its sink when it is built, so a later `configure(sink=...)` has to do more than update
+what `get_config()` reports — otherwise the config and the behaviour disagree silently, which is
+what it used to do. The swap drains everything submitted so far to the **previous** sink, closes
+it, and points the worker at the new one:
+
+```python
+lf.configure(sink=StdoutSink())
+do_some_work()                       # these events go to stdout
+
+lf.configure(sink=SQSSink(queue_url=QUEUE_URL))
+do_some_more_work()                  # these go to SQS; the earlier ones were drained to stdout
+```
+
+The drain is bounded at 5 s. If it cannot be confirmed in that time the swap still takes effect —
+you asked for that sink — but the previous sink is left **open** rather than closed, because the
+drain thread may still be inside its `emit`, and `health().incomplete_swaps` records it. Passing
+the sink that is already live is a no-op: no drain, no close. The previous sink **is** closed, so
+do not hand it back to a later call.
+
+The 5 s covers the drain, **not** the previous sink's `close()`, which has no timeout of its own —
+a destination that blocks there blocks `configure()`. `KafkaSink.close()` flushes its producer, so
+an unreachable broker is the case to watch. Configure the sink before the first log where you can;
+that path has no worker to retarget and nothing to close.
+
+`configure()` is still a startup call. It is not thread-safe, and a span finishing on another
+thread mid-swap may land on either sink.
+
 ### `@trace`
 
 Decorate any **synchronous** function. Usable bare or with arguments:
@@ -746,7 +774,11 @@ returns a snapshot of the worker's counters:
 
 ```python
 h = log_foundry.health()
-if h.dropped or h.failed_batches or h.stopped_reason or (h.sink and (h.sink.dropped or h.sink.failed)):
+if (
+    h.dropped or h.failed_batches or h.stopped_reason or h.incomplete_swaps
+    or (h.sink and (h.sink.dropped or h.sink.failed))
+    or (h.retired and h.submitted_after_shutdown)
+):
     ...  # logs were silently lost — worth an alert
 ```
 
@@ -759,6 +791,8 @@ They tell you different things, and they want different responses:
 | `stopped_reason` | The background thread **died** on that exception type. Nothing further will be delivered, ever. | Restart the process; investigate the named exception. |
 | `sink.dropped` | The sink discarded events **before** attempting delivery — an oversized record, or one the client refused outright. | Read the stderr line: it names the cause. An oversized record means shrink what you log; a refused local produce/publish (Kafka, Pub/Sub) points at the client — a saturated buffer, a bad topic, a credential. |
 | `sink.failed` | The sink attempted delivery and could not confirm it — abandoned requests, partially-failed batches, responses it could not adjudicate. | Fix the destination. |
+| `retired` + `submitted_after_shutdown` | `shutdown()` was called and the process **kept logging**. Those events are queued where nothing will drain them — total loss, for as long as the process runs. | Use `flush()`, not `shutdown()`, in a process that logs again. This is the serverless mistake below. |
+| `incomplete_swaps` | A late `configure(sink=...)` could not confirm the previous sink was drained. The swap took effect; that sink was left open and some queued events may have gone to the new one. | Investigate the previous sink — it was hung or failing. Configure the sink before the first log where you can. |
 
 `h.sink` is a `SinkLosses(dropped, failed)` or `None` — `None` when no worker exists yet, or when
 the configured sink reports nothing (`losses()` is optional). Note the two `dropped` fields count
@@ -780,8 +814,14 @@ logged, and after a clean `shutdown()`, so a plain truthiness check is safe. Wit
 thread showed up only indirectly, as `dropped` climbing once the queue filled — the wrong signal,
 pointing at the wrong fix.
 
+`retired` is deliberately **not** alerted on by itself. A process that shuts down and then stops
+logging is doing the right thing; it is the *pair* — retired, and still being handed events — that
+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.
+
 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`) not yet in a tagged
+fields over time — a fourth (`stopped_reason`) in `v0.7.0`, and a fifth (`sink`) plus a sixth,
+seventh and eighth (`retired`, `submitted_after_shutdown`, `incomplete_swaps`) not yet in a tagged
 release — so unpacking it whole (`queued, dropped, failed = health()`) raises `ValueError`. Every
 field keeps its position when a new one is appended, so attribute and index access stay stable.
 
@@ -859,6 +899,13 @@ getting them wrong is silent:
   the first invocation on a warm container would log and every later one would silently log
   nothing. That failure reads as "works locally, broken in production".
 
+  It is no longer silent. Logging after `shutdown()` is accepted and undeliverable, and
+  `health()` says so: **`retired` is `True` and `submitted_after_shutdown` is non-zero** — that
+  pair, and only that pair, is this mistake. The first such submission also writes one stderr
+  line naming `flush()` as the remedy, throttled to the first and every thousandth after it.
+  `stopped_reason` stays `None` throughout, because nothing failed; someone used the terminal
+  drain where the repeatable one belonged.
+
 ```python
 import log_foundry as lf
 from log_foundry.sinks.sqs import SQSSink
@@ -876,9 +923,11 @@ def handler(event, context):
         # would log nothing.
         drained = lf.flush()
         h = lf.health()
-        if not drained or h.failed_batches or h.dropped or h.stopped_reason:
+        if not drained or h.failed_batches or h.dropped or h.stopped_reason or h.retired:
             # `drained` covers this invocation's tail; the counters cover anything the worker
             # lost earlier — a batch its own interval trigger already gave up on, for instance.
+            # `h.retired` catches the mistake above: inside a handler it can only mean something
+            # called shutdown(), and from here on this container logs nothing.
             # Emitting this through your platform's own logger keeps it outside the pipeline
             # that just failed.
             print(f"log-foundry: undelivered logs ({drained=}, {h=})")

{log_foundry-0.10.2.dev24 → log_foundry-0.10.2.dev26}/README.md

@@ -198,6 +198,34 @@ lf.configure(
 If you never set a `sink`, the first decorated call falls back to `StdoutSink()`, so `@trace`
 works with zero configuration.
 
+**Passing `sink=` after logging has started swaps the live destination.** The background worker
+captures its sink when it is built, so a later `configure(sink=...)` has to do more than update
+what `get_config()` reports — otherwise the config and the behaviour disagree silently, which is
+what it used to do. The swap drains everything submitted so far to the **previous** sink, closes
+it, and points the worker at the new one:
+
+```python
+lf.configure(sink=StdoutSink())
+do_some_work()                       # these events go to stdout
+
+lf.configure(sink=SQSSink(queue_url=QUEUE_URL))
+do_some_more_work()                  # these go to SQS; the earlier ones were drained to stdout
+```
+
+The drain is bounded at 5 s. If it cannot be confirmed in that time the swap still takes effect —
+you asked for that sink — but the previous sink is left **open** rather than closed, because the
+drain thread may still be inside its `emit`, and `health().incomplete_swaps` records it. Passing
+the sink that is already live is a no-op: no drain, no close. The previous sink **is** closed, so
+do not hand it back to a later call.
+
+The 5 s covers the drain, **not** the previous sink's `close()`, which has no timeout of its own —
+a destination that blocks there blocks `configure()`. `KafkaSink.close()` flushes its producer, so
+an unreachable broker is the case to watch. Configure the sink before the first log where you can;
+that path has no worker to retarget and nothing to close.
+
+`configure()` is still a startup call. It is not thread-safe, and a span finishing on another
+thread mid-swap may land on either sink.
+
 ### `@trace`
 
 Decorate any **synchronous** function. Usable bare or with arguments:
@@ -710,7 +738,11 @@ returns a snapshot of the worker's counters:
 
 ```python
 h = log_foundry.health()
-if h.dropped or h.failed_batches or h.stopped_reason or (h.sink and (h.sink.dropped or h.sink.failed)):
+if (
+    h.dropped or h.failed_batches or h.stopped_reason or h.incomplete_swaps
+    or (h.sink and (h.sink.dropped or h.sink.failed))
+    or (h.retired and h.submitted_after_shutdown)
+):
     ...  # logs were silently lost — worth an alert
 ```
 
@@ -723,6 +755,8 @@ They tell you different things, and they want different responses:
 | `stopped_reason` | The background thread **died** on that exception type. Nothing further will be delivered, ever. | Restart the process; investigate the named exception. |
 | `sink.dropped` | The sink discarded events **before** attempting delivery — an oversized record, or one the client refused outright. | Read the stderr line: it names the cause. An oversized record means shrink what you log; a refused local produce/publish (Kafka, Pub/Sub) points at the client — a saturated buffer, a bad topic, a credential. |
 | `sink.failed` | The sink attempted delivery and could not confirm it — abandoned requests, partially-failed batches, responses it could not adjudicate. | Fix the destination. |
+| `retired` + `submitted_after_shutdown` | `shutdown()` was called and the process **kept logging**. Those events are queued where nothing will drain them — total loss, for as long as the process runs. | Use `flush()`, not `shutdown()`, in a process that logs again. This is the serverless mistake below. |
+| `incomplete_swaps` | A late `configure(sink=...)` could not confirm the previous sink was drained. The swap took effect; that sink was left open and some queued events may have gone to the new one. | Investigate the previous sink — it was hung or failing. Configure the sink before the first log where you can. |
 
 `h.sink` is a `SinkLosses(dropped, failed)` or `None` — `None` when no worker exists yet, or when
 the configured sink reports nothing (`losses()` is optional). Note the two `dropped` fields count
@@ -744,8 +778,14 @@ logged, and after a clean `shutdown()`, so a plain truthiness check is safe. Wit
 thread showed up only indirectly, as `dropped` climbing once the queue filled — the wrong signal,
 pointing at the wrong fix.
 
+`retired` is deliberately **not** alerted on by itself. A process that shuts down and then stops
+logging is doing the right thing; it is the *pair* — retired, and still being handed events — that
+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.
+
 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`) not yet in a tagged
+fields over time — a fourth (`stopped_reason`) in `v0.7.0`, and a fifth (`sink`) plus a sixth,
+seventh and eighth (`retired`, `submitted_after_shutdown`, `incomplete_swaps`) not yet in a tagged
 release — so unpacking it whole (`queued, dropped, failed = health()`) raises `ValueError`. Every
 field keeps its position when a new one is appended, so attribute and index access stay stable.
 
@@ -823,6 +863,13 @@ getting them wrong is silent:
   the first invocation on a warm container would log and every later one would silently log
   nothing. That failure reads as "works locally, broken in production".
 
+  It is no longer silent. Logging after `shutdown()` is accepted and undeliverable, and
+  `health()` says so: **`retired` is `True` and `submitted_after_shutdown` is non-zero** — that
+  pair, and only that pair, is this mistake. The first such submission also writes one stderr
+  line naming `flush()` as the remedy, throttled to the first and every thousandth after it.
+  `stopped_reason` stays `None` throughout, because nothing failed; someone used the terminal
+  drain where the repeatable one belonged.
+
 ```python
 import log_foundry as lf
 from log_foundry.sinks.sqs import SQSSink
@@ -840,9 +887,11 @@ def handler(event, context):
         # would log nothing.
         drained = lf.flush()
         h = lf.health()
-        if not drained or h.failed_batches or h.dropped or h.stopped_reason:
+        if not drained or h.failed_batches or h.dropped or h.stopped_reason or h.retired:
             # `drained` covers this invocation's tail; the counters cover anything the worker
             # lost earlier — a batch its own interval trigger already gave up on, for instance.
+            # `h.retired` catches the mistake above: inside a handler it can only mean something
+            # called shutdown(), and from here on this container logs nothing.
             # Emitting this through your platform's own logger keeps it outside the pipeline
             # that just failed.
             print(f"log-foundry: undelivered logs ({drained=}, {h=})")

{log_foundry-0.10.2.dev24 → log_foundry-0.10.2.dev26}/pyproject.toml

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

{log_foundry-0.10.2.dev24 → log_foundry-0.10.2.dev26}/src/log_foundry/__init__.py

@@ -58,22 +58,35 @@ def health() -> Health:
     code non-blocking, and 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. A non-``None`` ``stopped_reason`` is worse than either: the background thread
-    died on that exception type, so nothing further will be delivered at all (SPEC-019)::
+    died on that exception type, so nothing further will be delivered at all (SPEC-019). A
+    ``retired`` worker still being handed events is the same total loss arrived at from the
+    other direction — someone called :func:`shutdown` in a process that logs again (SPEC-030)::
 
         h = log_foundry.health()
-        if h.dropped or h.failed_batches or h.stopped_reason or (
+        if h.dropped or h.failed_batches or h.stopped_reason or h.incomplete_swaps or (
             h.sink and (h.sink.dropped or h.sink.failed)
-        ):
+        ) or (h.retired and h.submitted_after_shutdown):
             ...  # raise an alert; logs were silently lost
 
+    ``retired`` alone is not a fault — a process that shuts down and then stops logging is
+    doing the right thing, which is why it is paired with the count rather than alerted on.
+
     Args:
       None.
 
     Returns:
-      The snapshot: ``queued``, ``dropped``, ``failed_batches``, ``stopped_reason`` and
-      ``sink``. The last is the configured sink's own
+      The snapshot: ``queued``, ``dropped``, ``failed_batches``, ``stopped_reason``, ``sink``,
+      ``retired``, ``submitted_after_shutdown`` and ``incomplete_swaps``. ``retired`` says
+      :func:`shutdown` was called, and ``submitted_after_shutdown`` counts events accepted
+      afterwards, which are queued where nothing will drain them — non-zero together, that is
+      the ``shutdown()``-per-invocation mistake, and the remedy is :func:`flush`.
+      ``incomplete_swaps`` counts late ``configure(sink=...)`` calls whose drain of the
+      previous sink could not be confirmed, leaving that sink open. ``sink`` is the configured
+      sink's own
       :class:`~log_foundry.sinks.base.SinkLosses` — loss the sink absorbed rather than the
       worker (SPEC-026) — and is ``None`` when no worker exists or the sink reports nothing.
+      Note ``sink`` describes whichever sink is live now, so a swap takes the previous sink's
+      absorbed losses out of the snapshot with it.
       Its ``dropped`` is not the worker's: the worker's is backpressure at the queue, the
       sink's is an event that never reached the wire, and the stderr line names which. Its
       ``failed`` is an upper bound on loss rather than a count of it, since a sink that raises
@@ -98,6 +111,11 @@ def shutdown(timeout: float | None = DEFAULT_SHUTDOWN_TIMEOUT) -> None:
     registered via ``atexit``, so call it explicitly only when you want to be certain the tail
     of the queue reached the sink before a fast process exit (SPEC-004 FR-005).
 
+    Logging afterwards is **accepted and undeliverable**: those events are queued and nothing
+    will drain them. It is not silent any more — :func:`health` then reports ``retired`` with a
+    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.
+
     Args:
       timeout: Seconds bounding the wait for the background thread (SPEC-027 FR-004). ``None``
         waits indefinitely, which is what this did unconditionally before and is still

{log_foundry-0.10.2.dev24 → log_foundry-0.10.2.dev26}/src/log_foundry/config.py

@@ -76,11 +76,31 @@ def configure(
     the zero-dependency dev default (arch §8). Every ceiling is validated before anything is
     assigned, so a rejected call leaves the config exactly as it found it.
 
+    A ``sink=`` passed after logging has already started is the one argument that needs more
+    than an assignment, because the background worker captured its sink when it was built
+    (arch §7). It **swaps the live delivery target**: everything submitted so far is drained to
+    the previous sink, that sink is closed, and subsequent events go to the new one. The drains
+    are bounded, and a swap whose drain could not be confirmed leaves the previous sink open and
+    records ``health().incomplete_swaps`` (SPEC-030 FR-003) — so "repeated calls compose rather
+    than reset" holds for the sink too, at the cost of one bounded wait. Passing the sink that
+    is already live is a no-op: no drain, no close. The previous sink is closed and must not be
+    handed back to a later call.
+
+    The *closing* of the previous sink is not bounded, because ``Sink.close`` takes no timeout —
+    a destination that blocks in ``close()`` blocks this call. It is the same gap
+    ``architecture.md`` §13 already records for ``shutdown()``, and it has the same fix, which
+    is a change to the sink contract rather than to this function.
+
+    This is still a startup call. It is not thread-safe, and a span finishing on another thread
+    during a swap may land on either sink.
+
     Args:
       service: The service name stamped onto every event.
       version: The service version stamped onto every event.
       env: The deployment environment stamped onto every event.
-      sink: The destination every event is delivered to.
+      sink: The destination every event is delivered to. Passed after the first log, it swaps
+        the live target as described above rather than only updating what ``get_config()``
+        reports.
       defaults: Fields merged into every event at the lowest precedence.
       max_value_bytes: Per-value ceiling, in UTF-8 bytes or rendered digits.
       max_stack_bytes: Ceiling for ``error.stack`` alone.
@@ -119,6 +139,37 @@ def configure(
 
     _ensure_sink()
 
+    if sink is not None:
+        _swap_live_sink(sink)
+
+
+def _swap_live_sink(sink: Sink) -> None:
+    """Points an already-running worker at a newly configured sink (SPEC-030 FR-003).
+
+    The import is local for the reason ``_ensure_sink``'s is: ``decorator`` imports this module
+    at module scope, so reaching back the other way at import time would be a cycle. It also
+    keeps the dependency to the one call that needs it — ``configure()`` without a ``sink=``
+    never touches the worker at all.
+
+    The budget is passed explicitly rather than left to the parameter default, so that the
+    bound this call actually applies is resolved when it runs. A default argument is bound at
+    definition time, which would leave the end-to-end bound untestable without reaching past
+    the function under test.
+
+    Args:
+      sink: The sink just written to the config.
+
+    Returns:
+      None.
+
+    Raises:
+      None.
+    """
+    from log_foundry.decorator import _swap_sink
+    from log_foundry.worker import DEFAULT_SWAP_TIMEOUT
+
+    _swap_sink(sink, DEFAULT_SWAP_TIMEOUT)
+
 
 def get_config() -> Config:
     """Returns the current global config singleton.

{log_foundry-0.10.2.dev24 → log_foundry-0.10.2.dev26}/src/log_foundry/decorator.py

@@ -20,11 +20,13 @@ from log_foundry.ids import (
     parse_traceparent,
 )
 from log_foundry.model import Span, backfill_baggage, end_event, start_event
-from log_foundry.worker import DEFAULT_SHUTDOWN_TIMEOUT, Health, Worker
+from log_foundry.worker import DEFAULT_SHUTDOWN_TIMEOUT, DEFAULT_SWAP_TIMEOUT, Health, Worker
 
 if TYPE_CHECKING:
     import contextvars
 
+    from log_foundry.sinks.base import Sink
+
 __all__ = ["continue_trace", "trace"]
 
 _worker: Worker | None = None
@@ -231,6 +233,37 @@ def _shutdown_worker(timeout: float | None = DEFAULT_SHUTDOWN_TIMEOUT) -> None:
         _worker.shutdown(timeout)
 
 
+def _swap_sink(new_sink: Sink, timeout: float | None = DEFAULT_SWAP_TIMEOUT) -> None:
+    """Retargets the process worker at a new sink, backing a late ``configure(sink=...)``.
+
+    Like :func:`_flush_worker` this deliberately does not call :func:`_get_worker`: a process
+    that has not logged has captured no sink, so there is nothing to swap and building a thread
+    to prove it would be pure cost — that is also the case where the old behaviour was already
+    correct (SPEC-030 FR-003).
+
+    Args:
+      new_sink: The sink already written to the config, to be made the live delivery target.
+      timeout: Seconds bounding the drain of the previous sink.
+
+    Returns:
+      None.
+
+    Raises:
+      None. This runs inside ``configure()``, which has never raised for anything but a
+        rejected ceiling, and a sink swap that fails must not become the reason an application
+        cannot start.
+    """
+    worker = _worker
+    if worker is None:
+        return
+    try:
+        worker.swap_sink(new_sink, timeout)
+    except Exception as exc:
+        _diag.absorbed(
+            "swapping the log sink", exc, "events may still be delivered to the previous sink"
+        )
+
+
 def _flush_worker(timeout: float | None = 5.0) -> bool:
     """Drains the process worker without retiring it, backing ``flush()`` (SPEC-013 FR-003).
 

{log_foundry-0.10.2.dev24 → log_foundry-0.10.2.dev26}/src/log_foundry/sinks/_socket.py

@@ -111,6 +111,7 @@ class SocketTransport:
         self._counter_lock = threading.Lock()
         self.stop_signal: threading.Event | None = None
         self._lock = threading.Lock()
+        self._closed = False
 
     def send_all(self, messages: list[bytes]) -> None:
         """Sends each pre-framed message, reconnecting on error (FR-005, FR-006).
@@ -119,6 +120,11 @@ class SocketTransport:
         reconnect rebinds, so releasing between messages would let another thread send on a
         socket this one is about to reset (SPEC-028 FR-002).
 
+        A closed transport refuses rather than reconnecting. ``_socket`` opens a connection
+        whenever it holds none and ``close`` only drops the one it has, so without this a single
+        ``log_foundry.info()`` after ``shutdown()`` would open a TCP connection nothing will ever
+        reap — measured, and the same leak ``RabbitMQSink`` had (SPEC-028).
+
         Args:
           messages: The exact bytes to put on the wire, one call per message.
 
@@ -130,14 +136,21 @@ class SocketTransport:
             this transport propagate a dead destination to the worker instead of reporting
             success (SPEC-026 FR-001). A partial send does not raise, because the worker's retry
             would re-send the messages that already landed, and an empty call is a no-op rather
-            than a total failure.
+            than a total failure. Also when the transport is already closed.
         """
+        if not messages:
+            return
         with self._lock:
+            if self._closed:
+                raise SinkDeliveryError(
+                    f"SocketTransport delivered none of {len(messages)} message(s): "
+                    f"the transport is closed"
+                )
             delivered = 0
             for message in messages:
                 if self._send_one(message):
                     delivered += 1
-        if messages and delivered == 0:
+        if delivered == 0:
             raise SinkDeliveryError(
                 f"SocketTransport delivered none of {len(messages)} message(s)"
             )
@@ -175,6 +188,7 @@ class SocketTransport:
           None.
         """
         with self._lock:
+            self._closed = True
             self._reset()
 
     def _send_one(self, message: bytes) -> bool:

{log_foundry-0.10.2.dev24 → log_foundry-0.10.2.dev26}/src/log_foundry/sinks/clickhouse.py

@@ -41,10 +41,11 @@ class ClickHouseSink:
     sink is write-only, and the worst-case delay (SPEC-027 FR-005) is ``max_retries``
     interruptible waits per chunk, 0.7 s at the defaults.
 
-    The driver requirement satisfied (SPEC-028 FR-002): a ``clickhouse-connect`` client holds
-    per-session state across an insert and the project does not publish it as safe to share
-    between threads, so this sink serializes its use rather than assuming otherwise. A lock is
-    the conservative reading — one client per thread would be the alternative, and that is the
+    The driver requirement satisfied (SPEC-028 FR-002): ``clickhouse-connect`` states that a
+    client is **not** thread-safe when using session ids, and that concurrent queries in one
+    session raise ``ProgrammingError``. This sink calls ``get_client(dsn=...)``, which takes the
+    default auto-generated session, so it is squarely in that case and the lock is required
+    rather than merely prudent. One client per thread would be the alternative, and that is the
     connection-pool design FR-002 puts out of scope.
     """
 
@@ -133,6 +134,10 @@ class ClickHouseSink:
             return
         chunks = inserted = 0
         with self._lock:
+            if self._closed:
+                raise SinkDeliveryError(
+                    f"ClickHouseSink inserted none of {len(batch)} event(s): the sink is closed"
+                )
             for chunk in chunk_list(batch, self._chunk_size):
                 chunks += 1
                 inserted += self._insert([self._row(event) for event in chunk])
@@ -157,9 +162,9 @@ class ClickHouseSink:
         with self._lock:
             if self._closed:
                 return
+            self._closed = True
             if self._owns_client:
                 self.client.close()
-            self._closed = True
 
     def _row(self, event: dict[str, object]) -> list[object]:
         """Builds one row: the extracted columns, then the whole event as JSON.

{log_foundry-0.10.2.dev24 → log_foundry-0.10.2.dev26}/src/log_foundry/sinks/eventhubs.py

@@ -68,6 +68,8 @@ class AzureEventHubsSink:
         self.failed = 0
         self.dropped_oversized = 0
         self._counter_lock = threading.Lock()
+        self._lock = threading.Lock()
+        self._closed = False
 
     def losses(self) -> SinkLosses:
         """Reports oversized drops and events in a batch abandoned past the bound (FR-002).
@@ -106,6 +108,32 @@ class AzureEventHubsSink:
         """
         if not batch:
             return
+        with self._lock:
+            if self._closed:
+                raise SinkDeliveryError(
+                    f"AzureEventHubsSink sent none of {len(batch)} event(s): the sink is closed"
+                )
+            self._send_batch(batch)
+
+    def _send_batch(self, batch: list[dict[str, object]]) -> None:
+        """Packs and sends the batch, with the emit lock already held.
+
+        Split out so the lock's extent is one line in :meth:`emit`. The driver requirement
+        satisfied (SPEC-028 FR-002): Microsoft affirmatively states that the
+        ``EventHubProducerClient`` is not thread-safe and recommends guarding it with a
+        ``threading.Lock``; the ``EventDataBatch`` this builds up across the loop is single-owner
+        state besides — two threads packing into batches from one producer interleave
+        ``create_batch``/``add``/``send`` on it.
+
+        Args:
+          batch: The events to send, known non-empty.
+
+        Returns:
+          None.
+
+        Raises:
+          SinkDeliveryError: When every attempted send failed.
+        """
         event_data_cls = _event_data_cls()
         current = self.producer.create_batch()
         attempted = delivered = 0
@@ -132,6 +160,9 @@ class AzureEventHubsSink:
     def close(self) -> None:
         """Closes the producer (FR-009).
 
+        Idempotent, and takes the emit lock so the producer is never closed out from under an
+        in-flight send (SPEC-028 FR-002).
+
         Args:
           None.
 
@@ -141,7 +172,11 @@ class AzureEventHubsSink:
         Raises:
           Exception: Whatever the producer raises on close.
         """
-        self.producer.close()
+        with self._lock:
+            if self._closed:
+                return
+            self._closed = True
+            self.producer.close()
 
     def _send(self, event_batch: Any) -> int:
         """Sends one ``EventDataBatch``, retrying failures (FR-009, FR-011).

{log_foundry-0.10.2.dev24 → log_foundry-0.10.2.dev26}/src/log_foundry/sinks/file.py

@@ -8,6 +8,8 @@ import threading
 import time
 from typing import TextIO
 
+from log_foundry.sinks.base import SinkDeliveryError
+
 __all__ = ["FileSink", "RotatingFileSink"]
 
 _WHEN_SECONDS = {
@@ -71,7 +73,13 @@ class FileSink:
         Raises:
           OSError: If the write or flush fails (FR-001).
         """
+        if not batch:
+            return
         with self._lock:
+            if self._closed:
+                raise SinkDeliveryError(
+                    f"FileSink wrote none of {len(batch)} event(s): the sink is closed"
+                )
             for event in batch:
                 self._stream.write(json.dumps(event) + "\n")
             self._stream.flush()
@@ -94,9 +102,9 @@ class FileSink:
         with self._lock:
             if self._closed:
                 return
+            self._closed = True
             self._stream.flush()
             self._stream.close()
-            self._closed = True
 
 
 class RotatingFileSink:
@@ -176,7 +184,13 @@ class RotatingFileSink:
         Raises:
           OSError: If a write, flush or rotation fails.
         """
+        if not batch:
+            return
         with self._lock:
+            if self._closed:
+                raise SinkDeliveryError(
+                    f"RotatingFileSink wrote none of {len(batch)} event(s): the sink is closed"
+                )
             for event in batch:
                 line = json.dumps(event) + "\n"
                 data = len(line.encode(self._encoding))
@@ -205,9 +219,9 @@ class RotatingFileSink:
         with self._lock:
             if self._closed:
                 return
+            self._closed = True
             self._stream.flush()
             self._stream.close()
-            self._closed = True
 
     @staticmethod
     def _rollover_seconds(when: str | None, interval: int) -> float | None:

{log_foundry-0.10.2.dev24 → log_foundry-0.10.2.dev26}/src/log_foundry/sinks/firehose.py

@@ -32,6 +32,10 @@ class FirehoseSink:
         the chunk sent, so none could be paired to an outcome. A non-zero count means those
         records were abandoned without the stream ever confirming them — treat it as loss, and
         as a sign the client is not AWS-shaped.
+
+    The driver requirement satisfied (SPEC-028 FR-002): this sink takes **no** transport
+    lock. ``boto3`` clients are documented thread-safe, this one is built once in
+    ``__init__``, and the sink rebinds nothing after construction.
     """
 
     MAX_RECORDS = 500

{log_foundry-0.10.2.dev24 → log_foundry-0.10.2.dev26}/src/log_foundry/sinks/kafka.py

@@ -24,6 +24,10 @@ class KafkaSink:
       failed: Messages whose delivery callback reported an error.
       rejected: Messages ``produce()`` itself refused — a full local queue, a serialization fault
         — which never reached the producer's batch at all.
+
+    The driver requirement satisfied (SPEC-028 FR-002): this sink takes **no** transport
+    lock. ``confluent-kafka`` documents its ``Producer`` as thread-safe, and this sink adds no state
+    of its own to guard — ``produce()`` is a local hand-off into the client's internal queue.
     """
 
     def __init__(

{log_foundry-0.10.2.dev24 → log_foundry-0.10.2.dev26}/src/log_foundry/sinks/kinesis.py

@@ -32,6 +32,10 @@ class KinesisSink:
         describe the chunk sent, so none could be paired to an outcome. A non-zero count means
         those records were abandoned without the stream ever confirming them — treat it as loss,
         and as a sign the client is not AWS-shaped.
+
+    The driver requirement satisfied (SPEC-028 FR-002): this sink takes **no** transport
+    lock. ``boto3`` clients are documented thread-safe, this one is built once in
+    ``__init__``, and the sink rebinds nothing after construction.
     """
 
     MAX_RECORDS = 500