opscompanion-observability

OpsCompanion Observability

Use OpsCompanion observability commands for live or recent runtime investigation.

This skill is for:

• current or recent errors
• runtime behavior in a service
• log inspection during debugging
• live tailing while the user works
• trace search for request paths or span names

Do not use opc search for this. opc search is for stored knowledge and memory, not live telemetry.

Action

Choose the command that matches the user's intent:

Search logs

opc --agent codex logs "<query>"

Live tail logs

opc --agent codex logs tail "<query>" --tui

Search traces

opc --agent codex traces "<query>"

Flags

opc logs

Flag	Default	Description
--service	none	Filter by service name; repeatable
--severity	none	Filter by severity; repeatable
--since	24h	Time range: 1h, 6h, 12h, 24h, 3d, 7d, 14d
--mode	keyword	Search mode: keyword or regex
--case-sensitive	off	Enable case-sensitive search
--limit	50	Maximum number of results
--json	off	Output full API response as JSON
--ndjson	off	Output one result object per line

opc logs tail

Flag	Default	Description
--service	none	Filter by service name; repeatable
--severity	none	Filter by severity; repeatable
--mode	keyword	Search mode: keyword or regex
--case-sensitive	off	Enable case-sensitive search
--limit	20	Maximum number of results per poll
--tui	off	Launch the interactive Bubble Tea tail UI

opc logs tail does not accept --since.

opc traces

Flag	Default	Description
--service	none	Filter by service name; repeatable
--since	24h	Time range: 1h, 6h, 12h, 24h, 3d, 7d, 14d
--mode	keyword	Search mode: keyword or regex
--case-sensitive	off	Enable case-sensitive search
--limit	50	Maximum number of results
--json	off	Output full API response as JSON
--ndjson	off	Output one result object per line

Query Strategy

User says	Command to use
"what errors are we seeing in api?"	opc --agent codex logs --service api --severity ERROR
"tail vercel-app while I test this"	opc --agent codex logs tail --service vercel-app --tui
"search for timeout logs in the last hour"	opc --agent codex logs "timeout" --since 1h
"find checkout traces"	opc --agent codex traces "checkout"
"regex for connection reset"	`opc --agent codex logs "connection reset

Prefer the narrowest useful service and severity filters before broad free-text queries.

TUI Guidance

When the user wants to watch a service live, prefer:

opc --agent codex logs tail --service "<service>" --tui

The TUI supports:

• j / k or arrow keys to scroll
• pgup / pgdn for page movement
• g / G for top and bottom
• f to toggle follow mode
• q or Ctrl-C to quit

How to Present Results

• For logs or traces search, summarize the most relevant findings instead of dumping every line.
• Call out recurring services, severities, trace IDs, or obvious failure patterns.
• If the user wants raw machine output, rerun with --json or --ndjson.
• If the issue appears to be historical team knowledge rather than live telemetry, switch to $opscompanion-search.

Error Handling

If an observability command fails with a config error, run $opscompanion-init first.