activegraph 1.0.0rc2__py3-none-any.whl

activegraph/observability/logging.py

@@ -0,0 +1,205 @@
+"""Structured logging. CONTRACT v0.8 #6–#7, #16.
+
+The framework emits structured logs through stdlib ``logging``. We do
+NOT auto-configure on import — a library that does is hostile. By
+default the framework attaches to ``logging.getLogger("activegraph")``
+and lets the operator's config handle output.
+
+If the operator wants the opinionated setup, ``configure_logging`` adds
+a JSON-line handler with the documented schema.
+
+The schema is the operator contract. Dashboards built against these
+field names keep working across framework versions.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import sys
+import time
+from typing import Any, Callable, Optional
+
+
+LOGGER_ROOT = "activegraph"
+
+# The documented operator-facing log schema. Fields appear when
+# applicable; fields that don't apply are omitted (not nulled).
+LOG_FIELDS: tuple[str, ...] = (
+    "timestamp",
+    "level",
+    "logger",
+    "message",
+    "run_id",
+    "event_id",
+    "behavior",
+    "tool",
+    "model",
+    "cache_hit",
+    "cost_usd",
+    "latency_seconds",
+    "reason",
+    "error_type",
+    "error_message",
+)
+
+# Reserved attributes on every LogRecord (stdlib internals). Any
+# `extra=` field that collides is renamed in extras-pickup logic below.
+_RESERVED_RECORD_ATTRS = frozenset(
+    {
+        "args", "asctime", "created", "exc_info", "exc_text", "filename",
+        "funcName", "levelname", "levelno", "lineno", "message", "module",
+        "msecs", "msg", "name", "pathname", "process", "processName",
+        "relativeCreated", "stack_info", "thread", "threadName",
+        "taskName",  # 3.12+
+    }
+)
+
+
+_payload_redactor_state: dict[str, Optional[Callable[[dict], dict]]] = {
+    "fn": None
+}
+
+
+def set_payload_redactor(fn: Optional[Callable[[dict], dict]]) -> None:
+    """Install a redactor that runs on any payload before it enters a log
+    record's ``extra`` dict. Idempotent. Pass None to remove.
+    """
+    _payload_redactor_state["fn"] = fn
+
+
+def redact_payload(payload: dict) -> dict:
+    """Apply the configured redactor (or identity)."""
+    fn = _payload_redactor_state["fn"]
+    return fn(payload) if fn is not None else payload
+
+
+class JsonLineFormatter(logging.Formatter):
+    """One JSON object per log record, on one line.
+
+    Populates the documented LOG_FIELDS from the record's reserved
+    attributes plus any ``extra=`` dict the caller passed. Omits fields
+    that aren't present.
+    """
+
+    def __init__(self) -> None:
+        super().__init__()
+
+    def format(self, record: logging.LogRecord) -> str:
+        out: dict[str, Any] = {
+            "timestamp": _iso_utc(record.created),
+            "level": record.levelname,
+            "logger": record.name,
+            "message": record.getMessage(),
+        }
+        # Pluck extras: any record attribute not in the reserved set is
+        # treated as a documented field. We only emit fields documented
+        # in LOG_FIELDS so the schema is stable.
+        for k in LOG_FIELDS:
+            if k in out:
+                continue
+            v = getattr(record, k, _MISSING)
+            if v is _MISSING or v is None:
+                continue
+            out[k] = v
+        # Allow exc_info to flow into error_type / error_message even if
+        # the caller didn't pass them explicitly.
+        if record.exc_info and "error_type" not in out:
+            etype, evalue, _ = record.exc_info
+            if etype is not None:
+                out["error_type"] = etype.__name__
+            if evalue is not None and "error_message" not in out:
+                out["error_message"] = str(evalue)
+        return json.dumps(out, separators=(",", ":"), ensure_ascii=False)
+
+
+class _MISSING_T:  # sentinel
+    pass
+
+
+_MISSING = _MISSING_T()
+
+
+def _iso_utc(ts: float) -> str:
+    # Avoid datetime import overhead per record.
+    lt = time.gmtime(ts)
+    ms = int((ts - int(ts)) * 1000)
+    return (
+        f"{lt.tm_year:04d}-{lt.tm_mon:02d}-{lt.tm_mday:02d}T"
+        f"{lt.tm_hour:02d}:{lt.tm_min:02d}:{lt.tm_sec:02d}.{ms:03d}Z"
+    )
+
+
+def get_logger(name: str = LOGGER_ROOT) -> logging.Logger:
+    """Get a logger in the activegraph namespace.
+
+    ``get_logger("runtime")`` → ``logging.getLogger("activegraph.runtime")``.
+    ``get_logger("activegraph")`` → root activegraph logger.
+    """
+    if name == LOGGER_ROOT or name.startswith(LOGGER_ROOT + "."):
+        return logging.getLogger(name)
+    return logging.getLogger(f"{LOGGER_ROOT}.{name}")
+
+
+def runtime_log_extra(**fields: Any) -> dict[str, Any]:
+    """Build an ``extra=`` dict for a log call, dropping None values and
+    rejecting reserved LogRecord attribute names.
+
+    Use:
+        log.info("event emitted", extra=runtime_log_extra(
+            run_id=rt.run_id, event_id=e.id, behavior=b.name,
+        ))
+    """
+    out: dict[str, Any] = {}
+    for k, v in fields.items():
+        if v is None:
+            continue
+        if k in _RESERVED_RECORD_ATTRS:
+            # Don't smash stdlib internals; prefix the key.
+            out[f"ag_{k}"] = v
+            continue
+        out[k] = v
+    return out
+
+
+def configure_logging(
+    level: str | int = "INFO",
+    *,
+    json_output: bool = True,
+    stream: Any = None,
+    payload_redactor: Optional[Callable[[dict], dict]] = None,
+) -> logging.Logger:
+    """Configure the activegraph logger hierarchy.
+
+    Idempotent: repeated calls replace the existing handler rather than
+    stacking. Returns the activegraph root logger.
+
+    Args:
+        level: numeric or string level name.
+        json_output: True for the documented JSON-line format; False for
+            the stdlib default (one human-readable line).
+        stream: where to write. Defaults to stderr (the logging default).
+        payload_redactor: optional callable(dict) -> dict applied to any
+            payload before it's added to a log record's extra fields.
+    """
+    set_payload_redactor(payload_redactor)
+    logger = logging.getLogger(LOGGER_ROOT)
+    logger.setLevel(level)
+    # Replace existing activegraph handlers so calls are idempotent.
+    for h in list(logger.handlers):
+        if getattr(h, "_activegraph", False):
+            logger.removeHandler(h)
+    handler = logging.StreamHandler(stream or sys.stderr)
+    handler._activegraph = True  # type: ignore[attr-defined]
+    handler.setFormatter(
+        JsonLineFormatter()
+        if json_output
+        else logging.Formatter(
+            "%(asctime)s %(levelname)s %(name)s %(message)s"
+        )
+    )
+    logger.addHandler(handler)
+    # Don't propagate up to root if we own a handler — operators with
+    # their own root handler would double-print.
+    logger.propagate = False
+    return logger

activegraph/observability/metrics.py

@@ -0,0 +1,219 @@
+"""Metrics protocol + NoOp default. CONTRACT v0.8 #8–#10.
+
+Three methods. No timers (use a histogram with a latency value), no
+summaries (Prometheus-specific), no custom types. Adding a metric is
+a public API change — the standard metric list below is the operator
+contract.
+
+Cardinality rule (locked, CONTRACT v0.8 #C4):
+
+  run_id MAY appear as a tag on gauges of active state (cardinality
+  is bounded by the number of concurrently active runs).
+  run_id MUST NOT appear as a tag on counters or histograms.
+
+The ``METRIC_NAMES`` table enforces this at import time — any standard
+metric whose tag set violates the rule fails the test.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol, runtime_checkable
+
+
+# ---- the protocol --------------------------------------------------------
+
+
+@runtime_checkable
+class Metrics(Protocol):
+    """Three methods, all best-effort, all non-throwing.
+
+    Implementations MUST tolerate unknown metric names. Unknown tag keys
+    are also accepted; cardinality discipline is the caller's job.
+    """
+
+    def counter(self, name: str, tags: dict[str, str], value: float = 1.0) -> None: ...
+    def histogram(self, name: str, tags: dict[str, str], value: float) -> None: ...
+    def gauge(self, name: str, tags: dict[str, str], value: float) -> None: ...
+
+
+# ---- the no-op default ---------------------------------------------------
+
+
+class NoOpMetrics:
+    """Default Metrics implementation. Does nothing.
+
+    Three method bodies, each a single ``return``. The runtime is fully
+    functional with NoOpMetrics. Profile-checked for zero allocation
+    pressure under steady load.
+    """
+
+    __slots__ = ()
+
+    def counter(self, name: str, tags: dict[str, str], value: float = 1.0) -> None:
+        return
+
+    def histogram(self, name: str, tags: dict[str, str], value: float) -> None:
+        return
+
+    def gauge(self, name: str, tags: dict[str, str], value: float) -> None:
+        return
+
+
+# ---- the documented metric table ----------------------------------------
+
+# Type tags: c=counter, h=histogram, g=gauge.
+# Source of truth for the standard metric list. Conformance tests pin
+# this table; adding/removing a row is a public API change.
+
+
+@dataclass(frozen=True)
+class MetricSpec:
+    name: str
+    kind: str  # "counter" | "histogram" | "gauge"
+    tags: tuple[str, ...]
+    description: str
+
+
+METRIC_NAMES: tuple[MetricSpec, ...] = (
+    MetricSpec(
+        "activegraph_events_emitted_total",
+        "counter",
+        ("event_type",),
+        "Every event that lands in the graph's event log.",
+    ),
+    MetricSpec(
+        "activegraph_behaviors_invoked_total",
+        "counter",
+        ("behavior",),
+        "Each behavior invocation. Increments before the handler runs.",
+    ),
+    MetricSpec(
+        "activegraph_behaviors_failed_total",
+        "counter",
+        ("behavior", "reason"),
+        "Behavior invocations that produced a behavior.failed event.",
+    ),
+    MetricSpec(
+        "activegraph_behaviors_duration_seconds",
+        "histogram",
+        ("behavior",),
+        "Wall-clock duration of a behavior invocation (handler only).",
+    ),
+    MetricSpec(
+        "activegraph_llm_calls_total",
+        "counter",
+        ("model",),
+        "Every llm.requested event (cached and non-cached).",
+    ),
+    MetricSpec(
+        "activegraph_llm_cache_hits_total",
+        "counter",
+        ("model",),
+        "LLM calls served from the recorded-response cache.",
+    ),
+    MetricSpec(
+        "activegraph_llm_failed_total",
+        "counter",
+        ("model", "reason"),
+        "LLM calls that failed before producing a usable response.",
+    ),
+    MetricSpec(
+        "activegraph_llm_tokens_in",
+        "histogram",
+        ("model",),
+        "Input tokens reported by the provider per llm.responded.",
+    ),
+    MetricSpec(
+        "activegraph_llm_tokens_out",
+        "histogram",
+        ("model",),
+        "Output tokens reported by the provider per llm.responded.",
+    ),
+    MetricSpec(
+        "activegraph_llm_cost_usd",
+        "histogram",
+        ("model",),
+        "Per-call cost in USD as reported by the provider.",
+    ),
+    MetricSpec(
+        "activegraph_tools_calls_total",
+        "counter",
+        ("tool",),
+        "Every tool.requested event (cached and non-cached).",
+    ),
+    MetricSpec(
+        "activegraph_tools_cache_hits_total",
+        "counter",
+        ("tool",),
+        "Tool calls served from the recorded-response cache.",
+    ),
+    MetricSpec(
+        "activegraph_tools_failed_total",
+        "counter",
+        ("tool", "reason"),
+        "Tool calls that produced a tool.failed event.",
+    ),
+    MetricSpec(
+        "activegraph_tools_duration_seconds",
+        "histogram",
+        ("tool",),
+        "Wall-clock duration of a tool invocation.",
+    ),
+    MetricSpec(
+        "activegraph_queue_depth",
+        "gauge",
+        (),
+        "Current depth of the runtime's event queue.",
+    ),
+    MetricSpec(
+        "activegraph_budget_cost_remaining_usd",
+        "gauge",
+        ("run_id",),
+        "Remaining cost budget for an active run, USD.",
+    ),
+    MetricSpec(
+        "activegraph_budget_events_remaining",
+        "gauge",
+        ("run_id",),
+        "Remaining event budget for an active run.",
+    ),
+    MetricSpec(
+        "activegraph_patterns_evaluated_total",
+        "counter",
+        (),
+        "Pattern evaluations across all behaviors.",
+    ),
+    MetricSpec(
+        "activegraph_patterns_evaluation_duration_seconds",
+        "histogram",
+        (),
+        "Per-evaluation duration of a pattern subscription.",
+    ),
+    MetricSpec(
+        "activegraph_replay_divergence_detected_total",
+        "counter",
+        ("reason",),
+        "Replay-strict re-runs that diverged from the recorded log.",
+    ),
+)
+
+METRIC_BY_NAME: dict[str, MetricSpec] = {m.name: m for m in METRIC_NAMES}
+
+
+def validate_cardinality_rule(metrics: tuple[MetricSpec, ...] = METRIC_NAMES) -> None:
+    """Enforce CONTRACT v0.8 #C4: run_id only appears on gauges.
+
+    Called from the conformance test. Raises if any counter or histogram
+    declares run_id as a tag.
+    """
+    for spec in metrics:
+        if "run_id" in spec.tags and spec.kind != "gauge":
+            raise AssertionError(
+                f"metric {spec.name!r} ({spec.kind}) lists run_id as a tag — "
+                f"forbidden by the cardinality rule (run_id is gauge-only)."
+            )
+
+
+# Validate at import time so any in-tree edit fails loud.
+validate_cardinality_rule()