# iii-observability

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.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 195 installs · ★ 18938 repo stars
- Author: iii-hq
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/iii-hq/iii/tree/HEAD/engine/src/workers/observability/skills/SKILL.md
- Updated: 2026-11-09
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/iii-observability

## What it 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.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add iii-hq/iii --skill iii-observability -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/skills/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/skills/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add iii-hq/iii --skill iii-observability -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/skills/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add iii-hq/iii --skill iii-observability -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/skills/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install iii-hq/iii engine/src/workers/observability/skills
```

2. **Manually: put the files in place**
- File: `.github/skills/skills/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add iii-hq/iii --skill iii-observability -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/iii-hq/iii --path engine/src/workers/observability/skills
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/skills/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add iii-hq/iii --skill iii-observability -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/iii-hq/iii/tree/HEAD/engine/src/workers/observability/skills/SKILL.md

## When to use it
- 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
- Log an error with `user_id` attribute via `engine::log::error`
- Show all logs from the last hour at `warn` level or above
- Group spans by `http.status_code` and return counts per group

## Similar
- [observability-and-instrumentation](https://affpapa.org/en/nevibecode/skills/observability-and-instrumentation.md) — skill · 70700 installs
- [agent-observability](https://affpapa.org/en/nevibecode/skills/agent-observability.md) — skill · 373 installs
- [opentelemetry](https://affpapa.org/en/nevibecode/skills/claude-mpm-team-opentelemetry.md) — skill · 655 installs
- [opentelemetry-net-instrumentation](https://affpapa.org/en/nevibecode/skills/opentelemetry-net-instrumentation.md) — skill · 442 installs
- [monitoring-observability](https://affpapa.org/en/nevibecode/skills/travisjneuman-monitoring-observability.md) — skill · 146 installs
- [Observability taste](https://affpapa.org/en/nevibecode/prompts/observability-taste.md) — prompt · ★ 178201 repo stars

From the same set: [iii-hq/iii](https://affpapa.org/en/nevibecode/by/iii-hq/iii.md) — 8 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
