observal ops

Inspect current session telemetry, Registry usage, feedback, logs, and Agent insight reports. All 11 supported workflows provide table and JSON output. Finite commands return one JSON document. Streaming commands return JSON Lines, one compact object per update. The dead ops metrics, legacy ops spans, and synthetic ops telemetry test commands have been removed. Current trace detail comes from ops traces --span through the Sessions API.

Commands

Command	Purpose
`top`	Show the most-downloaded MCPs or Agents
`rate`	Submit Registry feedback
`rate-update`	Update the caller’s feedback
`rate-delete`	Delete the caller’s feedback
`feedback`	Show aggregate and individual feedback
`traces`	List current sessions or fetch their details
`telemetry status`	Check server event counts and local outbox health
`logs`	Follow local or remote development logs
`insights list`	List Agent insight reports
`insights show`	Show an insight report or section
`insights generate`	Generate an insight report

Top Registry items

observal ops top --type mcp --output json
observal ops top --type agent --output json

JSON returns the direct ranking array. MCP ranking is currently server-limited to five results; Agent ranking is currently server-limited to six.

Feedback

Submit feedback:

observal ops rate alice/postgres --type mcp --stars 5 --comment 'Reliable' --output json

Update feedback:

observal ops rate-update alice/postgres --type mcp --stars 4 --output json
observal ops rate-update alice/postgres --type mcp --comment 'Updated review' --anonymous --output json

Delete feedback:

observal ops rate-delete alice/postgres --type mcp --yes --output json

View feedback:

observal ops feedback alice/postgres --type mcp --output json

Feedback types are mcp, agent, skill, hook, prompt, and sandbox. Stars accept 1 through 5 and comments accept at most 5,000 characters. Rate and update return the direct feedback object. Delete currently returns an empty object. JSON deletion requires --yes; human mode prompts without it. Feedback JSON combines aggregate and individual results:

{
  "summary": {
    "average_rating": 4.5,
    "total_reviews": 2
  },
  "reviews": []
}

Traces and current session details

traces uses the current REST session pipeline:

Summary list: GET /api/v1/sessions
Turn or span detail: GET /api/v1/sessions/{session_id}

observal ops traces --limit 20 --output json
observal ops traces --platform kiro --days 7 --output json
observal ops traces --turn --limit 5 --output json
observal ops traces --span --limit 3 --output json

--platform accepts a registered harness. --days accepts 1 through 365 and --limit accepts 1 through 200. Default JSON returns the direct session summary array. Turn and span JSON fetch every selected session detail:

{
  "view": "span",
  "items": [
    {
      "summary": {
        "session_id": "session-id"
      },
      "detail": {
        "events": []
      }
    }
  ]
}

--turn renders prompts and tool calls. --span includes full assistant and tool-result detail. Detail failures are surfaced rather than replaced with incomplete summaries.

Telemetry status

observal ops telemetry status --output json

The server portion requires administrator access. The result combines recent server counts and local durable outbox state:

{
  "server": {
    "status": "ok",
    "tool_call_events": 8,
    "agent_interaction_events": 5
  },
  "outbox": {
    "available": true,
    "pending": 0,
    "failed": 0,
    "total": 0,
    "bytes": 0
  }
}

A local outbox read failure remains visible as available: false with a safe error type. The removed synthetic test command is not part of the current JSONL session ingestion architecture.

Logs

Read a finite local tail:

observal ops logs --level WARNING --lines 50 --no-follow --output json

Follow local logs:

observal ops logs --level INFO --output json

Follow remote server logs with administrator access:

observal ops logs --remote --level WARNING --output json

Valid levels are TRACE, DEBUG, INFO, WARNING, ERROR, and CRITICAL. --filter performs case-insensitive text filtering. --lines must be zero or greater. JSON mode emits JSON Lines. Local records have this shape:

{"event":"log","source":"local","level":"ERROR","line":"raw log line"}

Remote records wrap the structured server event:

{"event":"log","source":"remote","log":{"level":"ERROR","event":"request failed"}}

Malformed remote records, inaccessible files, HTTP errors, timeouts, and connection failures use categorized exits. Access tokens are never emitted. Log content itself may contain sensitive application data and must be handled accordingly.

Agent insights

List reports:

observal ops insights list alice/reviewer --output json

Show a report or one section:

observal ops insights show alice/reviewer latest --output json
observal ops insights show alice/reviewer latest --section suggestions --output json

A section request returns report_id, section, and that section’s data rather than the entire report. Generate once:

observal ops insights generate alice/reviewer --period 14 --output json

Generate and wait with JSON Lines progress:

observal ops insights generate alice/reviewer --period 14 --wait --output json

{"event":"queued","report":{"id":"report-id","status":"pending"}}
{"event":"progress","report":{"id":"report-id","status":"running","progress_percent":50}}
{"event":"progress","report":{"id":"report-id","status":"completed","progress_percent":100}}

Periods accept 1 through 365 days. --version and --compare require semantic versions. Invalid report rows, ambiguous prefixes, missing reports, unknown sections, unavailable providers, generation failures, and wait timeouts use categorized errors. Report sections include:

at_a_glance
what_they_work_on
interaction_style
usage_patterns
what_works
friction_analysis
suggestions
usage_cost_analysis
version_comparison
regression_detection
on_the_horizon
fun_ending

Exit codes

Code	Meaning
3	Authentication required or failed
4	Telemetry, log, session, or insight permission denied
5	Registry item, report, session, or local log file not found
6	Ambiguous report or Registry reference
7	Invalid type, harness, section, period, version, comment, or missing confirmation
8	Rate limit reached
9	Server, provider, stream, outbox, or local log dependency unavailable
10	CLI and server version mismatch

observal inbox: completed insight notifications
observal agent: apply insight recommendations
observal registry: inspect rated or recommended components
Debug Agent failures

Getting Started

Core Concepts

Use Cases

CLI Reference

Self-Hosting

Integrations

Reference

Security

Architecture Decisions

Contributing

Commands

Top Registry items

Feedback

Traces and current session details

Telemetry status

Logs

Agent insights

Exit codes

​Commands

​Top Registry items

​Feedback

​Traces and current session details

​Telemetry status

​Logs

​Agent insights

​Exit codes

​Related

Commands

Top Registry items

Feedback

Traces and current session details

Telemetry status

Logs

Agent insights

Exit codes

Related