# Iii Observability

OpenTelemetry-backed tracing, structured logs, metrics with rollups, alerts, sampling...

- Repository: https://github.com/iii-hq/iii (18876 stars)
- Category: Engineering
- License: see repository
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add iii-hq/iii --skill iii-observability -g -a claude-code -y`
Codex: `npx skills add iii-hq/iii --skill iii-observability -g -a codex -y`
Cursor: `npx skills add iii-hq/iii --skill iii-observability -g -a cursor -y`
Gemini CLI: `npx skills add iii-hq/iii --skill iii-observability -g -a gemini-cli -y`

## Description

OpenTelemetry-backed tracing, structured logs, metrics with rollups, alerts, sampling, and baggage for the engine, emit and query telemetry through `engine::*` functions and react to logs with a `log` trigger.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# iii-observability

The `iii-observability` worker provides OpenTelemetry-backed observability for the iii engine:
distributed tracing, structured logs, metrics with rollups, alert rules, sampling configuration, and
baggage propagation. Every surface is a callable `engine::*` function, plus a single `log` reactive
trigger that fires on every ingested log entry. Functions span nine sub-namespaces, emit, query
stored telemetry, inspect configuration, and propagate context.

The worker is on by default (`enabled: true`). When disabled, the emit and read functions still
register but become no-ops and the trigger never fires. Core config:
`service_name`/`service_version`/`service_namespace` (OTel resource attributes), `exporter`
(`memory` | `otlp` | `both`), `endpoint` (OTLP collector URL, default `http://localhost:4317`),
`sampling_ratio` (`0.0`, `1.0`), `memory_max_spans`, and per-pillar toggles/limits
(`metrics_enabled`, `logs_enabled`, retention and count caps). Most fields accept `OTEL_*` env
overrides. The in-memory query functions (`logs`, `traces`) require the `memory` or `both` exporter.

Traces and metrics use OTLP/gRPC by default; `https://` endpoints enable TLS and `http://` endpoints
use cleartext. Set `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf` to use OTLP/HTTP protobuf for traces
and metrics, or use `OTEL_EXPORTER_OTLP_TRACES_PROTOCOL` / `OTEL_EXPORTER_OTLP_METRICS_PROTOCOL` for
signal-specific overrides. The HTTP/protobuf path is appended automatically (`/v1/traces`,
`/v1/metrics`) when the configured endpoint is a base collector URL. Logs export over OTLP/HTTP to
`/v1/logs`.

The rest: https://github.com/iii-hq/iii/blob/HEAD/engine/src/workers/observability/skills/SKILL.md