skill CX Codex

otel-ruby — Claude Code skill: OpenTelemetry setup

Q: How do I install otel-ruby in Claude Code?

Run `npx skills add ollygarden/opentelemetry-agent-skills --skill otel-ruby -a claude-code`. The skill file is available at `~/.claude/skills/otel-ruby/SKILL.md`.

Guides an agent through OpenTelemetry setup and troubleshooting in Ruby services. Use it for tracing, experimental metrics and logs, or library instrumentation.

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓

npx skills add ollygarden/opentelemetry-agent-skills --skill otel-ruby -a claude-code

Open on GitHub

What otel-ruby does

The skill directs the agent to task-specific references for gem installation, OpenTelemetry::SDK.configure, manual signals, context propagation, and testing emitted telemetry. Other guides cover contrib instrumentation for Rails, Rack, Sinatra, HTTP clients, databases, jobs, and messaging, plus performance tuning and upgrades.

Ruby tracing uses stable API and SDK gems, while metrics and logs remain experimental. Bundler must resolve each gem independently, and changes to Gemfile.lock need review; matching version numbers across signals or contrib gems cannot be assumed. That matters during upgrades, where compatibility depends on the individual gem.

What it helps with

configure OpenTelemetry::SDK.configure in a Ruby service
add manual traces and context propagation
choose contrib instrumentation for Rails or Sidekiq
troubleshoot Ruby OpenTelemetry metrics and logs
review gem versions and upgrade changes

Example prompts for the agent

Set up OpenTelemetry SDK for this Ruby service and review Gemfile.lock.
Add manual tracing and context propagation to this application.
Choose and configure OpenTelemetry instrumentation for Rails and Sidekiq.

How to install otel-ruby

1Skills CLI (Vercel)

npx skills add ollygarden/opentelemetry-agent-skills --skill otel-ruby -a claude-code

2Manually: put the files in place

~/.claude/skills/otel-ruby/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/otel-ruby/

1Skills CLI (Vercel)

npx skills add ollygarden/opentelemetry-agent-skills --skill otel-ruby -a codex

2Manually: put the files in place

.agents/skills/otel-ruby/SKILL.md

For all projects use ~/.agents/skills/

1Skills CLI (Vercel)

npx skills add ollygarden/opentelemetry-agent-skills --skill otel-ruby -a cursor

2Manually: put the files in place

.cursor/skills/otel-ruby/SKILL.md

Cursor also reads .agents/skills/ and .claude/skills/

1GitHub CLI

gh skill install ollygarden/opentelemetry-agent-skills otel-ruby

2Manually: put the files in place

.github/skills/otel-ruby/SKILL.md

1Skills CLI (Vercel)

npx skills add ollygarden/opentelemetry-agent-skills --skill otel-ruby -a gemini-cli

2Platform CLI

gemini skills install https://github.com/ollygarden/opentelemetry-agent-skills --path skills/otel-ruby

Manually: put the files in place

.devin/skills/otel-ruby/SKILL.md

The legacy .windsurf/skills/ path still works

Skills CLI (Vercel)

npx skills add ollygarden/opentelemetry-agent-skills --skill otel-ruby -a opencode

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about otel-ruby

How do I install otel-ruby in Claude Code?

Run npx skills add ollygarden/opentelemetry-agent-skills --skill otel-ruby -a claude-code. The skill file is available at ~/.claude/skills/otel-ruby/SKILL.md.

What does otel-ruby do?

It guides Ruby OpenTelemetry work, from SDK configuration and manual traces to library instrumentation, performance, and upgrades.

Why should I resolve Ruby OpenTelemetry gem versions separately?

Tracing is stable, but the Ruby metrics and logs APIs, SDKs, and exporters are experimental. The skill advises resolving each dependency with Bundler and reviewing Gemfile.lock changes.

Source text

SKILL.md · Apache-2.0

---
name: otel-ruby
description: OpenTelemetry in Ruby — SDK setup, manual tracing, experimental metrics and logs, Bundler integration, contrib instrumentation for Rails/Rack/Sinatra/Sidekiq and other gems, propagation, performance, and upgrades. Use when adding, reviewing, configuring, or troubleshooting OpenTelemetry in a Ruby or Rails service. Triggers on "setup otel in ruby", "ruby telemetry", "Rails OpenTelemetry", "OpenTelemetry::SDK.configure", "opentelemetry-instrumentation-all", "Ruby tracing", "Rack otel", "Sidekiq otel", or any Ruby-related OTel question.
---

# OpenTelemetry in Ruby

