log-foundry 0.10.2.dev20__tar.gz → 0.10.2.dev22__tar.gz

{log_foundry-0.10.2.dev20 → log_foundry-0.10.2.dev22}/PKG-INFO

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

{log_foundry-0.10.2.dev20 → log_foundry-0.10.2.dev22}/pyproject.toml

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

log_foundry-0.10.2.dev22/src/log_foundry/__init__.py

@@ -0,0 +1,143 @@
+"""log_foundry — consistent, structured logs per decorated function call."""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _dist_version
+
+from log_foundry.api import critical, debug, error, info, set_baggage, warning
+from log_foundry.config import configure, get_config
+from log_foundry.context import (
+    current_baggage_header,
+    current_trace_context,
+    current_traceparent,
+    reset_context,
+)
+from log_foundry.decorator import continue_trace, trace
+from log_foundry.sinks.base import SinkDeliveryError, SinkLosses
+from log_foundry.worker import DEFAULT_SHUTDOWN_TIMEOUT, Health
+
+try:
+    __version__ = _dist_version("log-foundry")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
+
+
+def flush(timeout: float | None = 5.0) -> bool:
+    """Drains buffered events through the sink without closing it.
+
+    This is the drain for a process that is frozen rather than exited — an AWS Lambda handler
+    must drain before it returns, but will be invoked again on the same warm container. Call it
+    in a ``finally``: the invocation worth logging is the one that failed. Unlike
+    :func:`shutdown` the background worker stays alive and the sink stays open, so logging
+    continues normally afterwards.
+
+    Args:
+      timeout: Seconds to wait for the drain. ``None`` waits indefinitely, which is unsafe in
+        any environment with an execution deadline — it converts "some logs were lost" into
+        "the invocation timed out".
+
+    Returns:
+      True when the events submitted before this call reached the sink. False if the drain did
+      not complete within the timeout, if the worker has already been shut down or has died, or
+      if a batch was abandoned while this call was outstanding (SPEC-021 FR-001) — so True means
+      the events were delivered, not merely that a drain took place. Events submitted
+      concurrently by another thread may or may not be included, since the caller cannot have
+      meant those, and a batch lost before the call belongs to :func:`health`.
+
+    Raises:
+      None.
+    """
+    from log_foundry.decorator import _flush_worker
+
+    return _flush_worker(timeout)
+
+
+def health() -> Health:
+    """Snapshots the background worker's delivery counters (SPEC-017 FR-005).
+
+    A non-zero ``dropped`` means the queue filled and submissions were discarded to keep your
+    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)::
+
+        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)
+        ):
+            ...  # raise an alert; logs were silently lost
+
+    Args:
+      None.
+
+    Returns:
+      The snapshot: ``queued``, ``dropped``, ``failed_batches``, ``stopped_reason`` and
+      ``sink``. The last 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.
+      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
+      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`.
+
+    Raises:
+      None.
+    """
+    from log_foundry.decorator import _worker_health
+
+    return _worker_health()
+
+
+def shutdown(timeout: float | None = DEFAULT_SHUTDOWN_TIMEOUT) -> None:
+    """Flushes buffered events and closes the sink, blocking until drained.
+
+    This is terminal — the worker does not come back — and idempotent. Do not call it
+    per-invocation in a serverless handler: the first invocation on a warm container would log
+    and every later one would silently log nothing; use :func:`flush` there. It is also
+    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).
+
+    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
+        available on request, but is unsafe anywhere with an execution deadline — ``atexit`` is
+        one such place, where a sink blocked in a network call would hold the process open. An
+        expired shutdown reports a ``stopped_reason`` of ``"ShutdownTimeout"`` and leaves the
+        sink open, since the drain thread may still be inside ``emit``.
+
+    Returns:
+      None.
+
+    Raises:
+      None.
+    """
+    from log_foundry.decorator import _shutdown_worker
+
+    _shutdown_worker(timeout)
+
+
+__all__ = [
+    "DEFAULT_SHUTDOWN_TIMEOUT",
+    "Health",
+    "SinkDeliveryError",
+    "SinkLosses",
+    "__version__",
+    "configure",
+    "continue_trace",
+    "critical",
+    "current_baggage_header",
+    "current_trace_context",
+    "current_traceparent",
+    "debug",
+    "error",
+    "flush",
+    "get_config",
+    "health",
+    "info",
+    "reset_context",
+    "set_baggage",
+    "shutdown",
+    "trace",
+    "warning",
+]

log_foundry-0.10.2.dev22/src/log_foundry/_diag.py

