log-foundry 0.10.2.dev42__tar.gz → 0.10.2.dev44__tar.gz

{log_foundry-0.10.2.dev42 → log_foundry-0.10.2.dev44}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: log-foundry
-Version: 0.10.2.dev42
+Version: 0.10.2.dev44
 Summary: Generate logs for your console and JSON events for downstream consumption.
 License-Expression: MIT
 License-File: LICENSE
@@ -327,8 +327,8 @@ await fetch(4127)   # one trace_id; load's parent_span_id == fetch's span_id
 Emit your own structured events from inside a decorated call with the level functions
 `debug` / `info` / `warning` / `error` / `critical`. Each appends one event to the current
 span, so the whole call's logs flush together and share its `trace_id` / `span_id`. Keyword
-arguments land in the event's `fields`; the function name is captured, but arguments and
-return values never are.
+arguments land in the event's `fields` — except the three reserved names below; the function
+name is captured, but arguments and return values never are.
 
 ```python
 @lf.trace
@@ -341,7 +341,8 @@ def process_payment(user_id: int) -> str:
 
 - **`set_baggage(**kv)`** — attach trace-scoped context that is merged into the `fields` of
   every subsequent event in the same execution flow. Precedence, lowest to highest: config
-  `defaults` → span `defaults` → baggage → per-call `fields`. **Trace-scoped means it ends
+  `defaults` → span `defaults` → baggage → per-call fields (`fields=` first, then `**kwargs`
+  over it). **Trace-scoped means it ends
   with the trace:** when the outermost `@trace` call returns *or raises*, the baggage in effect
   before it is restored, so one request's keys do not reach the next request's events. Nested
   calls do not reset — baggage set three calls deep stays visible to its parent and to the
@@ -352,6 +353,18 @@ def process_payment(user_id: int) -> str:
 - **`echo=True`** — *additionally* write a human-readable `LEVEL   message` line to the console
   (`sys.stderr` by default), synchronously, without waiting for the async flush. The event
   still rides the normal pipeline to the sink — echo never redirects.
+- **`fields={...}`** — the escape hatch. `message`, `echo` and `fields` are **reserved**: they
+  are parameters, so `info("x", echo="the payload we echoed back")` would switch on the console
+  line instead of recording a field. Pass them — and any key that is not a Python identifier —
+  through `fields=`:
+
+  ```python
+  lf.info("proxied", fields={"echo": "the payload we echoed back", "content-type": "text/json"})
+  ```
+
+  It reaches its own name too (`fields={"fields": ...}`), so every reserved word has exactly one
+  route through. A key given both ways takes the keyword's value, since `**kwargs` is what you
+  wrote at the call site and `fields=` is usually a mapping built elsewhere.
 - **Orphan logs** — a level call made with no active span is not dropped: it emits a standalone
   one-event span with a fresh `trace_id`, flushed straight to the sink.
 

{log_foundry-0.10.2.dev42 → log_foundry-0.10.2.dev44}/README.md

@@ -291,8 +291,8 @@ await fetch(4127)   # one trace_id; load's parent_span_id == fetch's span_id
 Emit your own structured events from inside a decorated call with the level functions
 `debug` / `info` / `warning` / `error` / `critical`. Each appends one event to the current
 span, so the whole call's logs flush together and share its `trace_id` / `span_id`. Keyword
-arguments land in the event's `fields`; the function name is captured, but arguments and
-return values never are.
+arguments land in the event's `fields` — except the three reserved names below; the function
+name is captured, but arguments and return values never are.
 
 ```python
 @lf.trace
@@ -305,7 +305,8 @@ def process_payment(user_id: int) -> str:
 
 - **`set_baggage(**kv)`** — attach trace-scoped context that is merged into the `fields` of
   every subsequent event in the same execution flow. Precedence, lowest to highest: config
-  `defaults` → span `defaults` → baggage → per-call `fields`. **Trace-scoped means it ends
+  `defaults` → span `defaults` → baggage → per-call fields (`fields=` first, then `**kwargs`
+  over it). **Trace-scoped means it ends
   with the trace:** when the outermost `@trace` call returns *or raises*, the baggage in effect
   before it is restored, so one request's keys do not reach the next request's events. Nested
   calls do not reset — baggage set three calls deep stays visible to its parent and to the
@@ -316,6 +317,18 @@ def process_payment(user_id: int) -> str:
 - **`echo=True`** — *additionally* write a human-readable `LEVEL   message` line to the console
   (`sys.stderr` by default), synchronously, without waiting for the async flush. The event
   still rides the normal pipeline to the sink — echo never redirects.