Entry point for OpenTelemetry mechanics in Ruby applications. Load only the reference that matches
the task; each reference is self-contained.

## References

| File | Use when |
|---|---|
| [`references/setup.md`](references/setup.md) | Installing gems, configuring `OpenTelemetry::SDK.configure`, selecting OTLP exporters, setting resources and environment variables, and handling process shutdown. |
| [`references/api.md`](references/api.md) | Writing manual traces, metrics, or logs; managing context and propagation; testing emitted telemetry. |
| [`references/instrumentation-libraries.md`](references/instrumentation-libraries.md) | Selecting and configuring contrib instrumentation for Rails, Rack, Sinatra, HTTP clients, databases, jobs, messaging, and other gems. |
| [`references/performance.md`](references/performance.md) | Tuning sampling, batching, cardinality, forked-process behavior, exporters, and lifecycle handling. |
| [`references/breaking-changes.md`](references/breaking-changes.md) | Reviewing Ruby/runtime compatibility, independently versioned gems, experimental signal changes, and core/contrib upgrades. |

## Signal stability matters

Tracing uses the stable `opentelemetry-api` and `opentelemetry-sdk` gems. Ruby metrics and logs are
separate `0.x` API, SDK, and exporter gems and remain experimental. Do not assume a tracing gem's
version exists for metrics, logs, semantic conventions, exporters, or contrib instrumentation.
Resolve each gem independently with Bundler, inspect its changelog, and keep the resulting
`Gemfile.lock` change under review.

Released snapshot verified 2026-10-19: tracing API `1.11.1`, tracing SDK `1.13.1`, trace OTLP
exporter `0.37.0`; metrics API `0.10.0`, SDK `0.21.0`, OTLP exporter `0.14.0`; logs API `0.7.0`, SDK
`0.8.1`, OTLP exporter `0.7.0`; experimental declarative-config gem `opentelemetry-config` `0.1.0`
(traces only; `0.1.1`, verified 2026-10-15, still targets schema `v1.0.0-rc.3`; owner: the
`otel-declarative-config` [parsers table](../otel-declarative-config/SKILL.md)). Treat this as an audit anchor, not
a version-alignment rule; use the lookups below for newer releases.

## Sources of truth

| Fact | Fetch |
|---|---|
| Latest core releases and per-gem tags | `gh api repos/open-telemetry/opentelemetry-ruby/releases --paginate` |
| Latest contrib instrumentation releases | `gh api repos/open-telemetry/opentelemetry-ruby-contrib/releases --paginate` |
| Released and locked gem dependencies | `gem specification <gem> dependencies --remote --yaml`; inspect `Gemfile.lock` for the locked dependency set |
| Core implementation and changelogs | [open-telemetry/opentelemetry-ruby](https://github.com/open-telemetry/opentelemetry-ruby) |
| Contrib catalog, compatibility, and per-gem options | [open-telemetry/opentelemetry-ruby-contrib](https://github.com/open-telemetry/opentelemetry-ruby-contrib) |
| Ruby language docs | [OpenTelemetry Ruby documentation](https://opentelemetry.io/docs/languages/ruby/) |

## Cross-references

- SDK version selection across languages: `otel-sdk-versions` skill.
- Semantic convention names and stability: `otel-semantic-conventions` skill.
- OTLP receiver/export validation: `otel-collector` and `otel-telemetrygen` skills.

Similar skills

All skills for Programming languages →

migrate-to-shoehorn Matt Pocock Replaces as type assertions in tests with helpers from @total-typescript/shoehorn. Use it when tests need partial objects or deliberately invalid data. 475,388installs write-swift emilkowalski This skill guides Swift coding, reviews, and migrations using the language’s current practices. Use it to investigate concurrency errors, hangs, data races, or retain cycles. CX Codex +1 119,300installs megacave JuliusBrussee Switches agent responses to Classical Chinese (wenyan) to reduce terminal output. Activated via /megacave or /caveman wenyan. CX Codex +1 25,400installs find-docs upstash Pulls up-to-date documentation, API references and code examples for any library through the Context7 CLI. Useful when the model's training data lags behind the API. CX Codex +1 9,400installs typescript-advanced-types Seth Hobson Guides an agent through advanced TypeScript types, from generics to conditional and mapped types. Use it for typed libraries, API clients, or strict configuration objects. CX Codex 92,169installs smart-explore thedotmack Uses tree-sitter to map code structure and find symbols. Useful when you need to explore a codebase without loading every full file. CX Codex +1 7,300installs

From the same set20