Telemetry and Metrics
Relevant source files
The following files were used as context for generating this wiki page:
The Telemetry and Metrics system in OpenCode Swarm provides the infrastructure for tracking agent behavior, resource consumption, and project progress. It enables the orchestrator to monitor the health of the multi-agent swarm, enforce performance constraints, and gather retrospective data for continuous improvement.
This system is integrated directly into the agent lifecycle, capturing events ranging from budget updates and tool calls to complex failure modes like retry loops and plan drift. By persisting these metrics in structured formats like JSONL, the system ensures that both automated monitors and human developers can audit the swarm's performance.
Architecture and Data Flow
The telemetry system operates as a centralized event bus that agents and hooks use to report their internal state. The telemetry object acts as the primary interface, providing specialized methods for different event types.
Primary Telemetry Interface
The telemetry module exposes several key methods for logging swarm activities:
budgetUpdated: Tracks token consumption and budget percentages for specific sessions.event: Records generic swarm events with metadata.error: Logs failure conditions with associated context.
Sources: src/state/telemetry.ts:1-20, src/hooks/system-enhancer.ts:1330-1334
Data Flow Diagram
The following diagram illustrates how telemetry data flows from subagents through the orchestrator to the persistence layer.
Phase-Level Metrics and Retrospectives
At the conclusion of each project phase, the Architect agent is responsible for aggregating performance data into a permanent record. This is handled via the PHASE-WRAP mode and Rule 10 of the Architect's protocol.
Metric Categories
The system tracks a specific set of indicators to evaluate phase health:
- Efficiency: Total tool calls and task count.
- Reliability: Coder revisions, reviewer rejections, and test failures.
- Security: Security findings detected during the phase.
- Complexity: Integration issues and qualitative task complexity.
Sources: src/agents/architect.ts:321-325
Retrospective Tracking Table
| Metric Name | Source Agent/System | Description |
|---|---|---|
total_tool_calls | Swarm State Aggregates | Count of all tool executions across all subagents. |
coder_revisions | Coder Agent | Number of times a coder had to retry a task after a gate failure. |
reviewer_rejections | Reviewer Agent | Count of negative verdicts emitted by the reviewer. |
test_failures | Test Engineer | Number of failed verification or adversarial test runs. |
security_findings | SAST/Secret Scan | Vulnerabilities or secrets detected in the phase code changes. |
Sources: src/agents/architect.ts:322-324, src/hooks/system-enhancer.ts:1210-1215
Budget Monitoring and Resource Constraints
Telemetry is heavily utilized by the System Enhancer Hook to prevent context window overflow and manage token budgets.
Context Budgeting
The system monitors token usage against defined thresholds:
- Warning Threshold: Typically 70% of the model's token limit.
- Critical Threshold: Typically 90% of the model's limit.
When these thresholds are crossed, the telemetry system triggers a budgetUpdated event, which is then surfaced to the Architect agent to prompt context triage or compaction.
Sources: src/hooks/system-enhancer.ts:1315-1340
Event Persistence
The system uses the meta.summary convention to provide human-readable descriptions of state updates in events.jsonl. This ensures that even low-level telemetry events can be interpreted in the context of the project plan.
{
"taskId": "2.3",
"event": "budgetUpdated",
"budgetPct": 72.5,
"agent": "architect",
"meta.summary": "Session approaching context limit — triage required"
}
Sources: src/agents/architect.ts:303-310, src/agents/coder.ts:353-360
Analysis and Complexity Indicators
The Explorer agent contributes to the telemetry ecosystem by providing factual metrics about the codebase structure and complexity. These indicators are used by the Architect to adjust task sizes and risk assessments.
Structural Complexity Indicators
- High Cyclomatic Complexity: Detected in deep nesting or complex control flows.
- Large Files: Flagged when a file exceeds 500 lines.
- Export Density: High number of exported symbols in a single module.
- Inheritance Depth: Complexity in type or class hierarchies.
Sources: src/agents/explorer.ts:34-45, src/agents/explorer-consumer-contract.test.ts:60-65
Diagnostic Events
The system identifies and logs specific anti-patterns and failure loops as diagnostic telemetry.
Critical Diagnostic Triggers
- Architect Loop Detected: Triggered when the Architect enters a logic impasse for the 3rd time.
- Coder Retry Circuit Breaker: Triggered after 3 consecutive implementations fail the QA gates.
- Baseline Drift: Logged when a plan is mutated without explicit Critic approval.
- Manipulation Detected: Logged by the Critic when pressure language is identified in orchestrator delegations.
Sources: src/agents/architect.ts:245, src/agents/critic.ts:110-125, tests/unit/agents/agent-audit-p2.test.ts:40-50
Summary
The Telemetry and Metrics system provides the observability layer necessary for autonomous swarm operation. By combining granular token tracking with high-level phase retrospectives and structural code analysis, it allows the OpenCode Swarm to maintain high quality and security standards while operating within the technical constraints of Large Language Models.