+- **`fields={...}`** — the escape hatch. `message`, `echo` and `fields` are **reserved**: they
+  are parameters, so `info("x", echo="the payload we echoed back")` would switch on the console
+  line instead of recording a field. Pass them — and any key that is not a Python identifier —
+  through `fields=`:
+
+  ```python
+  lf.info("proxied", fields={"echo": "the payload we echoed back", "content-type": "text/json"})
+  ```
+
+  It reaches its own name too (`fields={"fields": ...}`), so every reserved word has exactly one
+  route through. A key given both ways takes the keyword's value, since `**kwargs` is what you
+  wrote at the call site and `fields=` is usually a mapping built elsewhere.
 - **Orphan logs** — a level call made with no active span is not dropped: it emits a standalone
   one-event span with a fresh `trace_id`, flushed straight to the sink.
 

{log_foundry-0.10.2.dev42 → log_foundry-0.10.2.dev44}/pyproject.toml

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

{log_foundry-0.10.2.dev42 → log_foundry-0.10.2.dev44}/src/log_foundry/api.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+from typing import TYPE_CHECKING
+
 from log_foundry import _diag, context
 from log_foundry.config import _ensure_sink
 from log_foundry.console import ConsoleWriter
@@ -10,6 +12,9 @@ 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
 
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
 __all__ = [
     "critical",
     "debug",
@@ -100,13 +105,66 @@ def _log(level: str, message: str, echo: bool, fields: dict[str, object]) -> Non
             _diag.absorbed("echoing to the console", exc)
 
 
-def debug(message: str, *, echo: bool = False, **fields: object) -> None:
+def _merge(fields: Mapping[str, object] | None, kv: dict[str, object]) -> dict[str, object]:
+    """Combines the explicit ``fields=`` mapping with the keyword form.
+
+    ``echo`` and ``message`` were reserved words stolen from the caller's field namespace:
+    ``info("x", echo="incoming payload echoed back")`` dropped a real field *and* turned on an
+    unwanted console line, and ``message=`` raised ``TypeError`` (SPEC-034 FR-004). ``fields=``
+    is the way round all three — including its own name, which is why the escape hatch can
+    express every key including the ones this signature reserves — and the only way to pass a
+    key that is not a Python identifier.
+
+    The keyword form wins a collision. ``fields=`` is the bulk route, usually a mapping built
+    somewhere else; ``**kv`` is what the caller wrote at this call site, and a literal
+    overriding a base is what ``{**base, **overrides}`` already means in the language.
+
+    A ``fields=`` that is not a mapping is **absorbed, not raised**. This helper runs in the
+    emitter, before :func:`_log`, so it sits outside that function's orphan guard entirely: an
+    unguarded ``{**fields, **kv}`` propagated a ``TypeError`` into the application on all four
+    entry paths, including the orphan one where SPEC-025's promise holds today, and inside a span
+    the decorator then recorded ``status=error`` with an ``error.type`` the caller's code never
+    raised. It was also asymmetric in a way neither reading defends — ``fields=[]`` was silently
+    ignored while ``fields=["x"]`` crashed. The library coerces rather than validates (SPEC-017),
+    so the tolerant half is the one that matches, and the fault is announced by type.
+
+    Args:
+      fields: The explicit mapping, or ``None``.
+      kv: The keyword-collected fields.
+
+    Returns:
+      One mapping, with ``kv`` taking precedence. The caller's ``fields`` is never mutated, and a
+        ``fields=`` that could not be merged is dropped rather than costing the event.
+
+    Raises:
+      None.
+    """
+    if not fields:
+        return kv
+    try:
+        return {**fields, **kv}
+    except Exception as exc:
+        _diag.absorbed("merging the fields= argument", exc, "the fields= argument was ignored")
+        return kv
+
+
+def debug(
+    message: str,
+    *,
+    echo: bool = False,
+    fields: Mapping[str, object] | None = None,
+    **kv: 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.
+      fields: Per-call structured fields, for names ``**kv`` cannot express — the three
+        reserved words ``message``, ``echo`` and ``fields`` itself, and any key that is not a
+        Python identifier at all. Merged **under** ``**kv``, so a name given both ways takes the
+        keyword's value.
+      **kv: Per-call structured fields.
 
     Returns:
       None.
@@ -114,16 +172,26 @@ def debug(message: str, *, echo: bool = False, **fields: object) -> None:
     Raises:
       None.
     """
-    _log("DEBUG", message, echo, fields)
+    _log("DEBUG", message, echo, _merge(fields, kv))
 
 
-def info(message: str, *, echo: bool = False, **fields: object) -> None:
+def info(
+    message: str,
+    *,
+    echo: bool = False,
+    fields: Mapping[str, object] | None = None,
+    **kv: 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.
+      fields: Per-call structured fields, for names ``**kv`` cannot express — the three
+        reserved words ``message``, ``echo`` and ``fields`` itself, and any key that is not a
+        Python identifier at all. Merged **under** ``**kv``, so a name given both ways takes the
+        keyword's value.
+      **kv: Per-call structured fields.
 
     Returns:
       None.
@@ -131,16 +199,26 @@ def info(message: str, *, echo: bool = False, **fields: object) -> None:
     Raises:
       None.
     """
-    _log("INFO", message, echo, fields)
+    _log("INFO", message, echo, _merge(fields, kv))
 
 
-def warning(message: str, *, echo: bool = False, **fields: object) -> None:
+def warning(
+    message: str,
+    *,
+    echo: bool = False,
+    fields: Mapping[str, object] | None = None,
+    **kv: 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.
+      fields: Per-call structured fields, for names ``**kv`` cannot express — the three
+        reserved words ``message``, ``echo`` and ``fields`` itself, and any key that is not a
+        Python identifier at all. Merged **under** ``**kv``, so a name given both ways takes the
+        keyword's value.
+      **kv: Per-call structured fields.
 
     Returns:
       None.
@@ -148,16 +226,26 @@ def warning(message: str, *, echo: bool = False, **fields: object) -> None:
     Raises:
       None.
     """
-    _log("WARNING", message, echo, fields)
+    _log("WARNING", message, echo, _merge(fields, kv))
 
 
-def error(message: str, *, echo: bool = False, **fields: object) -> None:
+def error(
+    message: str,
+    *,
+    echo: bool = False,
+    fields: Mapping[str, object] | None = None,
+    **kv: 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.
+      fields: Per-call structured fields, for names ``**kv`` cannot express — the three
+        reserved words ``message``, ``echo`` and ``fields`` itself, and any key that is not a
+        Python identifier at all. Merged **under** ``**kv``, so a name given both ways takes the
+        keyword's value.
+      **kv: Per-call structured fields.
 
     Returns:
       None.
@@ -165,16 +253,26 @@ def error(message: str, *, echo: bool = False, **fields: object) -> None:
     Raises:
       None.
     """
-    _log("ERROR", message, echo, fields)
+    _log("ERROR", message, echo, _merge(fields, kv))
 
 
-def critical(message: str, *, echo: bool = False, **fields: object) -> None:
+def critical(
+    message: str,
+    *,
+    echo: bool = False,
+    fields: Mapping[str, object] | None = None,
+    **kv: 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.
+      fields: Per-call structured fields, for names ``**kv`` cannot express — the three
+        reserved words ``message``, ``echo`` and ``fields`` itself, and any key that is not a
+        Python identifier at all. Merged **under** ``**kv``, so a name given both ways takes the
+        keyword's value.
+      **kv: Per-call structured fields.
 
     Returns:
       None.
@@ -182,4 +280,4 @@ def critical(message: str, *, echo: bool = False, **fields: object) -> None:
     Raises:
       None.
     """
-    _log("CRITICAL", message, echo, fields)
+    _log("CRITICAL", message, echo, _merge(fields, kv))

{log_foundry-0.10.2.dev42 → log_foundry-0.10.2.dev44}/src/log_foundry/config.py

@@ -2,14 +2,15 @@
 
 from __future__ import annotations
 
-from dataclasses import dataclass, field
+import threading
+from dataclasses import dataclass, field, replace
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
     from log_foundry.sinks.base import Sink
 
 
-@dataclass
+@dataclass(frozen=True)
 class Config:
     """Process-wide settings stamped onto every event and consulted by the pipeline.
 
@@ -22,6 +23,13 @@ class Config:
     string is measured in UTF-8 bytes, an integer in the decimal length it renders as, sign
     included. An integer is also bounded by ``sys.get_int_max_str_digits()`` whenever that
     is lower, since a longer one cannot be rendered at all.
+
+    It is **frozen** (SPEC-034 FR-003). :func:`get_config` handed out this object, so assigning
+    to it retargeted what the config *reported* while every event continued to the sink the
+    worker had already captured — SPEC-030's defect reachable with no underscore in sight — and
+    assigning a ceiling bypassed :func:`_require_positive`, so ``max_value_bytes = 0`` was
+    accepted and emptied every event it touched. Both measured. :func:`configure` is the only
+    supported route to a change, and it rebinds the module global rather than mutating.
     """
 
     service: str = "unknown"
@@ -37,6 +45,25 @@ class Config:
 
 _config = Config()
 
+_config_lock = threading.Lock()
+"""Serializes the read-modify-write that replacing a frozen config now is.
+
+Freezing :class:`Config` turned each field assignment into a whole-object
+``replace()`` — a read of every field followed by a write of every field — and one of the two
+call sites, :func:`_ensure_sink`, runs on the **orphan logging path**, on whatever application
+thread called ``info()``. A stale snapshot there puts back the pre-``configure()`` ``service``,
+``version``, ``env``, ``defaults`` *and* ``sink``, permanently. Measured on the unlocked version:
+268 of 2000 trials shipped every later event with ``service="unknown"`` after one concurrent
+``info()``, against 0 before the freeze — a regression, and the SPEC-024 category of wrong data
+rather than lost data.
+
+It does **not** cover reads. :func:`_live_config` is one atomic global read and stays lock-free,
+so the per-event path pays nothing (SPEC-034 FR-003 AC-6). Lock ordering is one-way and stays
+that way: ``_ensure_sink`` is called with ``decorator._worker_lock`` held, and ``configure()``
+releases this lock before ``_swap_live_sink`` takes that one, so nothing acquires
+``_worker_lock`` underneath this.
+"""
+
 
 def _require_positive(name: str, value: int | None) -> None:
     """Rejects a non-positive ceiling.
@@ -127,24 +154,22 @@ def configure(
     _require_positive("max_keys", max_keys)
     _require_positive("max_depth", max_depth)
 
-    if service is not None:
-        _config.service = service
-    if version is not None:
-        _config.version = version
-    if env is not None:
-        _config.env = env
-    if sink is not None:
-        _config.sink = sink
-    if defaults is not None:
-        _config.defaults = dict(defaults)
-    if max_value_bytes is not None:
-        _config.max_value_bytes = max_value_bytes
-    if max_stack_bytes is not None:
-        _config.max_stack_bytes = max_stack_bytes
-    if max_keys is not None:
-        _config.max_keys = max_keys
-    if max_depth is not None:
-        _config.max_depth = max_depth
+    changed: dict[str, object] = {
+        name: value
+        for name, value in (
+            ("service", service),
+            ("version", version),
+            ("env", env),
+            ("sink", sink),
+            ("defaults", None if defaults is None else dict(defaults)),
+            ("max_value_bytes", max_value_bytes),
+            ("max_stack_bytes", max_stack_bytes),
+            ("max_keys", max_keys),
+            ("max_depth", max_depth),
+        )
+        if value is not None
+    }
+    _rebind(**changed)
 
     _ensure_sink()
 
@@ -183,18 +208,73 @@ def _swap_live_sink(sink: Sink) -> None:
 def get_config() -> Config:
     """Returns the current global config, for reading.
 
-    **Mutating what this returns is unsupported and will raise from 1.0** (SPEC-034 FR-003).
-    Today it hands back the live singleton, so assigning to it retargets what the config
-    *reports* while every event continues to the sink the worker already captured, and assigning
-    a ceiling bypasses the validation :func:`configure` performs — ``max_value_bytes = 0`` is
-    accepted and empties every event it touches. Both measured. :func:`configure` is the only
-    supported route to a change.
+    **Mutating what this returns raises** (SPEC-034 FR-003). It used to hand back the live
+    singleton, so assigning to it retargeted what the config *reported* while every event
+    continued to the sink the worker had already captured, and assigning a ceiling bypassed the
+    validation :func:`configure` performs — ``max_value_bytes = 0`` was accepted and emptied
+    every event it touched. Both measured. :func:`configure` is the only route to a change.
+
+    It is a **copy**, not the frozen original, and ``defaults`` is copied with it. A caller who
+    defeats the freeze — ``object.__setattr__`` reaches through any frozen dataclass — then
+    edits an object the library does not read, rather than the live config; and ``defaults`` is
+    a plain mutable ``dict``, so sharing it would leave the freeze cosmetic at the one field
+    that is not a scalar. ``dataclasses.replace`` alone does **not** do this: it shares the
+    dict, which was measured while building this.
 
     Args:
       None.
 
     Returns:
-      The process-wide :class:`Config`, to be treated as read-only.
+      A copy of the process-wide :class:`Config`, with its own ``defaults``.
+
+    Raises:
+      None.
+    """
+    return replace(_config, defaults=dict(_config.defaults))
+
+
+def _rebind(**changed: object) -> None:
+    """Replaces the module-global config with a copy carrying the changed fields.
+
+    :class:`Config` is frozen (SPEC-034 FR-003), so a change is a new object and a rebinding of
+    the global rather than an assignment to a field. It is **one** replacement for the whole
+    call, not one per field: nine rebindings would allocate nine configs and, worse, would leave
+    a window in which another thread reads a half-applied config — a `service` from the new call
+    beside a `sink` from the old one, stamped onto real events.
+
+    Rebinding is safe only because no module imports ``_config`` by value; a
+    ``from log_foundry.config import _config`` anywhere would hold the pre-rebind object forever,
+    which is why a test asserts the absence rather than a comment claiming it.
+
+    Args:
+      **changed: Field names and their new values. Fields not named keep their current value.
+
+    Returns:
+      None.
+
+    Raises:
+      None.
+    """
+    global _config
+    with _config_lock:
+        _config = replace(_config, **changed)  # type: ignore[arg-type]
+
+
+def _live_config() -> Config:
+    """Returns the config object itself, for callers inside the package.
+
+    :func:`get_config` copies, because it is public and a caller must not be able to reach the
+    live object through it. ``model.build_event`` reads the config **one to three times per
+    event**, so routing that through the public accessor would allocate a ``Config`` and a
+    ``defaults`` dict per event. The freeze is a guarantee to the library's *users*, not one the
+    library needs against itself, so internal callers read the live object and treat it as
+    read-only — the same split :func:`context._live_baggage` makes for baggage.
+
+    Args:
+      None.
+
+    Returns:
+      The live process-wide :class:`Config`.
 
     Raises:
       None.
@@ -210,6 +290,14 @@ def _ensure_sink() -> Sink:
     user has not called ``configure()`` yet. The local import defers the ``sinks``
     dependency and avoids a top-level import cycle (arch §7).
 
+    It is called on the **orphan logging path**, on arbitrary application threads, so the
+    default is resolved under :data:`_config_lock` with a double check and the global is re-read
+    inside it (SPEC-034 FR-003). Returning a freshly built local instead handed two racing
+    threads two different ``StdoutSink`` objects — measured 996 of 3000 trials — one of which
+    then received events and was referenced by nothing, so nothing closed it (SPEC-031 FR-006).
+    The unlocked read above it is the fast path: once a sink is configured this is one atomic
+    global read and no lock at all.
+
     Args:
       None.
 
@@ -219,8 +307,17 @@ def _ensure_sink() -> Sink:
     Raises:
       None.
     """
-    if _config.sink is None:
-        from log_foundry.sinks.stdout import StdoutSink
-
-        _config.sink = StdoutSink()
-    return _config.sink
+    global _config
+    sink_now = _config.sink
+    if sink_now is not None:
+        return sink_now
+
+    from log_foundry.sinks.stdout import StdoutSink
+
+    with _config_lock:
+        if _config.sink is None:
+            _config = replace(_config, sink=StdoutSink())
+        resolved = _config.sink
+    if resolved is None:  # pragma: no cover - unreachable; the branch above just set it
+        raise RuntimeError("the default sink could not be resolved")
+    return resolved

{log_foundry-0.10.2.dev42 → log_foundry-0.10.2.dev44}/src/log_foundry/model.py

@@ -8,7 +8,7 @@ from dataclasses import dataclass, field
 from datetime import UTC, datetime
 from typing import TYPE_CHECKING
 
-from log_foundry.config import get_config
+from log_foundry.config import _live_config
 from log_foundry.ids import new_log_id
 from log_foundry.sanitize import sanitize_fields, truncate_str, truncate_tail
 
@@ -93,7 +93,7 @@ def build_event(
     Raises:
       None.
     """
-    cfg = get_config()
+    cfg = _live_config()
     merged: dict[str, object] = {**cfg.defaults, **span.defaults, **baggage, **fields}
     safe, clipped = sanitize_fields(merged, cfg=cfg)
     bounded_message, message_clipped = truncate_str(message, cfg.max_value_bytes)
@@ -236,7 +236,7 @@ def end_event(
     event["duration_ms"] = (time.monotonic() - span.start_ts) * 1000.0
     event["status"] = status
     if exc is not None:
-        error, clipped = _error_fields(exc, cfg=get_config())
+        error, clipped = _error_fields(exc, cfg=_live_config())
         event["error"] = error
         if clipped:
             event[_TRUNCATED] = True
@@ -269,7 +269,7 @@ def backfill_baggage(span: Span, baggage: dict[str, object]) -> None:
     """
     if not baggage:
         return
-    safe, clipped = sanitize_fields(baggage, cfg=get_config())
+    safe, clipped = sanitize_fields(baggage, cfg=_live_config())
     for event in span.events:
         if event.get("message") in (_START_MESSAGE, _END_MESSAGE):
             fields = event.get("fields")