log-foundry 0.0.2.dev1__py3-none-any.whl

log_forge/sinks/file.py

@@ -0,0 +1,177 @@
+"""FileSink + RotatingFileSink — durable local NDJSON on disk (arch §8, SPEC-008).
+
+Not every deployment ships to a cloud queue; local dev, debugging, air-gapped hosts, and simple
+archival just want events on the local disk. These are the zero-dependency file sinks: one appends
+NDJSON to a single file; the other bounds on-disk growth by rotating on a size and/or time trigger
+while retaining a fixed number of numbered backups. Like every sink they receive *already-built*
+event dicts and know nothing about spans or context (that dumbness is what makes sinks swappable).
+
+Synchronous stdlib writes only — no async/mmap/O_DIRECT — and a single-process, single-worker-thread
+writer is assumed (arch §9); cross-process coordination is out of scope (SPEC-008).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from typing import TextIO
+
+__all__ = ["FileSink", "RotatingFileSink"]
+
+# Time-trigger unit codes -> seconds, mirroring stdlib TimedRotatingFileHandler's vocabulary
+# (subset). Matched case-insensitively; the rollover interval is ``interval * _WHEN_SECONDS[when]``.
+_WHEN_SECONDS = {
+    "S": 1,
+    "M": 60,
+    "H": 60 * 60,
+    "D": 60 * 60 * 24,
+}
+
+
+class FileSink:
+    """A :class:`~log_forge.sinks.base.Sink` that appends events as NDJSON to one file.
+
+    The file is opened once in append text mode at construction, so a missing parent directory
+    surfaces immediately (at ``configure`` time) rather than on the first flush. The file is created
+    if absent and appended to — never truncated — if it already exists.
+    """
+
+    def __init__(self, path: str, *, encoding: str = "utf-8") -> None:
+        self._path = path
+        self._encoding = encoding
+        self._stream: TextIO = open(path, "a", encoding=encoding)
+        self._closed = False
+
+    def emit(self, batch: list[dict[str, object]]) -> None:
+        """Write every event as one ``json.dumps`` line terminated by ``\\n``, then flush (FR-001)."""
+        for event in batch:
+            self._stream.write(json.dumps(event) + "\n")
+        self._stream.flush()
+
+    def close(self) -> None:
+        """Flush and close the file handle; a second call is a no-op (FR-001)."""
+        if self._closed:
+            return
+        self._stream.flush()
+        self._stream.close()
+        self._closed = True
+
+
+class RotatingFileSink:
+    """A :class:`~log_forge.sinks.base.Sink` that rotates the active NDJSON file to bound its growth.
+
+    Two independent triggers, either or both enabled:
+
+    * **size** — with ``max_bytes > 0``, rotate *before* the write that would push the active file
+      past ``max_bytes`` (so it never grows unbounded).
+    * **time** — with a ``when`` unit code (``"S"``/``"M"``/``"H"``/``"D"``) and ``interval``, rotate
+      on the first emit after ``interval`` units have elapsed since the last rotation.
+
+    Rotation renames the active file through numbered backups (``path.1`` … ``path.N``), prunes any
+    backup beyond ``backup_count``, and opens a fresh active file. ``backup_count=0`` keeps no
+    backups (the active file is simply truncated/replaced). No event is lost across a rotation: the
+    rotate happens *before* the pending event is written, and the event lands in the fresh file.
+    """
+
+    def __init__(
+        self,
+        path: str,
+        *,
+        max_bytes: int = 0,
+        backup_count: int = 0,
+        when: str | None = None,
+        interval: int = 1,
+    ) -> None:
+        self._path = path
+        self._encoding = "utf-8"
+        self._max_bytes = max_bytes
+        self._backup_count = backup_count
+        self._interval_seconds = self._rollover_seconds(when, interval)
+        self._stream: TextIO = open(path, "a", encoding=self._encoding)
+        # Byte size of the active file, tracked explicitly so ``max_bytes`` is measured in bytes even
+        # through a text-mode stream. Seeded from any pre-existing file we appended to.
+        self._size = os.path.getsize(path) if os.path.exists(path) else 0
+        self._next_rollover = self._schedule_next()
+        self._closed = False
+
+    def emit(self, batch: list[dict[str, object]]) -> None:
+        """Append each event, rotating first whenever a size/time trigger fires (FR-002)."""
+        for event in batch:
+            line = json.dumps(event) + "\n"
+            data = len(line.encode(self._encoding))  # byte cost, for size accounting
+            if self._should_rotate(data):
+                self._rotate()
+            self._stream.write(line)
+            self._size += data
+        self._stream.flush()
+
+    def close(self) -> None:
+        """Flush and close the active handle; a second call is a no-op (FR-002)."""
+        if self._closed:
+            return
+        self._stream.flush()
+        self._stream.close()
+        self._closed = True
+
+    # -- internals ----------------------------------------------------------------------
+
+    @staticmethod
+    def _rollover_seconds(when: str | None, interval: int) -> float | None:
+        """Translate a ``when`` unit code + ``interval`` into a rollover period in seconds.
+
+        Returns ``None`` (no time trigger) when ``when`` is ``None``; raises ``ValueError`` on an
+        unrecognized unit code so a typo fails loudly at construction, not silently at runtime.
+        """
+        if when is None:
+            return None
+        try:
+            unit = _WHEN_SECONDS[when.upper()]
+        except KeyError:
+            raise ValueError(
+                f"invalid 'when' unit {when!r}; expected one of {sorted(_WHEN_SECONDS)}"
+            ) from None
+        return unit * interval
+
+    def _schedule_next(self) -> float | None:
+        """Absolute monotonic-wallclock time of the next time-based rotation (or ``None``)."""
+        if self._interval_seconds is None:
+            return None
+        return time.time() + self._interval_seconds
+
+    def _should_rotate(self, incoming: int) -> bool:
+        """Decide whether to rotate before writing ``incoming`` bytes (size and/or time)."""
+        if (
+            self._max_bytes > 0
+            and self._size > 0
+            and self._size + incoming > self._max_bytes
+        ):
+            return True
+        if self._next_rollover is not None and time.time() >= self._next_rollover:
+            return True
+        return False
+
+    def _rotate(self) -> None:
+        """Close the active file, shift/prune numbered backups, and open a fresh active file."""
+        self._stream.close()
+        if self._backup_count > 0:
+            # Shift path.(N-1) -> path.N downward, dropping anything past backup_count, then move
+            # the active file to path.1. Highest-numbered backup is the oldest.
+            for i in range(self._backup_count - 1, 0, -1):
+                src = f"{self._path}.{i}"
+                dst = f"{self._path}.{i + 1}"
+                if os.path.exists(src):
+                    if os.path.exists(dst):
+                        os.remove(dst)
+                    os.replace(src, dst)
+            first = f"{self._path}.1"
+            if os.path.exists(first):
+                os.remove(first)
+            if os.path.exists(self._path):
+                os.replace(self._path, first)
+        elif os.path.exists(self._path):
+            # No backups retained: drop the active file so reopening starts empty.
+            os.remove(self._path)
+        self._stream = open(self._path, "a", encoding=self._encoding)
+        self._size = 0
+        self._next_rollover = self._schedule_next()

log_forge/sinks/filtering.py

@@ -0,0 +1,71 @@
+"""FilteringSink — drop events by predicate and/or minimum level (arch §8, SPEC-006 FR-003).
+
+A static, emit-time filter in front of an inner sink: forward only the events that satisfy a
+``predicate`` and/or meet a ``min_level``. This is *not* the reserved tail-sampling
+``should_send`` seam (arch §10) — that stays deferred and owns rate policy at span-decision
+time; this only reshapes an already-built batch on its way to a sink.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from log_forge.sinks.base import Sink
+
+__all__ = ["FilteringSink"]
+
+# Standard severity ranks; higher is more severe. Level names are the arch §6 set.
+_LEVELS = {"DEBUG": 10, "INFO": 20, "WARNING": 30, "ERROR": 40, "CRITICAL": 50}
+
+
+class FilteringSink:
+    """A :class:`~log_forge.sinks.base.Sink` that forwards only events passing a filter.
+
+    Wraps ``inner`` and forwards the subset of each batch that satisfies ``predicate`` and/or
+    meets ``min_level`` (both, when both are given). An event whose ``level`` is unknown or
+    missing is forwarded fail-open rather than dropped; when nothing passes, ``inner.emit`` is
+    not called. Level comparison is case-insensitive.
+
+    Raises:
+        ValueError: if ``min_level`` is not one of the five standard names (case-insensitive).
+    """
+
+    def __init__(
+        self,
+        inner: Sink,
+        *,
+        predicate: Callable[[dict[str, object]], bool] | None = None,
+        min_level: str | None = None,
+    ) -> None:
+        self._inner = inner
+        self._predicate = predicate
+        self._min_rank: int | None = None
+        if min_level is not None:
+            rank = _LEVELS.get(min_level.upper())
+            if rank is None:
+                raise ValueError(
+                    f"unknown min_level: {min_level!r} (expected one of {list(_LEVELS)})"
+                )
+            self._min_rank = rank
+
+    def emit(self, batch: list[dict[str, object]]) -> None:
+        """Forward the events that clear both the predicate and min_level, in order (FR-003)."""
+        kept = [event for event in batch if self._passes(event)]
+        if kept:
+            self._inner.emit(kept)
+
+    def _passes(self, event: dict[str, object]) -> bool:
+        """Whether ``event`` clears the predicate and the minimum level (fail-open on level)."""
+        if self._predicate is not None and not self._predicate(event):
+            return False
+        if self._min_rank is not None:
+            level = event.get("level")
+            rank = _LEVELS.get(level.upper()) if isinstance(level, str) else None
+            # A known level below the floor is dropped; an unknown/missing level fails open.
+            if rank is not None and rank < self._min_rank:
+                return False
+        return True
+
+    def close(self) -> None:
+        """Close the inner sink (FR-003)."""
+        self._inner.close()

