Observability foundations¶
Target
This page describes intended behaviour or structure. No implementation is claimed unless a section is explicitly marked Current implementation or Evidence.
Filled 2026-10-09
This page (platform-foundations/observability.md) was empty. It now records the Factory's deltas on the shared ConnectSoft observability foundations; the shared guidance itself lives in ConnectSoft.Documentation and in the ConnectSoft.Extensions.Observability, .Telemetry, .Diagnostics.Metrics and .Logging.Serilog libraries.
What the Factory adds¶
| Delta | Requirement |
|---|---|
| Run attribution | Every span, metric and log line carries trusted tenant, project, run, step and attempt identity (ADR-0014); trace id stays diagnostic correlation |
| AI-native trace shape | resolve release → retrieve memory → retrieve knowledge → build context → model call (model, provider, tokens, latency, cost) → tool call (tool, parameters, duration, result) → approval → verification → result |
| Terminal-state coverage | Completed, Failed and Cancelled are all observable; an exception or cancellation that leaves no terminal signal is a defect |
| Metrics | Task and agent success, cost and latency per task, tokens per task, tool failure rate, model fallback rate, human intervention rate, sandbox failures, retrieval quality, evaluation score, backlog age, stuck approvals and leases, unknown effects and usage |
| Content safety | Prompts, retrieval queries, tool arguments and outputs are not logged by default; capture is an explicit, scoped retention setting with redaction |
| Cardinality | Run and tenant identifiers are attributes on traces and logs, not unbounded metric labels |
| Export | The Factory meter and lifecycle metrics must be proven to reach the configured exporter for the selected profile |
| Separation | Telemetry is a projection; the run journal and audit store remain the authoritative records |
Current implementation¶
- OpenTelemetry instrumentation, a Factory meter (
connectsoft.ai.factory.agent) with lifecycle metrics, Serilog enrichers and Audit.NET registration exist in the libraries and the agent host template. - The retrieval sample logs the raw query text and sets it as an activity tag; the lifecycle library records success/failure metrics but no run identity exists to attribute them.
- No dashboards, alert rules, SLOs or export verification exist for the Factory.