Observability & Telemetry
Relevant source files
The following files were used as context for generating this wiki page:
Observability in Cogmo is designed to provide high-level visibility into agentic loops, system health, and self-evolution events. The system focuses on tracking the "reasoning" and execution steps of the agent, ensuring that long-running Node.js processes are both resilient and auditable. It includes specialized logging for tool usage, evolution audit logs, and status reporting via the primary Telegram interface.
The telemetry infrastructure supports multi-tier monitoring, ranging from simple health checks to detailed lineage tracing for self-evolution and coding delegation tasks. This ensures that the single technical user has full control and oversight over their self-hosted infrastructure.
Sources: README.md:12-16, CLAUDE.md:12-16, design/evolution.md:96-100
System Health & Liveness
Cogmo exposes a dedicated endpoint for monitoring the operational status of the agent runtime. This is critical for self-hosted deployments using Docker or systemd.
- Liveness Probe: The system exposes a
GET /healthendpoint on port 9090. - Infrastructure Connectivity: The setup wizard validates connectivity to core dependencies like PostgreSQL, Redis, Inngest, and Hindsight before the system starts.
Sources: README.md:46-48, README.md:73-75
Evolution Audit Log
The self-evolution system utilizes an append-only audit log to track how the agent learns from conversations. This provides a durable record of instruction evolution, steering rule graduations, and memory extractions.
Data Model: evolution_events
The evolution_events table serves as the primary data store for observability into the agent's learning process.
| Column | Type | Description |
|---|---|---|
id | UUIDv7 PK | Unique identifier for the event. |
conversation_id | UUID | Foreign key to the conversation being observed. |
user_id | UUID | Denormalized user ID for fast digest lookups. |
triggered_by | Enum | Source of the evolution: idle or manual. |
payload | JSONB | Structured ObserverResult including correction and memory stats. |
created_at | TIMESTAMPTZ | Timestamp of the evolution fire. |
Sources: design/evolution.md:107-124
Telemetry Flow: Manual vs. Autonomous Evolution
The following diagram illustrates how observability data is captured during both autonomous (idle-triggered) and manual (/reflect) evolution events.
The system captures durationMs to monitor extraction latency, allowing users to see reasoning traces and performance metrics for each learning cycle.
Sources: design/evolution.md:131-150, design/evolution.md:175-180
Coding & Task Progress
For autonomous coding tasks, the system provides detailed telemetry regarding tool usage, token consumption, and execution phases. This data is formatted for user consumption through progress subscribers.
Progress Metadata
The system tracks several dimensions of progress for coding delegation:
- Phases:
planning,executing,awaiting_approval, andfailed. - Token Metrics: Tracks both
inputandoutputtokens to provide cost and usage transparency. - Activity Line: Captures specific tool results (e.g., "Edit ✓ — wrote foo.ts") as they happen.
Sources: src/agent/coding/progress-format.test.ts:5-40
Tool Call Telemetry
Each tool invocation is observed and recorded with its status.
MCP Observability & Safety
Model Context Protocol (MCP) integrations include specialized telemetry to handle the non-deterministic nature of third-party servers.
- Connection Monitoring: Tracks
last_connected_atandlast_errorfor every configured MCP server. - Schema Pinning: The system hashes tool schemas (
schema_hash). Any change triggers a "needs_reapproval" status, acting as a telemetry signal for potential "schema rug-pull" attacks. - Timeout Tracking: A hard 30s timeout is enforced per call to detect hanging tools, with failures surfaced directly in the agent loop.
Sources: design/integrations/mcp.md:104-115, design/integrations/mcp.md:188-195
Logging & Traceability Rules
Cogmo enforces strict logging and error-handling patterns to ensure system state remains traceable.
- Conventional Commits: The project uses Conventional Commits to drive automated semantic releases and changelog generation.
- Lineage Tracing: Mandatory for self-evolution; every change must be traceable back to its origin (e.g., which conversation led to a specific steering rule).
- JSONB Validation: All telemetry stored in JSONB columns must pass Zod schema enforcement on both read and write to prevent silent data corruption.
Sources: CLAUDE.md:144-150, design/evolution.md:84-85, design/testing.md:46-52
Observability & Telemetry in Cogmo is not merely for debugging but is a core component of the "self-evolution" loop. By treating learning events and tool executions as first-class observable data, the system provides the transparency necessary for a user to trust and manage an autonomous personal agent.