iii-observability — Claude Code skill: OpenTelemetry tracing and logs
The iii-observability skill gives the iii engine tracing, structured logs, metrics with rollups, alerts, and sampling via OpenTelemetry. Call engine::* functions to emit and query telemetry; bind a log trigger to react to every entry.
no license 195 installs ★ 18,938 updated 2026-11-09
npx skills add iii-hq/iii --skill iii-observability -a claude-codeWhat iii-observability does
Nine namespaces inside: engine::log::* emits entries by level (info, warn, error), engine::logs::list reads stored logs filtered by time and trace, engine::traces::* returns spans as a list, tree, or grouped by attribute, engine::metrics::list and engine::rollups::list show metrics and aggregates over one-minute, five-minute, or one-hour windows. engine::baggage::* manages OpenTelemetry baggage, engine::health::check and engine::alerts::* inspect engine state and alert rules.
Data flows to a collector via OTLP/gRPC (endpoint, defaults to http://localhost:4317) or stays in memory (exporter: memory or both). Read functions work only with memory or both. TLS turns on automatically for https://; for HTTP/protobuf set OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf. Collector headers go in OTEL_EXPORTER_OTLP_HEADERS or separately for traces, metrics, and logs.
The log trigger runs a function on every entry in the log pipeline. Set level: error to catch only errors, or omit it to receive everything. The handler's return value is ignored; invocations spawn asynchronously.
What it helps with
- emit structured logs from a function without calling an external collector
- run a handler on every log entry in real time
- read stored spans and metrics filtered by attributes and time
- propagate OpenTelemetry baggage across calls
- inspect engine state and alert rules operationally
Example prompts for the agent
- Log an error with
user_idattribute viaengine::log::error - Show all logs from the last hour at
warnlevel or above - Group spans by
http.status_codeand return counts per group
How to install iii-observability
1Skills CLI (Vercel)
npx skills add iii-hq/iii --skill iii-observability -a claude-code2Manually: put the files in place
~/.claude/skills/skills/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/skills/
1Skills CLI (Vercel)
npx skills add iii-hq/iii --skill iii-observability -a codex2Manually: put the files in place
.agents/skills/skills/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add iii-hq/iii --skill iii-observability -a cursor2Manually: put the files in place
.cursor/skills/skills/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install iii-hq/iii engine/src/workers/observability/skills2Manually: put the files in place
.github/skills/skills/SKILL.md1Skills CLI (Vercel)
npx skills add iii-hq/iii --skill iii-observability -a gemini-cli2Platform CLI
gemini skills install https://github.com/iii-hq/iii --path engine/src/workers/observability/skillsManually: put the files in place
.devin/skills/skills/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add iii-hq/iii --skill iii-observability -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about iii-observability
How to install iii-observability in Claude Code?
Run npx skills add iii-hq/iii --skill iii-observability -a claude-code, then npx skills add iii-hq/iii --skill skills -a claude-code and open ~/.claude/skills/skills/SKILL.md.
What does iii-observability do?
The skill adds tracing, logs, metrics, and alerts to the iii engine via OpenTelemetry. Functions engine::* emit and query telemetry; a log trigger reacts to every entry.
Why do read functions return nothing?
Functions like engine::logs::list and engine::traces::* only work when exporter is set to memory or both. With otlp the data lives in your collector and cannot be queried directly.