log_forge/sinks/firehose.py

@@ -0,0 +1,91 @@
+"""FirehoseSink — put event records to a Kinesis Data Firehose delivery stream (arch §8, SPEC-010).
+
+The same durable-buffer shape as :class:`~log_forge.sinks.kinesis.KinesisSink`, using Firehose's
+``put_record_batch`` (≤ 500 records **and** ≤ 4 MB per request). ``boto3`` is the optional ``aws``
+extra, imported lazily. Partial failures (the response ``RequestResponses``/``FailedPutCount``) are
+retried within a bounded count.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any
+
+from log_forge.sinks._chunk import chunk_items
+
+__all__ = ["FirehoseSink"]
+
+
+class FirehoseSink:
+    """A :class:`~log_forge.sinks.base.Sink` that writes events to a Firehose delivery stream."""
+
+    MAX_RECORDS = 500  # put_record_batch hard limit: records per request
+    MAX_REQUEST_BYTES = 4 * 1024 * 1024  # 4 MB per put_record_batch request
+    MAX_RECORD_BYTES = 1024 * 1024  # 1 MB per record
+
+    def __init__(self, delivery_stream: str, *, client: Any = None, max_retries: int = 3) -> None:
+        if client is None:
+            import boto3  # type: ignore[import-not-found]  # optional 'aws' extra
+
+            client = boto3.client("firehose")
+        self.delivery_stream = delivery_stream
+        self.client = client
+        self.max_retries = max_retries
+        self.failed = 0
+        self.dropped_oversized = 0
+
+    def emit(self, batch: list[dict[str, object]]) -> None:
+        """Re-chunk to put_record_batch limits and send each chunk, retrying failures (FR-004)."""
+        records = self._records(batch)
+        for chunk in chunk_items(
+            records,
+            max_count=self.MAX_RECORDS,
+            max_bytes=self.MAX_REQUEST_BYTES,
+            size_of=lambda record: len(record["Data"]),
+        ):
+            self._send(chunk)
+
+    def close(self) -> None:
+        """No-op: the sink buffers nothing internally (FR-001)."""
+
+    # -- internals ----------------------------------------------------------------------
+
+    def _records(self, batch: list[dict[str, object]]) -> list[dict[str, Any]]:
+        """Build put_record_batch entries, dropping any single record too large (FR-011)."""
+        records: list[dict[str, Any]] = []
+        for event in batch:
+            data = json.dumps(event).encode("utf-8")
+            if len(data) > self.MAX_RECORD_BYTES:
+                self.dropped_oversized += 1
+                sys.stderr.write(
+                    f"log-forge: FirehoseSink dropped an event of {len(data)} bytes exceeding "
+                    f"the {self.MAX_RECORD_BYTES}-byte per-record limit\n"
+                )
+                continue
+            records.append({"Data": data})
+        return records
+
+    def _send(self, records: list[dict[str, Any]]) -> None:
+        """Send one chunk, retrying only the entries the response flags as failed (FR-004)."""
+        for attempt in range(self.max_retries + 1):
+            response = self.client.put_record_batch(
+                DeliveryStreamName=self.delivery_stream, Records=records
+            )
+            if not response.get("FailedPutCount"):
+                return
+            results = response.get("RequestResponses", [])
+            records = [
+                record
+                for record, result in zip(records, results)
+                if result.get("ErrorCode")
+            ]
+            if not records:
+                return
+            if attempt >= self.max_retries:
+                self.failed += len(records)
+                sys.stderr.write(
+                    f"log-forge: {len(records)} Firehose record(s) still failing after "
+                    f"{self.max_retries + 1} attempts; abandoned\n"
+                )
+                return

log_forge/sinks/honeycomb.py

@@ -0,0 +1,38 @@
+"""HoneycombSink — ship to Honeycomb's batch events API (arch §8, SPEC-009).
+
+An :class:`~log_forge.sinks.http.HTTPSink` specialization: POSTs to ``/1/batch/<dataset>`` with an
+``X-Honeycomb-Team`` header, using Honeycomb's ``[{"data": <event>}, ...]`` batch shape.
+"""
+
+from __future__ import annotations
+
+import json
+
+from log_forge.sinks.http import HTTPSink, merge_headers
+
+__all__ = ["HoneycombSink"]
+
+
+class HoneycombSink(HTTPSink):
+    """POST events to Honeycomb's batch API for a dataset (FR-010)."""
+
+    def __init__(
+        self,
+        api_key: str,
+        dataset: str,
+        *,
+        url: str = "https://api.honeycomb.io",
+        **http_kwargs: object,
+    ) -> None:
+        headers = merge_headers({"X-Honeycomb-Team": api_key}, http_kwargs)
+        super().__init__(
+            f"{url.rstrip('/')}/1/batch/{dataset}",
+            headers=headers, body_format="json_array", **http_kwargs,  # type: ignore[arg-type]
+        )
+
+    def emit(self, batch: list[dict[str, object]]) -> None:
+        """POST the batch as Honeycomb's ``[{"data": event}, ...]`` shape (FR-010)."""
+        if not batch:
+            return
+        body = json.dumps([{"data": event} for event in batch]).encode("utf-8")
+        self._send(body, content_type="application/json")

