AI-based log analysis tools for Nimble Streamer

We have released gpt-log-ingest, a toolkit for analyzing Nimble Streamer logs with your own AI agent. Ask it to explain messages, investigate incidents, compare activity across time periods, or monitor new log entries.

What you get

• 3,400+ message descriptions: patterns, triggers, explanations, possible causes, and suggested checks.
• Codex and Claude Code skills: a shared workflow for investigating runtime logs.
• Rust and Python watchers: local filtering by severity, grouping of identical records, and suggested catalog matches.
• Configuration templates: log locations, time zones, and reporting preferences.

Log analysis requires no Nimble source code or configuration changes. Your AI client must be installed and have permission to read your logs.

Start analyzing

Clone the repository and launch your agent:

git clone https://github.com/Softvelum/gpt-log-ingest.git
cd gpt-log-ingest
codex
# Or: claude

Provide a directory and a question:

Analyze Nimble logs in /var/log/nimble. Group errors from the last
hour, explain them, and cite evidence of failures affecting live/camera1.

If no log directory is provided or saved, the workflow instructs the agent to ask for one and save it in .local/settings.md when possible. By default, analysis covers nimble.log and nimble-*.log, including relevant rotated files. Access, advertisement, and unit-test logs require separate analysis; the catalog does not cover their distinct formats.

To invoke the skill explicitly:

• Codex: $nimble-logs followed by your question.
• Claude Code: /nimble-logs followed by your question.

Keep the skills in the cloned repository. If instructions are not loaded automatically, ask the agent to follow workflows/analyze-logs.md. Check setup details.

Ask operational questions

Task	Example request
Review errors	“Group errors from the last hour. Show counts and affected streams.”
Investigate an incident	“Build a timeline for live/camera1 between 14:20 and 14:40 today.”
Compare periods	“Compare today’s failures with yesterday’s. Identify new patterns and changes in frequency.”
Explain a message	“Explain this message using the catalog and suggest next checks: …”

You can ask about a pasted message without providing a log directory. Surrounding logs are needed to establish incident context or service impact.

The analysis workflow instructs the agent to:

• Cite timestamps, source locations, and matching catalog descriptions.
• Group repeated messages and report counts for the inspected files and time range.
• Separate observed behavior from possible causes.
• Disclose unmatched messages, missing evidence, and coverage gaps.

These instructions help make findings verifiable and reduce repetitive searching; compliance depends on the agent. Standard log analysis is read-only, and fixes are proposed for your review.

Save preferences

Save these preferences in .local/user-instructions.md: report in English, group
repeated messages, and redact tokens in excerpts.

The workflow instructs the agent to read saved preferences for each task; current requests take precedence. The log time zone and file patterns belong in .local/settings.md. Reports are saved to .local/reports/ by default unless you choose another destination.

Git ignores .local/. The toolkit does not control how your AI client or model provider handles log content.

Watch new events

Specify a duration and starting point:

Watch my Nimble logs for 30 minutes. Start with new lines only.
Use a 10-second status interval. Group repeated errors and report
new failures affecting live/camera1.

To run the Rust watcher directly, build it with a current stable Rust toolchain:

cargo build --release --locked \
  --manifest-path tools/nimble-log-watch/Cargo.toml

tools/nimble-log-watch/target/release/nimble-log-watch \
  --dir /var/log/nimble --levels E \
  --duration-seconds 1800 --status-interval-seconds 10

The Rust watcher reacts to filesystem notifications and rescans files at each status interval to catch missed changes.

The Python alternative polls at a fixed interval:

python3 scripts/nimble_log_watch.py \
  --dir /var/log/nimble --levels E \
  --duration-seconds 1800 --interval-seconds 10

Both examples watch for errors for 30 minutes. Use --levels E,V,D,I for all supported severity codes. The watchers group identical records and suggest catalog entries; the workflow requires the agent to verify matches.

Updates in chat require an active agent session. When the session ends, updates stop, but the watcher process may continue running. The workflow instructs the agent to stop it. The watchers do not provide unattended scheduling or guarantee that every record is captured. Check watcher details.

Additional diagnostics

Two optional toolsets provide checks beyond log analysis:

• whep-check: opens a real WHEP viewer session to check signaling, ICE/DTLS connectivity, and media reception, and reports delivery statistics.
• MPEG-TS ingest diagnostics: collect and analyze evidence of DNS lookups blocking ingest threads and causing UDP socket overflows.

The workflow permits these checks only when you explicitly request them. General log analysis remains the starting point.

Get the toolkit on GitHub and investigate your next Nimble Streamer incident with your AI agent.