observal-ops

# Observal Ops: Observability and Telemetry ## Critical Rules 1. **EXECUTE commands**: run them in your shell. Set timeout to 60 seconds. 2. **Pass `--output json`** on every command for stable, machine-readable output. 3. **When in doubt about a flag, run `<command> --help` first.** --- ## Procedure: Observe ```bash 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 ```bash 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 ```bash 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 `observ...