By SPDX-FileCopyrightText: 2026 Hemalatha Madeswaran hemalathamadeswaran@gmail.com
SPDX-License-Identifier: AGPL-3.0-only
name: observal-ops command: observal description: View traces, spans, metrics, feedback, and telemetry health for Observal agents and MCPs. Use when the user wants to see recent traces, check metrics, view top items, submit ratings, or diagnose telemetry pipeline issues. version: 2.0.0 owner: observal
Observal Ops: Observability and Telemetry
Critical Rules
- EXECUTE commands: run them in your shell. Set timeout to 60 seconds.
- Pass
--output jsonon every command for stable, machine-readable output. - When in doubt about a flag, run
<command> --helpfirst.
Procedure: Observe
observal ops overview --output json
observal ops metrics ITEM_NAME --type agent --output json
observal ops metrics ITEM_NAME --type mcp --watch
observal ops top --type agent --output json
observal ops top --type mcp --output json
observal ops traces --limit 20 --output json
observal ops traces --platform kiro --days 7 --output json
observal ops traces --turn --limit 5
observal ops traces --span --limit 3
observal ops spans TRACE_ID --output json
observal ops feedback ITEM_NAME --type mcp --output json
Procedure: Rate Component
observal ops rate MCP_NAME --stars 5 --type mcp --comment 'Worked great'
observal ops rate AGENT_NAME --stars 4 --type agent
--stars (1-5) and --type are required. --comment is optional.
Procedure: Telemetry Health
observal ops telemetry status
observal ops telemetry test
status is the reliable check: it queries server event counts and local SQLite buffer. test may return 404 on newer servers (legacy endpoint). If status shows events flowing, telemetry is healthy.
Diagnosis: status OK → healthy. No events → check observal auth status. Server reachable but no events → hooks not installed, suggest observal doctor.
Output Contract
- One sentence stating intent.
- The exact command in a fenced code block.
- The result: success / specific error.
- The next action, or "done".