Events and observability
Event stream
Agentweaver records each run as an ordered, durable stream of facts. The stream lets clients reconstruct timelines, graphs, approvals, status, and diagnostics after a restart or reconnection.
Each event has a run-local cursor. The normal append path obtains its sequence from durable storage before local delivery; subscribers resume from their last observed sequence. See the durable write-through and replay sequence.
Production uses EfRunEventStream to write events to PostgreSQL and poll by cursor across replicas. Local development uses SqliteRunEventStream. Process-local channels provide local delivery only; they are not the production cross-replica transport.
Telemetry
When APPLICATIONINSIGHTS_CONNECTION_STRING is configured, the API calls .UseAzureMonitor() to export OpenTelemetry data to Azure Monitor. The runtime also records explicit Agentweaver counters and histograms for operational metrics.
Model turns emit activities and agentweaver.token.usage metrics. Despite its name, that counter measures nano-AIU cost, not token count. Project metrics and run traces query telemetry when available; Azure Monitor export is separate from durable operational-event persistence.
Each provider agent turn also emits an agent.runtime_context durable event. It reports only run/project correlation, scalar sizes for the assembled base prompt, run context, assigned-skill block, separators, task, and provider declarations, plus a fixed skill delivery mode and ceil(totalCharacters / 4) planning estimate. Its section sizes always sum to totalCharacters. It is separate from memory.context_composition, which records the #1241 structured-context selection and omission results rather than prompt sizing.
Copilot SDK turns also emit agent.system_prompt from the same composition evidence. This includes the AgentHost-backed operator assistant path, for both GitHub Copilot and BYOK, as well as coordinator/project turns. The durable event contains the same bounded metadata plus callableMemoryGuidanceIncluded, which records whether the actual prompt-composition branch added callable project-memory guidance. Its provider field is only the canonical copilot or byok token; provider/configuration identifiers, types, model names, endpoints, prompt text and hashes, task/skill/charter content, tool names or schemas, credentials, PII, and unknown fields are never part of the public contract. REST and SSE rebuild a strict allowlisted projection, including for historical rows.
Operational use
Use the run stream to explain a specific run. Use GET /api/projects/{id}/metrics for project performance and GET /api/metrics/runs/{runId}/traces for trace details. Use cluster diagnostics for runtime dependencies and sandbox inventory.
Source
apps/Agentweaver.Api/Infrastructure/EfRunEventStream.csapps/Agentweaver.Api/Infrastructure/SqliteRunEventStream.csapps/Agentweaver.Api/Infrastructure/AzureMonitorBootstrap.csapps/Agentweaver.Api/Infrastructure/AgentWeaverMetrics.cspackages/Agentweaver.AgentRuntime/CopilotAIAgent.cs
Visual model
Durable events
Structured source · Editable draw.io
Related reading
Diagram details and constraints
| Element | Contract |
|---|---|
| title | Durable allocation, then cursor replay |
| takeaway | Cross-replica delivery polls shared rows; local notifications are not a distributed bus. |
| RecordNext | RecordNext |
| RecordNext | Request sequence allocation |
| RecordNext | Append with Sequence = 0 |
| EF append | EF append |
| EF append | ReadCommitted + advisory lock |
| EF append | Serialize allocation per run |
| RunEvents | RunEvents |
| RunEvents | MAX+1 / insert / commit |
| RunEvents | Return assigned sequence |
| Local history | Local history |
| Local history | Updated after durable ack |
| Local history | Notify only local waiters |
| Web replica A | Web replica A |
| Web replica A | Read Sequence > lastSeen |
| Web replica A | 250 ms delay only when empty |
| Browser watcher | Browser watcher |
| Browser watcher | SSE sequence IDs |
| Browser watcher | Remember last event cursor |
| Reconnect cursor | Reconnect cursor |
| Reconnect cursor | Last-Event-ID |
| Reconnect cursor | Not tied to original web pod |
| Web replica B | Web replica B |
| Web replica B | Ordered replay and live tail |
| Web replica B | Read same shared RunEvents |
| Resumed watcher | Resumed watcher |
| Resumed watcher | Receive rows after cursor |
| Resumed watcher | No PostgreSQL NOTIFY required |
| arrow-1 | append |
| arrow-2 | commit |
| arrow-3 | ack |
| arrow-4 | poll |
| arrow-5 | SSE |
| arrow-6 | resume |
| note-0 | Rows: write-through / live delivery / reconnect on another replica. |
| note-1 | Explicit historic sequence: identical content is idempotent; conflicts fail. |
| note-2 | SQL commits before local history update; polling reads the shared table. |
| notes | Rows: write-through / live delivery / reconnect on another replica.; Explicit historic sequence: identical content is idempotent; conflicts fail.; SQL commits before local history update; polling reads the shared table. |