docs(ruby): Add Yabeda integration guide (#17732)

dingsdax · claude · web-flow · commit 7796c1f0cff4 · 2026-06-02T13:25:45.000+02:00
## DESCRIBE YOUR PR Add a docs page for `sentry-yabeda`, the Yabeda adapter gem that bridges Yabeda metrics to Sentry Application Metrics. The `sentry-yabeda` gem is being added to the Ruby SDK in [getsentry/sentry-ruby#2925](getsentry/sentry-ruby#2925). This page documents the integration for end users. - Installation and configuration - Metric type mapping (counter, gauge, histogram, summary) - Usage with Yabeda plugins (puma, gc, activerecord) - Pull-based vs push-based collection and the periodic collector - Defining custom metrics - When to use Yabeda vs direct `Sentry.metrics.*` calls - Scaling considerations for high-volume use cases ## IS YOUR CHANGE URGENT? Help us prioritize incoming PRs by letting us know when the change needs to go live. - [ ] Urgent deadline (GA date, etc.):  - [ ] Other deadline:  - [x] None: Not urgent, can wait up to 1 week+ ## SLA - Teamwork makes the dream work, so please add a reviewer to your PRs. - Please give the docs team up to 1 week to review your PR unless you've added an urgent due date to it. Thanks in advance for your help! ## PRE-MERGE CHECKLIST *Make sure you've checked the following before merging your changes:* - [ ] Checked Vercel preview for correctness, including links - [ ] PR was reviewed and approved by any necessary SMEs (subject matter experts) - [ ] PR was reviewed and approved by a member of the [Sentry docs team](https://github.com/orgs/getsentry/teams/docs) --------- Co-authored-by: Claude <noreply@anthropic.com>
diff --git a/docs/platforms/ruby/common/integrations/index.mdx b/docs/platforms/ruby/common/integrations/index.mdx
@@ -22,6 +22,7 @@ Simply add the relevant gems to your Gemfile and run `bundle install` to install
 | <LinkWithPlatformIcon platform="ruby.delayed_job"      label="Delayed Job"    url="/platforms/ruby/guides/delayed_job/" />                    | `gem "sentry-delayed_job"`   |
 | <LinkWithPlatformIcon platform="ruby.resque"           label="Resque"         url="/platforms/ruby/guides/resque" />                          | `gem "sentry-resque"`        |
 | <LinkWithPlatformIcon platform="ruby.opentelemetry"    label="OpenTelemetry"  url="/platforms/ruby/tracing/instrumentation/opentelemetry" />  | `gem "sentry-opentelemetry"` |
+| <LinkWithPlatformIcon platform="ruby"                  label="Yabeda"         url="/platforms/ruby/integrations/yabeda" />                    | `gem "sentry-yabeda"`        |
 
 ## Patches
 
@@ -71,6 +72,10 @@ The OpenTelemetry integration is used for exporting spans instrumented by an Ope
 
 The [OTLP integration](/platforms/ruby/integrations/otlp/) configures the Sentry SDK to automatically send trace data instrumented by an OpenTelemetry SDK to Sentry via the OpenTelemetry Protocol (OTLP). This is the recommended approach for sending OpenTelemetry traces to Sentry.
 
+### Yabeda
+
+The [Yabeda integration](/platforms/ruby/integrations/yabeda/) connects [Yabeda](https://github.com/yabeda-rb/yabeda) to Sentry's [Application Metrics](/platforms/ruby/metrics/), forwarding any metrics defined with Yabeda or collected by Yabeda plugins to Sentry automatically.
+
 ### HTTP Requests
 
 Outgoing HTTP Requests are instrumented as Spans by the `:http` (for requests done with `Net::HTTP`) and `:faraday` patches.
diff --git a/docs/platforms/ruby/common/integrations/yabeda.mdx b/docs/platforms/ruby/common/integrations/yabeda.mdx
@@ -0,0 +1,127 @@
+---
+title: Yabeda
+description: "Send Yabeda metrics to Sentry using the sentry-yabeda adapter gem."
+---
+
+The `sentry-yabeda` gem is a Yabeda adapter that connects [Yabeda](https://github.com/yabeda-rb/yabeda) to Sentry's [Application Metrics](/platforms/ruby/metrics/). Any metric you define with Yabeda, or that a Yabeda plugin collects, automatically forwards to Sentry with no changes to plugin code.
+
+This is especially useful when you already have Yabeda plugins collecting process-level runtime data (GC pressure, thread pool utilization, connection pool stats) that tracing alone can't capture.
+
+## Install
+
+Add the gems to your `Gemfile`:
+
+```ruby
+gem "sentry-ruby"
+gem "sentry-yabeda"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Configure
+
+Initialize Sentry with metrics enabled. The Yabeda adapter registers itself automatically when `sentry-yabeda` is required — there's no extra setup:
+
+```ruby
+Sentry.init do |config|
+  config.dsn = ENV["SENTRY_DSN"]
+  config.enable_metrics = true
+end
+```
+
+All Yabeda metrics now flow to Sentry.
+
+## Metric Type Mapping
+
+Yabeda metric types translate to Sentry as follows:
+
+| Yabeda type | Sentry method                 | Notes                      |
+| ----------- | ----------------------------- | -------------------------- |
+| `counter`   | `Sentry.metrics.count`        |                            |
+| `gauge`     | `Sentry.metrics.gauge`        |                            |
+| `histogram` | `Sentry.metrics.distribution` |                            |
+| `summary`   | `Sentry.metrics.distribution` | Sentry has no summary type |
+
+Metric names combine the Yabeda group and name with a dot separator. A counter named `orders_created` in group `myapp` becomes `myapp.orders_created` in Sentry.
+
+Tags are passed through as metric attributes.
+
+## Usage With Yabeda Plugins
+
+Yabeda has a rich plugin ecosystem. Some examples that work well with Sentry:
+
+| Plugin                                                                  | What it captures                          |
+| ----------------------------------------------------------------------- | ----------------------------------------- |
+| [yabeda-puma-plugin](https://github.com/yabeda-rb/yabeda-puma-plugin)   | Thread pool utilization, backlog, workers |
+| [yabeda-gc](https://github.com/ianks/yabeda-gc)                         | GC pause time, heap stats                 |
+| [yabeda-activerecord](https://github.com/yabeda-rb/yabeda-activerecord) | Connection pool size, busy/idle/waiting   |
+
+Add the plugin gems and they'll start forwarding metrics to Sentry immediately.
+
+### Pull-Based vs Push-Based Collection
+
+Some Yabeda plugins use `collect` blocks to gather metrics. This is a pull-based pattern designed for Prometheus, where a scrape request triggers collection. Since Sentry is push-based, `sentry-yabeda` runs a background thread that calls `Yabeda.collect!` every 15 seconds to drive these plugins.
+
+This collector starts automatically when `enable_metrics` is `true`. Event-driven metrics (counters, histograms) flow to Sentry immediately — only pull-based gauges (like GC stats or Puma thread pool metrics) depend on the collector.
+
+<Alert>
+
+Metrics collected by the background thread won't carry trace context since they aren't tied to a specific request.
+
+</Alert>
+
+### Puma Configuration
+
+If you're using `yabeda-puma-plugin`, enable the Puma control app so the plugin can fetch thread and backlog stats:
+
+```ruby
+# config/puma.rb
+activate_control_app "unix://tmp/pumactl.sock", no_token: true
+plugin :yabeda
+```
+
+## Defining Custom Metrics
+
+You can define your own metrics with Yabeda and they'll automatically appear in Sentry:
+
+```ruby
+Yabeda.configure do
+  group :myapp do
+    counter   :orders_created, comment: "Orders placed", tags: %i[region]
+    gauge     :queue_depth,    comment: "Jobs waiting",  tags: %i[queue_name]
+    histogram :response_time,  comment: "Response time", unit: :milliseconds, tags: %i[controller]
+  end
+end
+```
+
+Then use them in your application code:
+
+```ruby
+Yabeda.myapp.orders_created.increment({ region: "us-east" })
+Yabeda.myapp.queue_depth.set({ queue_name: "default" }, 42)
+Yabeda.myapp.response_time.measure({ controller: "orders" }, 150.5)
+```
+
+## When to Use Yabeda vs. Direct Sentry Metrics
+
+Use **Yabeda** when:
+
+- You already have Yabeda plugins in your stack and want their data in Sentry.
+- You want vendor-neutral metric definitions that can target multiple adapters (Sentry, Prometheus, Datadog) simultaneously.
+
+Use **direct `Sentry.metrics.*` calls** when:
+
+- You're tracking a one-off business event and don't need a full metrics framework.
+- You want trace-correlated metrics tied to specific transactions.
+
+Both approaches can coexist in the same application.
+
+## Scaling Considerations
+
+Routing Yabeda metrics to Sentry works well for application-level data: business events, runtime diagnostics, and the kind of process-level gauges the plugins above collect. Sentry stores a row per metric event, so tracking anything from a handful of custom counters up to a moderate volume of plugin gauges is absolutely viable.
+
+At very high collection volumes (think: hundreds of nodes in a Kubernetes cluster each emitting per-second metrics), tools like Prometheus that pre-aggregate and compact data are purpose-built for that scale.
diff --git a/docs/platforms/ruby/common/metrics/index.mdx b/docs/platforms/ruby/common/metrics/index.mdx
@@ -13,6 +13,8 @@ Sentry metrics help you pinpoint and solve issues that impact user experience an
 
 Once in Sentry, these metrics can be viewed alongside relevant errors, and searched using their individual attributes.
 
+If you already use [Yabeda](https://github.com/yabeda-rb/yabeda) for metrics collection, the [Yabeda integration](/platforms/ruby/integrations/yabeda/) can forward all Yabeda metrics to Sentry automatically.
+
 ## Requirements
 
 <PlatformContent includePath="metrics/requirements" />
