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] 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 00000000000000..77e4b6e447c5b0 --- /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 00000000000000..996393f7ebf986 --- /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