@@ -0,0 +1,233 @@
+"""The library's own diagnostic channel — one line on stderr, for what it lost or absorbed.
+
+Three rules, all load-bearing (SPEC-029 FR-004):
+
+* The exception's type, never its message. A message can carry a value from the event that
+  provoked it, and arch §6 keeps user data out of anything the library emits about itself.
+  ``PostgresSink`` is the sharpest case: a psycopg error repr reprints the failing statement
+  and its bound parameters, so a naive diagnostic would reprint the event, PII included.
+* No stream fault escapes. These writers are called from the guards that exist to stop an
+  exception reaching the caller. A ``BaseException`` still passes through, as everywhere else
+  in this library: a ``KeyboardInterrupt`` mid-write is the operator's intent.
+* Record first, announce second. A counter moves before its line is attempted, at every call
+  site, because the write is best-effort and the counter ``health()`` reports is not.
+
+Stderr stays the channel: routing through the ``logging`` module would make the library's own
+failure reports depend on machinery that may be the thing failing. This module must import
+nothing from its own package — it is reached at module scope while the package is still
+partially initialised, and resolves only because it is a leaf.
+"""
+
+from __future__ import annotations
+
+import sys
+
+__all__ = ["absorbed", "errno_of", "lost", "rejected"]
+
+_MAX_DETAIL = 200
+
+_MAX_REJECTED_ECHO = 64
+
+_ESCAPES = {"\t": "\\t", "\n": "\\n", "\r": "\\r"}
+
+
+def absorbed(where: str, exc: BaseException, detail: str = "") -> None:
+    """Reports a failure the library swallowed rather than propagated.
+
+    Only the exception's type is written, never its message: a message can carry a value
+    from the event that provoked it, and arch §6 keeps user data out of anything the library
+    emits about itself. A stream fault is swallowed because these writers are called from the
+    ``except`` and ``finally`` blocks that exist to stop an exception reaching the caller,
+    though a ``BaseException`` from the write still propagates.
+
+    Args:
+      where: What was being attempted, as a participle phrase that reads after "while", such
+        as ``"closing a span"``. A literal, never a runtime value.
+      exc: The absorbed exception. Only ``type(exc).__name__`` is written.
+      detail: Optional consequence for the reader, appended after a semicolon — most usefully
+        what was lost, since an absorbed failure is invisible apart from this line. Escaped
+        and truncated to ``_MAX_DETAIL``; must not be derived from the exception's text.
+
+    Returns:
+      None.
+
+    Raises:
+      None on a stream fault. The channel of last resort has no fallback of its own, and
+        raising from the guard that protects the caller's exception would be worse (arch §4).
+    """
+    try:
+        sys.stderr.write(
+            f"log-foundry: absorbed a failure while {_escape(where)} "
+            f"({_escape(type(exc).__name__)}){_suffix(detail)}\n"
+        )
+    except Exception:
+        pass
+
+
+def lost(what: str, count: int, detail: str = "") -> None:
+    """Reports a counted loss — events, messages, batches or rows that will not be delivered.
+
+    Callers record the counter before calling this, because the write is best-effort by
+    construction and the counter ``health()`` reports must not be able to ride on it.
+
+    Args:
+      what: Singular noun for the unit lost, such as ``"event"`` or ``"row"``. Rendered with
+        the corpus-wide ``(s)`` suffix, so it must be a literal, never a runtime value.
+      count: How many this line reports as lost, normally the increment the caller's counter
+        has just taken. A throttled site instead passes its running total, because a line
+        written on every thousandth drop saying "lost 1" would read as one loss rather than a
+        thousand, and such a site says so in ``detail``.
+      detail: Optional circumstances — the sink's class name, the attempt count, an
+        ``errno``, an exception type. Escaped and truncated to ``_MAX_DETAIL``.
+
+    Returns:
+      None.
+
+    Raises:
+      None on a stream fault; a ``BaseException`` from the write still propagates.
+    """
+    try:
+        sys.stderr.write(f"log-foundry: lost {count} {_escape(what)}(s){_suffix(detail)}\n")
+    except Exception:
+        pass
+
+
+def rejected(reason: str, value: object) -> None:
+    """Reports an inbound trace context the library refused to adopt (SPEC-014).
+
+    The offending value is echoed as a bounded ``repr`` — the one place in the library where a
+    ``repr`` is correct, because the input is an inbound header rather than an exception and
+    its exact shape is what makes a rejection diagnosable. The ``repr`` is escaped afterwards
+    even though ``repr`` of a ``str`` is already printable, because ``repr`` runs
+    ``__repr__``, which is user code free to return a raw newline; escaping the result is the
+    difference between "the built-ins happen to escape" and "this cannot forge a line".
+
+    Args:
+      reason: Why it was refused, such as ``"unparseable traceparent"``. A literal, never a
+        runtime value: unlike the echo, it is not bounded.
+      value: The refused value, echoed as a ``repr`` bounded to ``_MAX_REJECTED_ECHO``,
+        because unbounded it would be a log-injection surface.
+
+    Returns:
+      None.
+
+    Raises:
+      None on a stream fault; a ``BaseException`` from the write still propagates.
+    """
+    try:
+        shown = _escape(repr(value))
+        if len(shown) > _MAX_REJECTED_ECHO:
+            shown = shown[:_MAX_REJECTED_ECHO] + "…"
+        sys.stderr.write(
+            f"log-foundry: ignoring inbound trace context ({_escape(reason)}): {shown}\n"
+        )
+    except Exception:
+        pass
+
+
+def errno_of(exc: BaseException) -> str:
+    """Returns ``"errno=N"`` for an exception carrying one, else an empty string.
+
+    This is the library-controlled detail that makes an ``OSError`` line actionable:
+    "connection refused" and "host unknown" share a type name and are told apart only by the
+    code, and an integer from the OS is not caller data. ``urllib``'s ``URLError`` carries the
+    underlying socket error on ``.reason`` rather than setting its own ``errno``, so that is
+    consulted too.
+
+    The value is rendered through ``int()`` rather than interpolated as found, because
+    ``isinstance(x, int)`` admits any subclass and a driver's error code is routinely one — an
+    ``IntEnum`` or a bespoke class whose ``__str__`` returns whatever its author chose, which
+    an f-string would write verbatim. That is the leak this helper exists to be the
+    alternative to.
+
+    Args:
+      exc: The exception to inspect.
+
+    Returns:
+      The rendered ``errno=N``, or an empty string when there is no integer code.
+
+    Raises:
+      None. Attribute access on an arbitrary exception can run a property that raises, and a
+        helper for a diagnostic must not become one.
+    """
+    try:
+        code = getattr(exc, "errno", None)
+        if code is None:
+            code = getattr(getattr(exc, "reason", None), "errno", None)
+        return f"errno={int(code)}" if isinstance(code, int) else ""
+    except Exception:
+        return ""
+
+
+def _suffix(detail: str) -> str:
+    """Renders a detail as a bounded, escaped ``"; ..."`` suffix.
+
+    Escaping precedes truncation so the bound applies to what is written, and so truncation
+    can only remove characters from an already-safe string rather than split an escape into
+    something that is not one.
+
+    Args:
+      detail: The caller-supplied detail, possibly empty.
+
+    Returns:
+      The suffix, or an empty string when there is no detail or it cannot be rendered.
+
+    Raises:
+      None. This runs inside the caller's f-string, so a detail that cannot be rendered would
+        otherwise take the whole line with it, including the count an operator cannot
+        reconstruct.
+    """
+    if not detail:
+        return ""
+    try:
+        shown = _escape(detail)
+        if len(shown) > _MAX_DETAIL:
+            shown = shown[:_MAX_DETAIL] + "…"
+        return f"; {shown}"
+    except Exception:
+        return ""
+
+
+def _escape(text: str) -> str:
+    """Renders every non-printable character visibly, so nothing in the text can forge a line.
+
+    ``str.isprintable()`` is the test rather than a table over ``range(0x20)``: it is
+    ``False`` for the C0 block and for DEL, the C1 block, U+0085, U+2028, U+2029, and the bidi
+    format characters. Python's own ``splitlines()`` breaks on three of those a C0 table
+    misses, so a reader doing the obvious thing would see a forged ``log-foundry:`` line that
+    a newline count says is not there. The whole-string fast path keeps the common case to a
+    single C-level call, and space is printable, so ordinary text is untouched.
+
+    Args:
+      text: The string to render safely.
+
+    Returns:
+      The text with every non-printable character escaped.
+
+    Raises:
+      None.
+    """
+    if text.isprintable():
+        return text
+    return "".join(char if char.isprintable() else _escaped(char) for char in text)
+
+
+def _escaped(char: str) -> str:
+    """Escapes one non-printable character, following Python's own ``repr`` conventions.
+
+    Args:
+      char: The single character to escape.
+
+    Returns:
+      The escape sequence for that character.
+
+    Raises:
+      None.
+    """
+    escape = _ESCAPES.get(char)
+    if escape is not None:
+        return escape
+    code = ord(char)
+    if code <= 0xFF:
+        return f"\\x{code:02x}"
+    return f"\\u{code:04x}" if code <= 0xFFFF else f"\\U{code:08x}"