log_forge/sinks/http.py

@@ -0,0 +1,202 @@
+"""HTTPSink — POST batches over the stdlib ``urllib`` (arch §8, §9.1, SPEC-009).
+
+The dependency-free base every other HTTP platform sink here builds on: it serializes a batch as
+NDJSON or a JSON array, applies headers/auth/optional gzip, POSTs it, and retries ``429``/``5xx``
+with bounded exponential backoff (honoring ``Retry-After``) before counting and logging an abandoned
+request. Like every sink it receives *already-built* event dicts and knows nothing about spans.
+
+These are **terminal, direct-ship** sinks: per arch §9.1 they couple application delivery to the
+destination's availability, so they are best-effort — for durability put a queue (SQS/SPEC-010) in
+front. A test can inject a fake ``opener`` (a ``urlopen``-shaped callable) to assert on the request
+without any network access.
+"""
+
+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 Any, Callable
+
+__all__ = ["HTTPSink", "merge_headers"]
+
+_BACKOFF_BASE = 0.1  # seconds; delay for retry attempt n is _BACKOFF_BASE * 2**n
+
+
+def merge_headers(base: dict[str, str], http_kwargs: dict[str, object]) -> dict[str, str]:
+    """Merge a platform sink's own headers with any caller-supplied ``headers`` (caller wins).
+
+    Pops ``headers`` out of ``http_kwargs`` (mutating it) so the remaining kwargs can be forwarded
+    to :class:`HTTPSink` without a duplicate ``headers`` argument. Shared by the SaaS sinks that set
+    a fixed auth header (Datadog/Splunk/New Relic/Honeycomb).
+    """
+    caller = http_kwargs.pop("headers", None)
+    if isinstance(caller, dict):
+        base.update(caller)
+    return base
+
+
+class HTTPSink:
+    """A :class:`~log_forge.sinks.base.Sink` that POSTs each batch to an HTTP endpoint.
+
+    Attributes:
+        failed: Requests abandoned past the retry bound.
+        dropped_oversized: Events dropped for exceeding a destination's hard size limit (used by
+            subclasses that enforce one; the generic core imposes no universal limit).
+    """
+
+    def __init__(
+        self,
+        url: str,
+        *,
+        method: str = "POST",
+        headers: dict[str, str] | None = None,
+        auth: str | tuple[str, str] | None = None,
+        body_format: str = "ndjson",
+        timeout: float = 5.0,
+        gzip: bool = False,
+        max_retries: int = 3,
+        opener: Callable[..., Any] | None = None,
+    ) -> None:
+        self.url = url
+        self.method = method
+        self._headers = dict(headers) if headers else {}
+        self._auth = auth
+        self.body_format = body_format
+        self.timeout = timeout
+        self.gzip = gzip
+        self.max_retries = max_retries
+        self._opener = opener if opener is not None else urllib.request.urlopen
+        self.failed = 0
+        self.dropped_oversized = 0
+
+    def emit(self, batch: list[dict[str, object]]) -> None:
+        """Serialize ``batch`` per ``body_format`` and POST it (FR-001)."""
+        if not batch:
+            return
+        body, content_type = self._encode(batch)
+        self._send(body, content_type=content_type)
+
+    def close(self) -> None:
+        """No-op — ``urllib`` opens a fresh connection per request; idempotent (FR-012)."""
+
+    # -- body building ------------------------------------------------------------------
+
+    def _encode(self, batch: list[dict[str, object]]) -> tuple[bytes, str]:
+        """Return ``(body_bytes, default_content_type)`` for the configured ``body_format``."""
+        if self.body_format == "json_array":
+            return json.dumps(batch).encode("utf-8"), "application/json"
+        text = "".join(json.dumps(event) + "\n" for event in batch)
+        return text.encode("utf-8"), "application/x-ndjson"
+
+    # -- transport ----------------------------------------------------------------------
+
+    def _send(
+        self,
+        body: bytes,
+        *,
+        content_type: str,
+        extra_headers: dict[str, str] | None = None,
+    ) -> bytes | None:
+        """POST ``body`` with bounded retry; return the response bytes, or ``None`` if abandoned.
+
+        Subclasses that must inspect the response (e.g. Elasticsearch ``_bulk`` ``items``) use the
+        returned bytes; a ``None`` return means the request was retried to exhaustion and counted.
+        """
+        headers, data = self._prepare(body, content_type, extra_headers)
+        for attempt in range(self.max_retries + 1):
+            request = urllib.request.Request(
+                self.url, data=data, method=self.method, headers=headers
+            )
+            try:
+                status, payload, retry_after = self._attempt(request)
+            except (urllib.error.URLError, OSError) as err:
+                if attempt < self.max_retries:
+                    self._sleep_backoff(attempt, None)
+                    continue
+                self._abandon(f"connection error: {err!r}")
+                return None
+            if 200 <= status < 300:
+                return payload
+            if (status == 429 or 500 <= status < 600) and attempt < self.max_retries:
+                self._sleep_backoff(attempt, retry_after)
+                continue
+            self._abandon(f"HTTP {status}")
+            return None
+        return None
+
+    def _prepare(
+        self,
+        body: bytes,
+        content_type: str,
+        extra_headers: dict[str, str] | None,
+    ) -> tuple[dict[str, str], bytes]:
+        """Build the final header map + (optionally gzipped) body. Caller headers win (FR-002)."""
+        headers: dict[str, str] = {"Content-Type": content_type}
+        if extra_headers:
+            headers.update(extra_headers)
+        headers.update(self._headers)  # caller-provided headers override defaults (FR-002)
+        data = body
+        if self.gzip:
+            data = _gzip.compress(body)
+            headers["Content-Encoding"] = "gzip"
+        self._apply_auth(headers)
+        return headers, data
+
+    def _apply_auth(self, headers: dict[str, str]) -> None:
+        """Apply bearer-token (str) or basic-auth (user, pass) credentials, if not already set."""
+        if self._auth is None or "Authorization" in headers:
+            return
+        if isinstance(self._auth, str):
+            headers["Authorization"] = f"Bearer {self._auth}"
+        else:
+            user, password = self._auth
+            token = b64encode(f"{user}:{password}".encode()).decode("ascii")
+            headers["Authorization"] = f"Basic {token}"
+
+    def _attempt(self, request: urllib.request.Request) -> tuple[int, bytes, float | None]:
+        """Perform one request. Returns ``(status, payload, retry_after)``.
+
+        A ``4xx``/``5xx`` arrives from ``urlopen`` as an ``HTTPError``, which *is* a readable
+        response object, so it is unified here rather than raised. Connection-level failures
+        (``URLError``/``OSError``) propagate for the retry loop to handle.
+        """
+        try:
+            response = self._opener(request, timeout=self.timeout)
+        except urllib.error.HTTPError as err:
+            response = err
+        status = getattr(response, "status", None)
+        if status is None:
+            status = response.getcode()
+        payload = response.read()
+        return int(status), payload, _parse_retry_after(getattr(response, "headers", None))
+
+    def _sleep_backoff(self, attempt: int, retry_after: float | None) -> None:
+        """Sleep before the next attempt: ``Retry-After`` if the server gave one, else backoff."""
+        delay = retry_after if retry_after is not None else _BACKOFF_BASE * (2**attempt)
+        time.sleep(delay)
+
+    def _abandon(self, reason: str) -> None:
+        """Count and log a request abandoned past the retry bound (FR-012)."""
+        self.failed += 1
+        sys.stderr.write(
+            f"log-forge: {type(self).__name__} abandoned a request after "
+            f"{self.max_retries + 1} attempt(s) ({reason})\n"
+        )
+
+
+def _parse_retry_after(headers: Any) -> float | None:
+    """Parse a ``Retry-After`` delay in seconds; ``None`` if absent or an HTTP-date we don't parse."""
+    if headers is None:
+        return None
+    value = headers.get("Retry-After")
+    if value is None:
+        return None
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None  # HTTP-date form: fall back to exponential backoff

