|
1 | | -# sentry-yabeda |
| 1 | +<p align="center"> |
| 2 | + <a href="https://sentry.io" target="_blank" align="center"> |
| 3 | + <img src="https://sentry-brand.storage.googleapis.com/sentry-logo-black.png" width="280"> |
| 4 | + </a> |
| 5 | + <br> |
| 6 | +</p> |
2 | 7 |
|
3 | | -A [Yabeda](https://github.com/yabeda-rb/yabeda) adapter that forwards Ruby application metrics to [Sentry](https://sentry.io). |
| 8 | +# sentry-yabeda, the Yabeda integration for Sentry's Ruby client |
4 | 9 |
|
5 | | -## Installation |
| 10 | +--- |
6 | 11 |
|
7 | | -Add this line to your application's Gemfile: |
| 12 | +[](https://rubygems.org/gems/sentry-yabeda) |
| 13 | + |
| 14 | +[](https://codecov.io/gh/getsentry/sentry-ruby/branch/master) |
| 15 | +[](https://rubygems.org/gems/sentry-yabeda/) |
| 16 | + |
| 17 | + |
| 18 | +[Documentation](https://docs.sentry.io/platforms/ruby/) | [Bug Tracker](https://github.com/getsentry/sentry-ruby/issues) | [Forum](https://forum.sentry.io/) | IRC: irc.freenode.net, #sentry |
| 19 | + |
| 20 | +The official Ruby-language client and integration layer for the [Sentry](https://github.com/getsentry/sentry) error reporting API. |
| 21 | + |
| 22 | + |
| 23 | +## Getting Started |
| 24 | + |
| 25 | +### Install |
8 | 26 |
|
9 | 27 | ```ruby |
| 28 | +gem "sentry-ruby" |
10 | 29 | gem "sentry-yabeda" |
11 | 30 | ``` |
12 | 31 |
|
13 | | -## Usage |
14 | | - |
15 | | -Require `sentry-yabeda` in your application. If you're using Bundler (most cases), simply adding it to your Gemfile is enough. |
| 32 | +Then initialize Sentry with metrics enabled: |
16 | 33 |
|
17 | 34 | ```ruby |
18 | | -# config/initializers/sentry.rb |
19 | 35 | Sentry.init do |config| |
20 | 36 | config.dsn = ENV["SENTRY_DSN"] |
21 | 37 | config.enable_metrics = true |
22 | 38 | end |
23 | | - |
24 | | -# config/initializers/yabeda.rb (or wherever Yabeda is configured) |
25 | | -require "sentry-yabeda" |
26 | 39 | ``` |
27 | 40 |
|
28 | 41 | That's it! All Yabeda metrics will automatically flow to Sentry. |
29 | | - |
30 | | -### Periodic Gauge Collection |
31 | | - |
32 | | -Many Yabeda plugins (puma, gc, gvl\_metrics) measure process-level state using **gauge metrics** with `collect` blocks. These blocks are designed for Prometheus's pull model. A scrape request triggers `Yabeda.collect!`, which reads the current state and sets gauge values. |
33 | | - |
34 | | -In a push-based system like Sentry, there's no scrape request. `sentry-yabeda` solves this with a built-in **periodic collector** that calls `Yabeda.collect!` on a background thread: |
35 | | - |
36 | | -```ruby |
37 | | -require "sentry-yabeda" |
38 | | - |
39 | | -# Start the collector (default: every 15 seconds) |
40 | | -Sentry::Yabeda.start_collector! |
41 | | - |
42 | | -# Or with a custom interval |
43 | | -Sentry::Yabeda.start_collector!(interval: 30) |
44 | | - |
45 | | -# Stop the collector |
46 | | -Sentry::Yabeda.stop_collector! |
47 | | -``` |
48 | | - |
49 | | -Without starting the collector, only **event-driven metrics** (counters incremented on each request, histograms measured per-operation) will flow to Sentry. Gauges that depend on periodic collection (e.g. GC stats, GVL contention, and Puma thread pool utilization) require the collector. |
50 | | - |
51 | | -** How it works ** |
52 | | - |
53 | | -Every 15s (or set interval) |
54 | | -1. Collector calls Yabeda.collect! |
55 | | -2. Plugin collect blocks fire (read GC.stat, fetch Puma /stats, etc.) |
56 | | -3. gauge.set(value) calls flow through the adapter |
57 | | -4. Sentry.metrics.gauge(name, value, attributes: tags) |
58 | | -5. Sentry buffers and sends in the next envelope flush |
59 | | - |
60 | | -### Metric Type Mapping |
61 | | - |
62 | | -| Yabeda Type | Sentry Type | |
63 | | -|-------------|-------------| |
64 | | -| Counter | `Sentry.metrics.count` | |
65 | | -| Gauge | `Sentry.metrics.gauge` | |
66 | | -| Histogram | `Sentry.metrics.distribution` | |
67 | | -| Summary | `Sentry.metrics.distribution` | |
68 | | - |
69 | | -### Tags |
70 | | - |
71 | | -Yabeda tags are passed directly as Sentry metric attributes, enabling filtering and grouping in the Sentry UI. |
72 | | - |
73 | | -### Metric Naming |
74 | | - |
75 | | -Metrics are named using the pattern `{group}.{name}` (e.g., `rails.request_duration`). Metrics without a group use just the name. |
76 | | - |
77 | | -### Trace Integration |
78 | | - |
79 | | -Since Sentry metrics carry trace context automatically, metrics emitted via the adapter are connected to active traces when `sentry-rails` or other Sentry integrations are active. This enables pivoting from metric spikes to relevant traces in the Sentry UI. |
0 commit comments