Evan Purkhiser
64dfeaa1f1
These per-SDK skills, plus a handful of setup/workflow skills, are superseded by the sentry-instrument skill and the references/sdks/ trees. Move them under skills-legacy/ so they are excluded from the plugin build and skipped by the drift automation, while skills.sentry.dev can still serve them as a fallback for existing URL consumers. Moves 26 skills: the 19 per-SDK skills plus sentry-sdk-skill-creator, sentry-fix-issues, the three sentry-span-streaming-* skills, sentry-instrument-logging, and sentry-instrumentation-guide. Regenerates SKILL_TREE.md and repaths the moved entries in CODEOWNERS. sentry-sdk is intentionally left in place; its removal is handled in a separate PR.
3.7 KiB
Profiling — Sentry Ruby SDK
⚠️ Beta — profiling is in beta and may have bugs. Minimum SDK:
sentry-rubyv5.9.0+ (StackProf), v5.21.0+ (Vernier)
Profiling attaches CPU/memory samples to Sentry transactions. It requires tracing to be enabled first — profiles_sample_rate is relative to traces_sample_rate.
Contents
Choosing a Profiler
| Profiler | Gem | Min sentry-ruby | Min Ruby | Notes |
|---|---|---|---|---|
| StackProf | stackprof |
v5.9.0 | Any | Wall-clock or CPU sampling |
| Vernier | vernier |
v5.21.0 | 3.2.1+ | Lower overhead; GVL-aware |
Vernier is preferred for Ruby 3.2.1+ applications. Use StackProf for older Ruby versions.
GVL-aware profiling (Vernier)
Ruby's Global VM Lock (GVL) means only one thread executes Ruby code at a time. StackProf only samples the thread holding the GVL, so multi-threaded apps (Puma, Sidekiq) show incomplete profiles. Vernier is GVL-aware — it tracks all threads including those waiting on I/O or the GVL, giving a complete picture of where time is spent across the entire process.
Production overhead
Both profilers use sampling (not tracing), so overhead is low. Expect ~2-5% CPU overhead per profiled transaction. Use profiles_sample_rate to control how many transactions are profiled — start with 0.1 in production and adjust based on your performance budget.
StackProf Setup
# Gemfile
gem "sentry-ruby"
gem "sentry-rails" # if Rails
gem "stackprof"
# config/initializers/sentry.rb (Rails) or Sentry.init block
Sentry.init do |config|
config.dsn = ENV["SENTRY_DSN"]
config.traces_sample_rate = 1.0 # tracing must be enabled
config.profiles_sample_rate = 1.0 # relative to traces_sample_rate
end
Vernier Setup
# Gemfile
gem "sentry-ruby"
gem "sentry-rails" # if Rails
gem "vernier"
Sentry.init do |config|
config.dsn = ENV["SENTRY_DSN"]
config.traces_sample_rate = 1.0
config.profiles_sample_rate = 1.0
config.profiler_class = Sentry::Vernier::Profiler # opt into Vernier
end
Configuration
| Option | Type | Default | Purpose |
|---|---|---|---|
profiles_sample_rate |
Float | nil |
Fraction of sampled transactions that include a profile [0.0–1.0] |
profiler_class |
Class | StackProf profiler | Set to Sentry::Vernier::Profiler to use Vernier |
profiles_sample_rate is relative to traces_sample_rate. With traces_sample_rate = 0.1 and profiles_sample_rate = 0.5, 5% of total transactions include a profile.
Best Practices
- Start with
profiles_sample_rate = 1.0in development to verify profiles appear in Sentry - Lower to
0.1–0.5in production — profiling adds overhead per sampled transaction - Prefer Vernier on Ruby 3.2.1+ for lower overhead and GVL visibility
- Profiling without tracing is not supported — ensure
traces_sample_rate > 0
Troubleshooting
| Issue | Solution |
|---|---|
| No profiles in Sentry | Verify traces_sample_rate > 0 — profiling requires tracing to be active |
Sentry::Vernier::Profiler not found |
Ensure vernier gem is installed and sentry-ruby ≥ 5.21.0 |
| StackProf missing constant error | Add gem "stackprof" to Gemfile and run bundle install |
| Profiles on some requests only | Expected — profiles_sample_rate is a fraction of sampled transactions, not all requests |
| Beta instability | Check sentry-ruby releases for fixes; report issues there |