log_forge/sinks/kafka.py

@@ -0,0 +1,71 @@
+"""KafkaSink — produce events to a Kafka topic (arch §8, §9.1, SPEC-010).
+
+A durable-buffer sink built on ``confluent-kafka`` (the optional ``kafka`` extra, imported lazily).
+``produce()`` enqueues locally into the producer's internal batch and returns without blocking; the
+delivery result arrives asynchronously on a callback serviced by ``poll()``/``flush()``. ``close()``
+flushes so buffered messages are sent before exit. Delivery errors are counted and logged, never
+raised out of ``emit``.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any
+
+__all__ = ["KafkaSink"]
+
+
+class KafkaSink:
+    """A :class:`~log_forge.sinks.base.Sink` that produces events to a Kafka topic.
+
+    Attributes:
+        failed: Messages whose delivery callback reported an error.
+    """
+
+    def __init__(
+        self,
+        topic: str,
+        *,
+        producer: Any = None,
+        bootstrap_servers: str | None = None,
+        key_field: str = "trace_id",
+    ) -> None:
+        if producer is None:
+            if bootstrap_servers is None:
+                raise ValueError(
+                    "KafkaSink requires bootstrap_servers when no producer is injected"
+                )
+            from confluent_kafka import Producer  # type: ignore[import-not-found]  # 'kafka' extra
+
+            producer = Producer({"bootstrap.servers": bootstrap_servers})
+        self.topic = topic
+        self.producer = producer
+        self.key_field = key_field
+        self.failed = 0
+
+    def emit(self, batch: list[dict[str, object]]) -> None:
+        """Produce one message per event; serve delivery callbacks without blocking (FR-002)."""
+        for event in batch:
+            body = json.dumps(event).encode("utf-8")
+            key = self._key(event)
+            self.producer.produce(self.topic, value=body, key=key, callback=self._on_delivery)
+            self.producer.poll(0)  # serve queued delivery callbacks, non-blocking
+
+    def close(self) -> None:
+        """Flush the producer so buffered messages are delivered before exit (FR-002)."""
+        self.producer.flush()
+
+    # -- internals ----------------------------------------------------------------------
+
+    def _key(self, event: dict[str, object]) -> bytes | None:
+        if not self.key_field:
+            return None
+        value = event.get(self.key_field)
+        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)."""
+        if err is not None:
+            self.failed += 1
+            sys.stderr.write(f"log-forge: KafkaSink delivery failed: {err!r}\n")