arthai-marketplace

/otel-setup

Configure OTEL observability — starts the local Arth Intelligence Docker stack (or points at a remote endpoint) and writes the env vars.

Synopsis

/otel-setup

When to use it

Quickstart

/otel-setup

What you’ll see: a check of your current config, then two questions — where to send traces (Cloud / Local / Custom), and how much telemetry to collect (Native-only vs Full, see below) — after which the skill writes the env vars (globally by default, so every project on the machine emits telemetry), starts the local Docker stack if you chose Local, and verifies end-to-end by sending a test span. Restart your Claude Code session and your activity appears on the dashboard.

No toolkit? The same setup ships in the Arth CLI as arth otel-setup. Install the Arth CLI first — it’s gated by your GitHub repo access (no public package).

Examples

/otel-setup        # the only form — the skill takes no arguments

Typical runs:

What it does

  1. Detects current state — reads .claude/settings.local.json and classifies it: not configured (full setup), fully configured (offers to reconfigure or just re-verify), or partially configured — the silent-failure case, where it shows exactly which keys are missing and offers repair-in-place, full reconfigure, or cancel — a user-confirmation checkpoint.
  2. Asks question 1 — where should traces go? A user-confirmation checkpoint with three options:
    • Cloud — Arth Intelligence (traces go to ingest.getarth.ai; the dashboard itself lives at app.getarth.ai, where you also get your Arth project key)
    • Local — a local Docker stack: it checks Docker is running, writes ~/.arthai/docker-compose.yml (Postgres + the Arth Intelligence engine + a watchtower auto-updater, all with restart: unless-stopped), starts it, and waits for the engine health check
    • Custom — your own OTLP endpoint (Honeycomb, Datadog, Jaeger, …); it asks for the URL and any auth headers
  3. Asks question 2 — how much telemetry? A user-confirmation checkpoint between two depths:
    • Native-only (default) — just Claude Code’s own OTEL: cost by model, cost by owner, tokens. Written to the global ~/.claude/settings.json so every project on the machine emits it, including non-toolkit repos and sessions launched outside a shell.
    • Full — everything in Native-only, plus the toolkit’s otel-telemetry hook: skill/agent attribution (skill names, lines edited), experiment auto-tags, a richer agent DAG. Choose this only if you’re running the toolkit in this repo and want that extra detail.
  4. Decides scope — the native block is written to the global ~/.claude/settings.json by default (every project on the machine), so this normally isn’t asked. It only prompts for an override if you want this one repo pointed somewhere different, via <repo>/.claude/settings.local.json.
  5. Offers “Explain this session” inline (optional, non-experimental). After the stack is healthy, /otel-setup (and arth otel-setup) ask whether to enable the dashboard’s “Explain this session” AI summary — pick any provider (Anthropic, OpenAI, Gemini, Bedrock) including free local Ollama / LM Studio (LM Studio auto-detects the loaded model, e.g. qwen). It’s optional; telemetry works without it. The experimental Cloud Orchestrator (calibrate/plan a repo) is configured separately — run /cloud-setup (or arth cloud-setup); it’s Claude-only and needs a GitHub token + license.
  6. Writes the env vars — merges the six required OTEL keys into the chosen target without overwriting your other settings, then asks one yes/no follow-up about auto-tagging sessions for arth’s /experiments page (default: on).
  7. Verifies end-to-end — re-reads the config and asserts all six keys landed, checks for a stale .claude/.arth-otel.env that could silently divert spans (offering one-click reconciliation), sends a test span to the endpoint the hook will actually use, and checks your existing containers will auto-restart after a reboot (offering a one-line migration if not).
  8. Finishes — writes the ~/.arthai/otel-configured marker so you aren’t re-prompted, and tells you to restart your Claude Code session so traces start flowing.

Output & artifacts

Troubleshooting

Problem Fix
/otel-setup requires jq brew install jq (macOS) or apt-get install jq (Linux), then re-run
Docker is not running Start Docker Desktop and re-run /otel-setup
Arth Intelligence failed to start docker compose -f ~/.arthai/docker-compose.yml logs to see why
Sessions appear but cost columns are empty The partial-config silent failure — re-run /otel-setup and choose Repair in place; verification confirms all six keys
415 Unsupported Media Type during verify Protocol mismatch — the repair path rewrites the protocol key; also check .claude/.arth-otel.env for a stale value
DIVERGENCE DETECTED between config sources Accept the offered reconciliation — it rewrites .arth-otel.env to match settings.local.json
Endpoint unreachable in the smoke test Local: start the engine (docker compose -f ~/.arthai/docker-compose.yml up -d); remote: check connectivity and the endpoint URL
Dashboard dark after a Mac reboot Legacy compose file without restart policies — run the printed docker update --restart unless-stopped ... one-liner
“Explain this session” shows “needs an LLM key — run /cloud-setup“ No LLM key configured. Run /cloud-setup (or arth cloud-setup), opt into Explain, and provide a key — it’s saved to ~/.arthai/.env and survives image updates. Free option: local Ollama.

Never run docker compose -f ~/.arthai/docker-compose.yml down -v — the -v erases all session data. Plain down is safe; updates are automatic via watchtower.