ph-core 0.2.0__py3-none-any.whl

ph/seams/telemetry.py

@@ -0,0 +1,249 @@
+"""`ctx.session_telemetry` — records, redaction, and no span tracer.
+
+**The session log is the trace** (§8). There is deliberately no span
+hierarchy: spans would be a second, lossier account of what already exists
+event-by-event in the log, and two accounts of one run diverge.
+
+What this seam adds is *export*: a record stream a sink can ship somewhere,
+with one hard ordering rule — **every record passes the
+`session-telemetry/record` redaction waterfall before any sink sees it**. A sink
+registered as a listener alongside redaction could observe an unredacted record
+by winning a race; a sink registered through `add_sink` cannot, because it runs
+after the waterfall settles.
+
+Ledger records mirror session events one-to-one with one exception: only the
+*first* `assistant/chunk` per step ships, because a token-by-token export is
+thousands of records saying the same thing, and the first is the one that
+carries the latency signal.
+
+@module ph.seams.telemetry
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from functools import partial
+from typing import Any, Literal, TypeAlias
+
+import anyio
+
+from ..cordis import (
+    Context,
+    Disposer,
+    MaybeAwaitable,
+    Running,
+    events,
+    maybe_await,
+    plugin,
+    running,
+    settled_or_none,
+)
+from ..json import as_int, dumps
+from ..keys import SESSION_TELEMETRY, SESSIONS
+from ..paths import default_home_path, write_text_under
+from ..session import Session, SessionEvent, now_ms
+from ..wire import WireModel
+from ._registry import claim_entry
+
+__all__ = [
+    "SessionTelemetry",
+    "SessionTelemetryRecord",
+    "apply",
+    "ops_record",
+]
+
+log = logging.getLogger("ph.seams.telemetry")
+
+Channel: TypeAlias = Literal["ledger", "ops"]
+Severity: TypeAlias = Literal["debug", "info", "warn", "error"]
+
+events.declare(
+    "session-telemetry/record",
+    "waterfall",
+    owner="ph.seams.telemetry",
+    doc="Redaction. Runs before any sink; a listener may rewrite or drop a record.",
+)
+
+
+class SessionTelemetryRecord(WireModel):
+    """One exportable record."""
+
+    channel: Channel
+    time: int
+    severity: Severity
+    attributes: dict[str, Any]
+    body: str
+
+
+@dataclass(frozen=True, slots=True)
+class _Sink:
+    """An exporter and who registered it (P6-29).
+
+    A sink is a row's body this seam invokes, once per record — the same category
+    as a tool's `execute`, and it ran unbound, so an exporter that registered
+    anything landed it on the seam and outlived its row."""
+
+    export: Callable[[SessionTelemetryRecord], MaybeAwaitable[None]]
+    by: Running
+
+
+@dataclass(slots=True)
+class SessionTelemetry:
+    """The service published as `ctx.session_telemetry`."""
+
+    ctx: Context
+    _sinks: list[_Sink] = field(default_factory=list)
+    _exporting: bool = False
+    """Whether a fan-out is already in flight, so a sink cannot feed itself.
+
+    A sink that records what it just failed to ship — through `ops_record`, or
+    any indirection reaching it — would re-enter `record` and fan out to itself,
+    a loop with no floor. The rule was a docstring asking each future sink author
+    to remember; this is the same rule where it cannot be forgotten. Dropping the
+    nested record is the intended answer, not a cost: it is a record *about* the
+    export path, made while that path is the thing failing."""
+    _last_chunked_step: dict[str, tuple[int, int]] = field(default_factory=dict)
+    """Per session, the step whose first chunk already shipped. One entry per
+    session rather than one per step, so it does not grow with the conversation."""
+
+    def add_sink(
+        self,
+        sink: Callable[[SessionTelemetryRecord], MaybeAwaitable[None]],
+        *,
+        scope: Context | None = None,
+    ) -> Disposer:
+        """Register an exporter. It sees only post-redaction records."""
+        by = self.ctx.running_for(scope)
+        return claim_entry(by.owner, self._sinks, _Sink(sink, by), label="telemetry.sink")
+
+    async def record(self, record: SessionTelemetryRecord) -> None:
+        """Redact, then fan out. A dropped record reaches no sink."""
+
+        async def inner(candidate: SessionTelemetryRecord) -> SessionTelemetryRecord | None:
+            return candidate
+
+        answered = await self.ctx.waterfall("session-telemetry/record", record, inner=inner)
+        redacted = settled_or_none("session-telemetry/record", answered, SessionTelemetryRecord)
+        if redacted is None or self._exporting:
+            return
+        self._exporting = True
+        try:
+            for sink in list(self._sinks):
+                try:
+                    # No target: telemetry is deployment-wide, so both halves are
+                    # what registration recorded.
+                    with running(sink.by):
+                        await maybe_await(sink.export(redacted))
+                except Exception:
+                    log.exception("ph.seams.telemetry: a sink failed")
+        finally:
+            self._exporting = False
+
+    def wants(self, session: Session, event: SessionEvent) -> bool:
+        """Whether this event ships — decided synchronously, so a dropped chunk
+        costs no task. Only the first `assistant/chunk` per step does."""
+        if event.type != "assistant/chunk":
+            return True
+        step = (as_int(event.data.get("turn")), as_int(event.data.get("step")))
+        if self._last_chunked_step.get(session.id) == step:
+            return False
+        self._last_chunked_step[session.id] = step
+        return True
+
+    async def observe(self, session: Session, event: SessionEvent) -> None:
+        """Mirror one session event onto the ledger channel."""
+        await self.record(
+            SessionTelemetryRecord(
+                channel="ledger",
+                time=event.time,
+                severity="info",
+                attributes={
+                    "session.id": session.id,
+                    "event.type": event.type,
+                    "event.seq": event.seq,
+                },
+                body=event.type,
+            )
+        )
+
+    async def ops(
+        self,
+        body: str,
+        *,
+        severity: Severity = "info",
+        **attributes: object,
+    ) -> None:
+        """Record something about the harness rather than the conversation."""
+        await self.record(
+            SessionTelemetryRecord(
+                channel="ops",
+                time=now_ms(),
+                severity=severity,
+                attributes=attributes,
+                body=body,
+            )
+        )
+
+
+async def ops_record(
+    ctx: Context,
+    body: str,
+    *,
+    severity: Severity = "info",
+    **attributes: object,
+) -> None:
+    """Record something about the harness, if this deployment has the seam (P5-09).
+
+    The producer's door. A row or a host holding a fact that is *not* a session
+    event — an open refused because another process holds the log, a store that
+    cannot take the I-5 lease, a workspace provider that broke and left an agent
+    uncontained — says it here and never looks for the seam itself. No seam, no
+    record and no error: telemetry is optional, and a producer must not fail its
+    own work for want of somewhere to put a note about it.
+
+    A sink that failed and reported its own failure here would fan out to the
+    same sink, which is a loop with no floor; `record` refuses a nested fan-out
+    for that reason, so reaching this from inside a sink drops the record rather
+    than recursing.
+    """
+    telemetry = ctx.get(SESSION_TELEMETRY)
+    if telemetry is None:
+        return
+    try:
+        await telemetry.ops(body, severity=severity, **attributes)
+    except Exception:
+        log.exception("ph.seams.telemetry: an ops record could not be made")
+
+
+class Config(WireModel):
+    """Row config for the JSONL telemetry sink."""
+
+    path: str | None = None
+    enabled: bool = True
+
+
+@plugin("session-telemetry", config=Config, inject=[SESSIONS])
+async def apply(ctx: Context, config: Config) -> None:
+    """Mount the telemetry seam and, when enabled, the JSONL sink."""
+    telemetry = SessionTelemetry(ctx=ctx)
+    ctx.provide(SESSION_TELEMETRY, telemetry)
+
+    if config.enabled:
+        path = default_home_path(config.path, "telemetry.jsonl")
+
+        async def write(record: SessionTelemetryRecord) -> None:
+            await anyio.to_thread.run_sync(
+                partial(write_text_under, path, f"{dumps(record.to_wire())}\n", append=True)
+            )
+
+        telemetry.add_sink(write)
+
+    def on_event(session: Session, event: SessionEvent) -> MaybeAwaitable[None]:
+        # The returned coroutine is scheduled by `emit`, never awaited on the
+        # append path; a chunk that will not ship returns nothing and costs no
+        # task at all.
+        return telemetry.observe(session, event) if telemetry.wants(session, event) else None
+
+    ctx.on("session/event", on_event)

ph/seams/telemetry_otel.py

@@ -0,0 +1,173 @@
+"""`session-telemetry-otel` — ship the ledger to an OTel collector (P5-09).
+
+A **sink**, registered through `SessionTelemetry.add_sink`, which is the whole
+security argument: `add_sink` runs after the `session-telemetry/record` redaction
+waterfall settles, so an exporter physically cannot observe a record the redactors
+dropped or rewrote. A row that listened on the waterfall event *alongside*
+redaction could see the unredacted form by winning a race; this one has no such
+race to win.
+
+**Logs, not spans**, which is §8's decision rather than a shortcut: "the session
+log is the trace", and a span hierarchy would be a second, lossier account of what
+the log already holds event by event. Each record becomes one OTel *log record*,
+carrying the channel and severity pH already assigned.
+
+**Optional, and honest when absent.** `opentelemetry-sdk` and the OTLP exporter
+distribution are an extra (`ph-core[otel]`), imported inside `apply` so a
+deployment that never exports does not pay them, and a profile that mounts this
+row without them gets a refusal naming what to install rather than an
+`ImportError` from the loader.
+
+**Nothing here half-mounts**: either the row can export or it refuses. Building a
+provider with no exporter would have `phern doctor` report a healthy telemetry sink
+shipping to nowhere.
+
+@module ph.seams.telemetry_otel
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..cordis import Context, MountRefusal, plugin
+from ..json import dumps
+from ..keys import SESSION_TELEMETRY
+from ..wire import WireModel
+from .diagnostics import Diagnostic, contribute
+from .telemetry import SessionTelemetryRecord
+
+__all__ = ["Config", "apply"]
+
+MISSING = (
+    "session-telemetry-otel needs the OpenTelemetry SDK and its OTLP exporter, "
+    "which are an extra: install `ph-core[otel]`, or remove this row."
+)
+"""Why the row refused, and the two ways out.
+
+A refusal rather than a silent no-op: a deployment that mounted an exporter and
+got nothing exported would discover it from the absence of data somewhere else,
+which is the worst place to learn it.
+"""
+
+SEVERITY = {"debug": 5, "info": 9, "warn": 13, "error": 17}
+"""pH's four severities as OTel severity numbers.
+
+The numbers are OTel's own scale (DEBUG=5, INFO=9, WARN=13, ERROR=17) written
+out rather than imported, so this mapping is readable without the SDK in front
+of you — and so the module's only hard dependency stays inside `apply`. The
+cost of writing them out is that a fifth pH severity could map to nothing; the
+test holds these keys against `get_args(Severity)` so that fails loudly rather
+than exporting the new severity as INFO.
+"""
+
+SCALARS = (str, int, float, bool)
+"""What OTel accepts as an attribute value. A tuple at module scope rather than a
+`str | int | float | bool` expression inside `_flat`, which would be evaluated per
+attribute per record.
+"""
+
+
+class Config(WireModel):
+    """Row config. `endpoint` empty means "whatever the OTEL_* environment says".
+
+    Deliberately thin: the OTel SDK already reads `OTEL_EXPORTER_OTLP_ENDPOINT`
+    and friends, and a second place to configure one exporter is a second place
+    for them to disagree. Empty is passed straight through — the exporter's own
+    `endpoint or environ.get(...)` gives exactly the unconfigured behavior, so
+    there is nothing for this row to branch on.
+    """
+
+    service_name: str = "ph"
+    endpoint: str = ""
+
+
+@plugin("session-telemetry-otel", inject=[SESSION_TELEMETRY], config=Config)
+async def apply(ctx: Context, config: Config) -> None:
+    """Register the exporter as a sink, or refuse with a reason."""
+    try:
+        from opentelemetry._logs import SeverityNumber
+        from opentelemetry.sdk._logs import LoggerProvider
+        from opentelemetry.sdk.resources import Resource
+
+        # Inside the guard, because `_pipeline` imports the *other* half of the
+        # extra: a deployment with the SDK but no OTLP exporter refuses here
+        # rather than mounting a sink that ships nowhere.
+        processor = _pipeline(config)
+    except ImportError as error:
+        raise MountRefusal(MISSING) from error
+
+    provider = LoggerProvider(resource=Resource.create({"service.name": config.service_name}))
+    provider.add_log_record_processor(processor)
+    logger = provider.get_logger("ph.session")
+    # Resolved once at mount rather than `SeverityNumber(...)` per record: enum
+    # lookup by value goes through `Enum.__call__`, for a table of four that
+    # cannot change while the row is mounted.
+    severities = {name: SeverityNumber(value) for name, value in SEVERITY.items()}
+
+    def ship(record: SessionTelemetryRecord) -> None:
+        """One post-redaction record, as one OTel log record.
+
+        No `try` here: `SessionTelemetry.record` already wraps every sink call,
+        so a guard at this level could not change any outcome — it would only
+        choose which of two log lines prints, while making the seam's own
+        containment unreachable for the one sink that talks to a network. Sink
+        health is the seam's to own, and it is already where it can see it.
+        """
+        logger.emit(
+            timestamp=record.time * 1_000_000,
+            body=record.body,
+            severity_number=severities[record.severity],
+            severity_text=record.severity,
+            attributes=_flat({"channel": record.channel, **record.attributes}),
+        )
+
+    # Through `add_sink`, never `ctx.on("session-telemetry/record", …)`: the
+    # sink list is fanned out *after* the waterfall settles, so this cannot see
+    # a record the redactors have not finished with. A listener could.
+    ctx.require(SESSION_TELEMETRY).add_sink(ship, scope=ctx)
+    ctx.add_disposer(provider.shutdown, label="telemetry.otel")
+
+    contribute(
+        ctx,
+        Diagnostic(
+            id="telemetry-otel",
+            title="Telemetry export",
+            order=70,
+            read=lambda: [
+                ("sink", "opentelemetry"),
+                ("service.name", config.service_name),
+                ("endpoint", config.endpoint or "from OTEL_* environment"),
+            ],
+        ),
+    )
+
+
+def _pipeline(config: Config) -> Any:  # noqa: ANN401
+    """The OTLP exporter behind a batching processor — the row's one test seam.
+
+    Batching is right in production, where a record per turn must not be a
+    request per turn, and wrong in a test, which has to observe the export
+    before the batch would have flushed. One substitutable hook rather than two
+    (an exporter factory *and* a processor factory) because both existed for
+    this single substitution, and the pair had `apply` importing a class purely
+    to hand it to a one-line helper.
+    """
+    from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter
+    from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
+
+    return BatchLogRecordProcessor(OTLPLogExporter(endpoint=config.endpoint))
+
+
+def _flat(attributes: dict[str, Any]) -> dict[str, Any]:
+    """OTel attributes are scalars; anything else goes as its JSON text.
+
+    Flattened here rather than dropped, because a record's attributes are the
+    part an operator actually queries on — and a nested value silently omitted
+    is a field that looks absent rather than unsupported. The `ph.` prefix is
+    applied here and only here, so the caller hands in `channel` rather than
+    spelling the convention a second time.
+    """
+    return {
+        f"ph.{key}": value if isinstance(value, SCALARS) else dumps(value)
+        for key, value in attributes.items()
+    }