log_foundry-0.10.2.dev22/src/log_foundry/api.py

@@ -0,0 +1,161 @@
+"""User-facing log emitters + baggage re-export (SPEC-002, arch §6)."""
+
+from __future__ import annotations
+
+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.ids import new_span_id, new_trace_id
+from log_foundry.model import Span, build_event
+
+__all__ = [
+    "critical",
+    "debug",
+    "error",
+    "info",
+    "set_baggage",
+    "warning",
+]
+
+_console = ConsoleWriter()
+
+
+def _log(level: str, message: str, echo: bool, fields: dict[str, object]) -> None:
+    """Builds one event at the given level and routes it, honoring ``echo``.
+
+    Inside a span the event is appended to that span's queue and flushed together at span
+    end. With no active span it becomes a standalone one-event span — fresh ``trace_id``,
+    ``parent_span_id`` of ``None`` — flushed directly so nothing is dropped (FR-004), with
+    the sink resolved through ``_ensure_sink`` so a zero-config orphan log falls back to
+    ``StdoutSink`` rather than crashing.
+
+    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
+    build raises here too. The in-span branch is deliberately left untouched, since it only
+    appends to a list. The echo runs after the emit, so a closed or redirected stream never
+    costs the event itself.
+
+    Args:
+      level: The severity label to stamp on the event.
+      message: The caller-supplied message text.
+      echo: Whether to also write a human-readable console line.
+      fields: Per-call fields merged into the event.
+
+    Returns:
+      None.
+
+    Raises:
+      None. A logging call must never hand the application an exception from a destination
+        it never chose to talk to; absorbed faults are reported through ``_diag``.
+    """
+    baggage = context.get_baggage()
+    span = context.current_span()
+    event: dict[str, object] | None = None
+    if span is not None:
+        event = build_event(span, level, message, fields=fields, baggage=baggage)
+        span.events.append(event)
+    else:
+        try:
+            orphan = Span(
+                trace_id=new_trace_id(),
+                span_id=new_span_id(),
+                parent_span_id=None,
+                name=message,
+                start_ts=0.0,
+            )
+            event = build_event(orphan, level, message, fields=fields, baggage=baggage)
+            _ensure_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:
+        try:
+            _console.write(event)
+        except Exception as exc:
+            _diag.absorbed("echoing to the console", exc)
+
+
+def debug(message: str, *, echo: bool = False, **fields: object) -> None:
+    """Emits a ``DEBUG`` event on the current span, or a standalone orphan span.
+
+    Args:
+      message: The message text.
+      echo: Whether to also write a human-readable console line.
+      **fields: Per-call structured fields.
+
+    Returns:
+      None.
+
+    Raises:
+      None.
+    """
+    _log("DEBUG", message, echo, fields)
+
+
+def info(message: str, *, echo: bool = False, **fields: object) -> None:
+    """Emits an ``INFO`` event on the current span, or a standalone orphan span.
+
+    Args:
+      message: The message text.
+      echo: Whether to also write a human-readable console line.
+      **fields: Per-call structured fields.
+
+    Returns:
+      None.
+
+    Raises:
+      None.
+    """
+    _log("INFO", message, echo, fields)
+
+
+def warning(message: str, *, echo: bool = False, **fields: object) -> None:
+    """Emits a ``WARNING`` event on the current span, or a standalone orphan span.
+
+    Args:
+      message: The message text.
+      echo: Whether to also write a human-readable console line.
+      **fields: Per-call structured fields.
+
+    Returns:
+      None.
+
+    Raises:
+      None.
+    """
+    _log("WARNING", message, echo, fields)
+
+
+def error(message: str, *, echo: bool = False, **fields: object) -> None:
+    """Emits an ``ERROR`` event on the current span, or a standalone orphan span.
+
+    Args:
+      message: The message text.
+      echo: Whether to also write a human-readable console line.
+      **fields: Per-call structured fields.
+
+    Returns:
+      None.
+
+    Raises:
+      None.
+    """
+    _log("ERROR", message, echo, fields)
+
+
+def critical(message: str, *, echo: bool = False, **fields: object) -> None:
+    """Emits a ``CRITICAL`` event on the current span, or a standalone orphan span.
+
+    Args:
+      message: The message text.
+      echo: Whether to also write a human-readable console line.
+      **fields: Per-call structured fields.
+
+    Returns:
+      None.
+
+    Raises:
+      None.
+    """
+    _log("CRITICAL", message, echo, fields)