From 30e8b09dbbf96752940500ab77ea81102e3a7af9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Johannes=20Daxb=C3=B6ck?= Date: Tue, 12 May 2026 10:50:53 +0200 Subject: [PATCH 1/2] docs(ruby): Add Yabeda integration guide Add docs page for sentry-yabeda, the Yabeda adapter gem that bridges Yabeda metrics to Sentry Application Metrics. Covers installation, configuration, metric type mapping, plugin usage, pull vs push collection, custom metrics, and scaling considerations. Co-Authored-By: Claude --- docs/platforms/ruby/guides/yabeda/config.yml | 3 + docs/platforms/ruby/guides/yabeda/index.mdx | 128 +++++++++++++++++++ 2 files changed, 131 insertions(+) create mode 100644 docs/platforms/ruby/guides/yabeda/config.yml create mode 100644 docs/platforms/ruby/guides/yabeda/index.mdx diff --git a/docs/platforms/ruby/guides/yabeda/config.yml b/docs/platforms/ruby/guides/yabeda/config.yml new file mode 100644 index 0000000000000..77e4b6e447c5b --- /dev/null +++ b/docs/platforms/ruby/guides/yabeda/config.yml @@ -0,0 +1,3 @@ + +title: Yabeda +sdk: "sentry.ruby.yabeda" diff --git a/docs/platforms/ruby/guides/yabeda/index.mdx b/docs/platforms/ruby/guides/yabeda/index.mdx new file mode 100644 index 0000000000000..996393f7ebf98 --- /dev/null +++ b/docs/platforms/ruby/guides/yabeda/index.mdx @@ -0,0 +1,128 @@ +--- +title: Yabeda +description: "Send Yabeda metrics to Sentry using the sentry-yabeda adapter gem." +sidebar_order: 30 +--- + +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. + + + +Metrics collected by the background thread won't carry trace context since they aren't tied to a specific request. + + + +### 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. \ No newline at end of file From ab15b02f2ba56bba127a05747172a167e52ad8cf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Johannes=20Daxb=C3=B6ck?= Date: Tue, 2 Jun 2026 12:37:59 +0200 Subject: [PATCH 2/2] ref(ruby): Move Yabeda from guides to integrations Yabeda is a metrics adapter, not a web/job framework like the other guides (Rails, Sidekiq, etc.). Place it under integrations where it fits better and add a cross-link from the Application Metrics page. Co-Authored-By: Claude --- docs/platforms/ruby/common/integrations/index.mdx | 5 +++++ .../yabeda/index.mdx => common/integrations/yabeda.mdx} | 1 - docs/platforms/ruby/common/metrics/index.mdx | 2 ++ docs/platforms/ruby/guides/yabeda/config.yml | 3 --- 4 files changed, 7 insertions(+), 4 deletions(-) rename docs/platforms/ruby/{guides/yabeda/index.mdx => common/integrations/yabeda.mdx} (99%) delete mode 100644 docs/platforms/ruby/guides/yabeda/config.yml diff --git a/docs/platforms/ruby/common/integrations/index.mdx b/docs/platforms/ruby/common/integrations/index.mdx index 038c12030389d..00df10a25acd8 100644 --- 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 | | `gem "sentry-delayed_job"` | | | `gem "sentry-resque"` | | | `gem "sentry-opentelemetry"` | +| | `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/guides/yabeda/index.mdx b/docs/platforms/ruby/common/integrations/yabeda.mdx similarity index 99% rename from docs/platforms/ruby/guides/yabeda/index.mdx rename to docs/platforms/ruby/common/integrations/yabeda.mdx index 996393f7ebf98..1aaa6c65a3e78 100644 --- a/docs/platforms/ruby/guides/yabeda/index.mdx +++ b/docs/platforms/ruby/common/integrations/yabeda.mdx @@ -1,7 +1,6 @@ --- title: Yabeda description: "Send Yabeda metrics to Sentry using the sentry-yabeda adapter gem." -sidebar_order: 30 --- 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. diff --git a/docs/platforms/ruby/common/metrics/index.mdx b/docs/platforms/ruby/common/metrics/index.mdx index ad6fea848c4e3..581f93e29a9ea 100644 --- 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 diff --git a/docs/platforms/ruby/guides/yabeda/config.yml b/docs/platforms/ruby/guides/yabeda/config.yml deleted file mode 100644 index 77e4b6e447c5b..0000000000000 --- a/docs/platforms/ruby/guides/yabeda/config.yml +++ /dev/null @@ -1,3 +0,0 @@ - -title: Yabeda -sdk: "sentry.ruby.yabeda"