agent-first-data 0.2.0__tar.gz → 0.2.1__tar.gz

{agent_first_data-0.2.0 → agent_first_data-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-first-data
-Version: 0.2.0
+Version: 0.2.1
 Summary: Agent-First Data (AFD) — suffix-driven output formatting and protocol templates for AI agents
 License-Expression: MIT
 Project-URL: Repository, https://github.com/cmnspore/agent-first-data
@@ -21,7 +21,7 @@ pip install agent-first-data
 
 ## API Reference
 
-Total: **9 public APIs** (4 protocol builders + 3 output functions + 1 internal + 1 utility)
+Total: **9 public APIs** + **AFD logging** (4 protocol builders + 3 output functions + 1 internal + 1 utility)
 
 ### Protocol Builders (returns dict)
 
@@ -256,6 +256,132 @@ print(output_plain(data))
 # api_key=*** cache_ttl=3600s count=42 created_at=2025-02-07T00:00:00.000Z file_size=5.0MB payment=50000000msats price=$99.99 request_timeout=5.0s success_rate=95.5% user_name=alice
 ```
 
+## AFD Logging
+
+AFD-compliant structured logging via Python's `logging` module. Every log line is formatted using the library's own `output_json`/`output_plain`/`output_yaml` functions. Span fields are carried via `contextvars` (async-safe), automatically flattened into each log line.
+
+### API
+
+```python
+from agent_first_data import init_logging_json, init_logging_plain, init_logging_yaml
+from agent_first_data.afd_logging import AfdHandler, get_logger, span
+
+# Convenience initializers — set up the root logger with AFD output to stdout
+init_logging_json(level="INFO")    # Single-line JSONL (secrets redacted, original keys)
+init_logging_plain(level="INFO")   # Single-line logfmt (keys stripped, values formatted)
+init_logging_yaml(level="INFO")    # Multi-line YAML (keys stripped, values formatted)
+
+# Low-level — create a handler for custom logger stacks
+AfdHandler(format="json")  # format: "json" | "plain" | "yaml"
+
+# Logger with default fields (returns logging.LoggerAdapter)
+get_logger(name, **fields)
+
+# Span context manager — adds fields to all log events within the block
+span(**fields)
+```
+
+### Setup
+
+```python
+from agent_first_data import init_logging_json, init_logging_plain, init_logging_yaml
+
+# JSON output for production (one JSONL line per event, secrets redacted)
+init_logging_json("INFO")
+
+# Plain logfmt for development (keys stripped, values formatted)
+init_logging_plain("DEBUG")
+
+# YAML for detailed inspection (multi-line, keys stripped, values formatted)
+init_logging_yaml("DEBUG")
+```
+
+### Log Output
+
+Standard `logging` calls work unchanged. Output format depends on the init function used.
+
+```python
+import logging
+logger = logging.getLogger("myapp")
+
+logger.info("Server started")
+# JSON:  {"timestamp_epoch_ms":1739000000000,"message":"Server started","target":"myapp","code":"info"}
+# Plain: code=info message="Server started" target=myapp timestamp_epoch_ms=1739000000000
+# YAML:  ---
+#        code: "info"
+#        message: "Server started"
+#        target: "myapp"
+#        timestamp_epoch_ms: 1739000000000
+
+logger.warning("DNS lookup failed")
+# JSON:  {"timestamp_epoch_ms":...,"message":"DNS lookup failed","target":"myapp","code":"warn"}
+```
+
+### Span Support
+
+Use the `span` context manager to add fields to all log events within the block. Spans nest and work with both sync and async code.
+
+```python
+from agent_first_data import span
+
+with span(request_id="abc-123"):
+    logger.info("Processing")
+    # {"timestamp_epoch_ms":...,"message":"Processing","target":"myapp","request_id":"abc-123","code":"info"}
+
+    with span(step="validate"):
+        logger.info("Validating input")
+        # {"timestamp_epoch_ms":...,"message":"Validating input","target":"myapp","request_id":"abc-123","step":"validate","code":"info"}
+```
+
+### Logger with Default Fields
+
+Use `get_logger` for per-component fields that appear on every log line:
+
+```python
+from agent_first_data import get_logger
+
+logger = get_logger("myapp.auth", component="auth")
+logger.info("Token verified")
+# {"timestamp_epoch_ms":...,"message":"Token verified","target":"myapp.auth","component":"auth","code":"info"}
+```
+
+### Custom Code Override
+
+The `code` field defaults to the log level. Override with an explicit field:
+
+```python
+from agent_first_data import get_logger
+
+logger = get_logger("myapp")
+logger.info("Server ready", extra={"code": "startup"})
+# {"timestamp_epoch_ms":...,"message":"Server ready","target":"myapp","code":"startup"}
+```
+
+### Output Fields
+
+Every log line contains:
+
+| Field | Type | Description |
+|:------|:-----|:------------|
+| `timestamp_epoch_ms` | number | Unix milliseconds |
+| `message` | string | Log message |
+| `target` | string | Logger name |
+| `code` | string | Level (debug/info/warn/error) or explicit override |
+| *span fields* | any | From `span()` context manager |
+| *event fields* | any | From `extra=` or `get_logger` fields |
+
+### Log Output Formats
+
+All three formats use the library's own output functions, so AFD suffix processing applies to log fields too:
+
+| Format | Function | Keys | Values | Use case |
+|:-------|:---------|:-----|:-------|:---------|
+| **JSON** | `init_logging_json` | original (with suffix) | raw | production, log aggregation |
+| **Plain** | `init_logging_plain` | stripped | formatted | development, compact scanning |
+| **YAML** | `init_logging_yaml` | stripped | formatted | debugging, detailed inspection |
+
+All formats automatically redact `_secret` fields in log output.
+
 ## Output Formats
 
 Three output formats for different use cases:

{agent_first_data-0.2.0 → agent_first_data-0.2.1}/README.md

@@ -12,7 +12,7 @@ pip install agent-first-data
 
 ## API Reference
 
-Total: **9 public APIs** (4 protocol builders + 3 output functions + 1 internal + 1 utility)
+Total: **9 public APIs** + **AFD logging** (4 protocol builders + 3 output functions + 1 internal + 1 utility)
 
 ### Protocol Builders (returns dict)
 
@@ -247,6 +247,132 @@ print(output_plain(data))
 # api_key=*** cache_ttl=3600s count=42 created_at=2025-02-07T00:00:00.000Z file_size=5.0MB payment=50000000msats price=$99.99 request_timeout=5.0s success_rate=95.5% user_name=alice
 ```
 
+## AFD Logging
+
+AFD-compliant structured logging via Python's `logging` module. Every log line is formatted using the library's own `output_json`/`output_plain`/`output_yaml` functions. Span fields are carried via `contextvars` (async-safe), automatically flattened into each log line.
+
+### API
+
+```python
+from agent_first_data import init_logging_json, init_logging_plain, init_logging_yaml
+from agent_first_data.afd_logging import AfdHandler, get_logger, span
+
+# Convenience initializers — set up the root logger with AFD output to stdout
+init_logging_json(level="INFO")    # Single-line JSONL (secrets redacted, original keys)
+init_logging_plain(level="INFO")   # Single-line logfmt (keys stripped, values formatted)
+init_logging_yaml(level="INFO")    # Multi-line YAML (keys stripped, values formatted)
+
+# Low-level — create a handler for custom logger stacks
+AfdHandler(format="json")  # format: "json" | "plain" | "yaml"
+
+# Logger with default fields (returns logging.LoggerAdapter)
+get_logger(name, **fields)
+
+# Span context manager — adds fields to all log events within the block
+span(**fields)
+```
+
+### Setup
+
+```python
+from agent_first_data import init_logging_json, init_logging_plain, init_logging_yaml
+
+# JSON output for production (one JSONL line per event, secrets redacted)
+init_logging_json("INFO")
+
+# Plain logfmt for development (keys stripped, values formatted)
+init_logging_plain("DEBUG")
+
+# YAML for detailed inspection (multi-line, keys stripped, values formatted)
+init_logging_yaml("DEBUG")
+```
+
+### Log Output
+
+Standard `logging` calls work unchanged. Output format depends on the init function used.
+
+```python
+import logging
+logger = logging.getLogger("myapp")
+
+logger.info("Server started")
+# JSON:  {"timestamp_epoch_ms":1739000000000,"message":"Server started","target":"myapp","code":"info"}
+# Plain: code=info message="Server started" target=myapp timestamp_epoch_ms=1739000000000
+# YAML:  ---
+#        code: "info"
+#        message: "Server started"
+#        target: "myapp"
+#        timestamp_epoch_ms: 1739000000000
+
+logger.warning("DNS lookup failed")
+# JSON:  {"timestamp_epoch_ms":...,"message":"DNS lookup failed","target":"myapp","code":"warn"}
+```
+
+### Span Support
+
+Use the `span` context manager to add fields to all log events within the block. Spans nest and work with both sync and async code.
+
+```python
+from agent_first_data import span
+
+with span(request_id="abc-123"):
+    logger.info("Processing")
+    # {"timestamp_epoch_ms":...,"message":"Processing","target":"myapp","request_id":"abc-123","code":"info"}
+
+    with span(step="validate"):
+        logger.info("Validating input")
+        # {"timestamp_epoch_ms":...,"message":"Validating input","target":"myapp","request_id":"abc-123","step":"validate","code":"info"}
+```
+
+### Logger with Default Fields
+
+Use `get_logger` for per-component fields that appear on every log line:
+
+```python
+from agent_first_data import get_logger
+
+logger = get_logger("myapp.auth", component="auth")
+logger.info("Token verified")
+# {"timestamp_epoch_ms":...,"message":"Token verified","target":"myapp.auth","component":"auth","code":"info"}
+```
+
+### Custom Code Override
+
+The `code` field defaults to the log level. Override with an explicit field:
+
+```python
+from agent_first_data import get_logger
+
+logger = get_logger("myapp")
+logger.info("Server ready", extra={"code": "startup"})
+# {"timestamp_epoch_ms":...,"message":"Server ready","target":"myapp","code":"startup"}
+```
+
+### Output Fields
+
+Every log line contains:
+
+| Field | Type | Description |
+|:------|:-----|:------------|
+| `timestamp_epoch_ms` | number | Unix milliseconds |
+| `message` | string | Log message |
+| `target` | string | Logger name |
+| `code` | string | Level (debug/info/warn/error) or explicit override |
+| *span fields* | any | From `span()` context manager |
+| *event fields* | any | From `extra=` or `get_logger` fields |
+
+### Log Output Formats
+
+All three formats use the library's own output functions, so AFD suffix processing applies to log fields too:
+
+| Format | Function | Keys | Values | Use case |
+|:-------|:---------|:-----|:-------|:---------|
+| **JSON** | `init_logging_json` | original (with suffix) | raw | production, log aggregation |
+| **Plain** | `init_logging_plain` | stripped | formatted | development, compact scanning |
+| **YAML** | `init_logging_yaml` | stripped | formatted | debugging, detailed inspection |
+
+All formats automatically redact `_secret` fields in log output.
+
 ## Output Formats
 
 Three output formats for different use cases:

{agent_first_data-0.2.0 → agent_first_data-0.2.1}/agent_first_data/__init__.py

@@ -12,6 +12,16 @@ from agent_first_data.format import (
     parse_size,
 )
 
+from agent_first_data.afd_logging import (
+    AfdHandler,
+    AfdJsonHandler,
+    init_json as init_logging_json,
+    init_plain as init_logging_plain,
+    init_yaml as init_logging_yaml,
+    get_logger,
+    span,
+)
+
 __all__ = [
     "build_json_startup",
     "build_json_ok",
@@ -22,4 +32,11 @@ __all__ = [
     "output_plain",
     "internal_redact_secrets",
     "parse_size",
+    "AfdHandler",
+    "AfdJsonHandler",
+    "init_logging_json",
+    "init_logging_plain",
+    "init_logging_yaml",
+    "get_logger",
+    "span",
 ]

agent_first_data-0.2.1/agent_first_data/afd_logging.py

@@ -0,0 +1,161 @@
+"""AFD-compliant structured logging.
+
+Outputs log events using agent-first-data formatting functions:
+- JSON: single-line JSONL via output_json (secrets redacted, original keys)
+- Plain: single-line logfmt via output_plain (keys stripped, values formatted)
+- YAML: multi-line via output_yaml (keys stripped, values formatted)
+
+Span fields are carried via contextvars (async-safe).
+
+Usage:
+    from agent_first_data.afd_logging import init_json, init_plain, init_yaml, span
+    import logging
+
+    init_json("INFO")   # or init_plain("INFO") or init_yaml("DEBUG")
+    logger = logging.getLogger("myapp")
+
+    with span(request_id="abc-123"):
+        logger.info("Processing")
+"""
+
+import logging
+import sys
+from contextvars import ContextVar, Token
+from typing import Any
+
+from agent_first_data.format import output_json, output_plain, output_yaml
+
+_span_fields: ContextVar[dict[str, Any]] = ContextVar("afd_span", default={})
+
+_LEVEL_TO_CODE = {
+    "CRITICAL": "error",
+    "ERROR": "error",
+    "WARNING": "warn",
+    "WARN": "warn",
+    "INFO": "info",
+    "DEBUG": "debug",
+    "NOTSET": "trace",
+}
+
+
+class AfdHandler(logging.Handler):
+    """Logging handler that outputs AFD-compliant log lines to stdout.
+
+    Formats output using the library's own output_json/output_plain/output_yaml.
+    """
+
+    def __init__(self, format: str = "json") -> None:
+        super().__init__()
+        if format not in ("json", "plain", "yaml"):
+            raise ValueError(f"Unknown format: {format!r}, expected json/plain/yaml")
+        self._format = format
+
+    def emit(self, record: logging.LogRecord) -> None:
+        entry: dict[str, Any] = {
+            "timestamp_epoch_ms": int(record.created * 1000),
+            "message": record.getMessage(),
+            "target": record.name,
+        }
+
+        # Span fields (from contextvars, async-safe)
+        span_data = _span_fields.get()
+        if span_data:
+            entry.update(span_data)
+
+        # Event fields (passed via extra= in logging calls)
+        has_code = False
+        extra = getattr(record, "_afd_fields", None)
+        if extra:
+            for k, v in extra.items():
+                if k == "code":
+                    has_code = True
+                entry[k] = v
+
+        # Default code from level
+        if not has_code:
+            entry["code"] = _LEVEL_TO_CODE.get(record.levelname, "info")
+
+        # Format using the library's own output functions
+        if self._format == "plain":
+            line = output_plain(entry)
+        elif self._format == "yaml":
+            line = output_yaml(entry)
+        else:
+            line = output_json(entry)
+
+        sys.stdout.write(line + "\n")
+        sys.stdout.flush()
+
+
+# Keep old name as alias for backwards compat
+AfdJsonHandler = AfdHandler
+
+
+class _AfdLoggerAdapter(logging.LoggerAdapter):
+    """Logger adapter that passes extra fields to AfdHandler."""
+
+    def process(self, msg: str, kwargs: Any) -> tuple[str, Any]:
+        extra = kwargs.get("extra", {})
+        if self.extra:
+            merged = {**self.extra, **extra}
+        else:
+            merged = extra
+        kwargs["extra"] = {"_afd_fields": merged}
+        return msg, kwargs
+
+
+def _init_with_format(format: str, level: str = "INFO") -> None:
+    handler = AfdHandler(format=format)
+    root = logging.getLogger()
+    root.handlers = [handler]
+    root.setLevel(getattr(logging, level.upper(), logging.INFO))
+
+
+def init_json(level: str = "INFO") -> None:
+    """Initialize the root logger with AFD JSON output to stdout."""
+    _init_with_format("json", level)
+
+
+def init_plain(level: str = "INFO") -> None:
+    """Initialize the root logger with AFD plain/logfmt output to stdout."""
+    _init_with_format("plain", level)
+
+
+def init_yaml(level: str = "INFO") -> None:
+    """Initialize the root logger with AFD YAML output to stdout."""
+    _init_with_format("yaml", level)
+
+
+def get_logger(name: str, **fields: Any) -> logging.LoggerAdapter:
+    """Get a logger with optional default fields.
+
+    Fields passed here appear on every log line from this logger.
+    Use for per-module or per-component fields.
+    """
+    base = logging.getLogger(name)
+    return _AfdLoggerAdapter(base, fields)
+
+
+class span:
+    """Context manager that adds fields to all log events within the block.
+
+    Spans nest: inner spans inherit and can override outer span fields.
+    Works with both sync and async code (uses contextvars).
+
+    Usage:
+        with span(request_id="abc-123", method="GET"):
+            logger.info("Handling request")
+    """
+
+    def __init__(self, **fields: Any) -> None:
+        self.fields = fields
+        self._token: Token[dict[str, Any]] | None = None
+
+    def __enter__(self) -> "span":
+        current = _span_fields.get()
+        self._token = _span_fields.set({**current, **self.fields})
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        if self._token is not None:
+            _span_fields.reset(self._token)

{agent_first_data-0.2.0 → agent_first_data-0.2.1}/agent_first_data.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-first-data
-Version: 0.2.0
+Version: 0.2.1
 Summary: Agent-First Data (AFD) — suffix-driven output formatting and protocol templates for AI agents
 License-Expression: MIT
 Project-URL: Repository, https://github.com/cmnspore/agent-first-data
@@ -21,7 +21,7 @@ pip install agent-first-data
 
 ## API Reference
 
-Total: **9 public APIs** (4 protocol builders + 3 output functions + 1 internal + 1 utility)
+Total: **9 public APIs** + **AFD logging** (4 protocol builders + 3 output functions + 1 internal + 1 utility)
 
 ### Protocol Builders (returns dict)
 
@@ -256,6 +256,132 @@ print(output_plain(data))
 # api_key=*** cache_ttl=3600s count=42 created_at=2025-02-07T00:00:00.000Z file_size=5.0MB payment=50000000msats price=$99.99 request_timeout=5.0s success_rate=95.5% user_name=alice
 ```
 
+## AFD Logging
+
+AFD-compliant structured logging via Python's `logging` module. Every log line is formatted using the library's own `output_json`/`output_plain`/`output_yaml` functions. Span fields are carried via `contextvars` (async-safe), automatically flattened into each log line.
+
+### API
+
+```python
+from agent_first_data import init_logging_json, init_logging_plain, init_logging_yaml
+from agent_first_data.afd_logging import AfdHandler, get_logger, span
+
+# Convenience initializers — set up the root logger with AFD output to stdout
+init_logging_json(level="INFO")    # Single-line JSONL (secrets redacted, original keys)
+init_logging_plain(level="INFO")   # Single-line logfmt (keys stripped, values formatted)
+init_logging_yaml(level="INFO")    # Multi-line YAML (keys stripped, values formatted)
+
+# Low-level — create a handler for custom logger stacks
+AfdHandler(format="json")  # format: "json" | "plain" | "yaml"
+
+# Logger with default fields (returns logging.LoggerAdapter)
+get_logger(name, **fields)
+
+# Span context manager — adds fields to all log events within the block
+span(**fields)
+```
+
+### Setup
+
+```python
+from agent_first_data import init_logging_json, init_logging_plain, init_logging_yaml
+
+# JSON output for production (one JSONL line per event, secrets redacted)
+init_logging_json("INFO")
+
+# Plain logfmt for development (keys stripped, values formatted)
+init_logging_plain("DEBUG")
+
+# YAML for detailed inspection (multi-line, keys stripped, values formatted)
+init_logging_yaml("DEBUG")
+```
+
+### Log Output
+
+Standard `logging` calls work unchanged. Output format depends on the init function used.
+
+```python
+import logging
+logger = logging.getLogger("myapp")
+
+logger.info("Server started")
+# JSON:  {"timestamp_epoch_ms":1739000000000,"message":"Server started","target":"myapp","code":"info"}
+# Plain: code=info message="Server started" target=myapp timestamp_epoch_ms=1739000000000
+# YAML:  ---
+#        code: "info"
+#        message: "Server started"
+#        target: "myapp"
+#        timestamp_epoch_ms: 1739000000000
+
+logger.warning("DNS lookup failed")
+# JSON:  {"timestamp_epoch_ms":...,"message":"DNS lookup failed","target":"myapp","code":"warn"}
+```
+
+### Span Support
+
+Use the `span` context manager to add fields to all log events within the block. Spans nest and work with both sync and async code.
+
+```python
+from agent_first_data import span
+
+with span(request_id="abc-123"):
+    logger.info("Processing")
+    # {"timestamp_epoch_ms":...,"message":"Processing","target":"myapp","request_id":"abc-123","code":"info"}
+
+    with span(step="validate"):
+        logger.info("Validating input")
+        # {"timestamp_epoch_ms":...,"message":"Validating input","target":"myapp","request_id":"abc-123","step":"validate","code":"info"}
+```
+
+### Logger with Default Fields
+
+Use `get_logger` for per-component fields that appear on every log line:
+
+```python
+from agent_first_data import get_logger
+
+logger = get_logger("myapp.auth", component="auth")
+logger.info("Token verified")
+# {"timestamp_epoch_ms":...,"message":"Token verified","target":"myapp.auth","component":"auth","code":"info"}
+```
+
+### Custom Code Override
+
+The `code` field defaults to the log level. Override with an explicit field:
+
+```python
+from agent_first_data import get_logger
+
+logger = get_logger("myapp")
+logger.info("Server ready", extra={"code": "startup"})
+# {"timestamp_epoch_ms":...,"message":"Server ready","target":"myapp","code":"startup"}
+```
+
+### Output Fields
+
+Every log line contains:
+
+| Field | Type | Description |
+|:------|:-----|:------------|
+| `timestamp_epoch_ms` | number | Unix milliseconds |
+| `message` | string | Log message |
+| `target` | string | Logger name |
+| `code` | string | Level (debug/info/warn/error) or explicit override |
+| *span fields* | any | From `span()` context manager |
+| *event fields* | any | From `extra=` or `get_logger` fields |
+
+### Log Output Formats
+
+All three formats use the library's own output functions, so AFD suffix processing applies to log fields too:
+
+| Format | Function | Keys | Values | Use case |
+|:-------|:---------|:-----|:-------|:---------|
+| **JSON** | `init_logging_json` | original (with suffix) | raw | production, log aggregation |
+| **Plain** | `init_logging_plain` | stripped | formatted | development, compact scanning |
+| **YAML** | `init_logging_yaml` | stripped | formatted | debugging, detailed inspection |
+
+All formats automatically redact `_secret` fields in log output.
+
 ## Output Formats
 
 Three output formats for different use cases:

{agent_first_data-0.2.0 → agent_first_data-0.2.1}/agent_first_data.egg-info/SOURCES.txt

@@ -1,9 +1,11 @@
 README.md
 pyproject.toml
 agent_first_data/__init__.py
+agent_first_data/afd_logging.py
 agent_first_data/format.py
 agent_first_data.egg-info/PKG-INFO
 agent_first_data.egg-info/SOURCES.txt
 agent_first_data.egg-info/dependency_links.txt
 agent_first_data.egg-info/top_level.txt
+tests/test_afd_logging.py
 tests/test_format.py

{agent_first_data-0.2.0 → agent_first_data-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agent-first-data"
-version = "0.2.0"
+version = "0.2.1"
 description = "Agent-First Data (AFD) — suffix-driven output formatting and protocol templates for AI agents"
 license = "MIT"
 readme = "README.md"

agent_first_data-0.2.1/tests/test_afd_logging.py

@@ -0,0 +1,173 @@
+"""Tests for AFD logging module."""
+
+import json
+import logging
+import sys
+from io import StringIO
+from unittest.mock import patch
+
+from agent_first_data.afd_logging import AfdHandler, AfdJsonHandler, init_json, init_plain, init_yaml, span, get_logger
+
+
+def capture_log(fn):
+    """Run fn and return the parsed JSON log line."""
+    buf = StringIO()
+    with patch("sys.stdout", buf):
+        fn()
+    line = buf.getvalue().strip()
+    assert line, "No log output captured"
+    return json.loads(line)
+
+
+def make_logger(name="test"):
+    """Create a fresh logger with AfdJsonHandler."""
+    logger = logging.getLogger(name)
+    logger.handlers = [AfdJsonHandler()]
+    logger.setLevel(logging.DEBUG)
+    return logger
+
+
+class TestBasicFields:
+    def test_info_message(self):
+        logger = make_logger("test_basic")
+        m = capture_log(lambda: logger.info("hello world"))
+        assert m["message"] == "hello world"
+        assert m["code"] == "info"
+        assert "timestamp_epoch_ms" in m
+        assert m["target"] == "test_basic"
+
+    def test_warning_code(self):
+        logger = make_logger("test_warn")
+        m = capture_log(lambda: logger.warning("something wrong"))
+        assert m["code"] == "warn"
+
+    def test_error_code(self):
+        logger = make_logger("test_error")
+        m = capture_log(lambda: logger.error("failure"))
+        assert m["code"] == "error"
+
+    def test_debug_code(self):
+        logger = make_logger("test_debug")
+        m = capture_log(lambda: logger.debug("verbose"))
+        assert m["code"] == "debug"
+
+
+class TestSpan:
+    def test_span_adds_fields(self):
+        logger = make_logger("test_span")
+
+        def run():
+            with span(request_id="abc-123"):
+                logger.info("processing")
+
+        m = capture_log(run)
+        assert m["request_id"] == "abc-123"
+        assert m["message"] == "processing"
+
+    def test_nested_spans(self):
+        logger = make_logger("test_nested")
+
+        def run():
+            with span(request_id="outer"):
+                with span(step="inner"):
+                    logger.info("nested")
+
+        m = capture_log(run)
+        assert m["request_id"] == "outer"
+        assert m["step"] == "inner"
+
+    def test_inner_span_overrides_parent(self):
+        logger = make_logger("test_override")
+
+        def run():
+            with span(source="parent"):
+                with span(source="child"):
+                    logger.info("test")
+
+        m = capture_log(run)
+        assert m["source"] == "child"
+
+    def test_span_fields_removed_after_exit(self):
+        logger = make_logger("test_exit")
+        buf = StringIO()
+
+        with patch("sys.stdout", buf):
+            with span(request_id="temp"):
+                logger.info("inside")
+            buf2 = StringIO()
+
+        with patch("sys.stdout", buf2):
+            logger.info("outside")
+
+        outside = json.loads(buf2.getvalue().strip())
+        assert "request_id" not in outside
+
+
+class TestCodeOverride:
+    def test_explicit_code(self):
+        logger = make_logger("test_code")
+        adapter = get_logger("test_code")
+
+        m = capture_log(lambda: adapter.info("ready", extra={"code": "startup"}))
+        assert m["code"] == "startup"
+
+
+class TestGetLogger:
+    def test_default_fields(self):
+        # Ensure root logger has AfdJsonHandler
+        root = logging.getLogger()
+        root.handlers = [AfdJsonHandler()]
+        root.setLevel(logging.DEBUG)
+
+        adapter = get_logger("test_adapter", component="myservice")
+
+        m = capture_log(lambda: adapter.info("event"))
+        assert m["component"] == "myservice"
+        assert m["message"] == "event"
+
+
+def capture_raw(fn):
+    """Run fn and return the raw output string."""
+    buf = StringIO()
+    with patch("sys.stdout", buf):
+        fn()
+    return buf.getvalue()
+
+
+class TestPlainFormat:
+    def test_plain_output(self):
+        logger = logging.getLogger("test_plain")
+        logger.handlers = [AfdHandler(format="plain")]
+        logger.setLevel(logging.DEBUG)
+
+        output = capture_raw(lambda: logger.info("hello"))
+        # Plain format is single-line logfmt
+        assert "message=" in output
+        assert "code=info" in output
+
+    def test_init_plain(self):
+        buf = StringIO()
+        with patch("sys.stdout", buf):
+            init_plain("DEBUG")
+            logging.getLogger("test_init_plain").info("test")
+        output = buf.getvalue()
+        assert "message=" in output
+
+
+class TestYamlFormat:
+    def test_yaml_output(self):
+        logger = logging.getLogger("test_yaml")
+        logger.handlers = [AfdHandler(format="yaml")]
+        logger.setLevel(logging.DEBUG)
+
+        output = capture_raw(lambda: logger.info("hello"))
+        # YAML format starts with ---
+        assert output.startswith("---")
+
+    def test_init_yaml(self):
+        buf = StringIO()
+        with patch("sys.stdout", buf):
+            init_yaml("DEBUG")
+            logging.getLogger("test_init_yaml").info("test")
+        output = buf.getvalue()
+        assert output.startswith("---")