Extendable solution for easy setup of monitoring in your Ruby apps.

Read more about Yabeda and the reasoning behind it in Martian Chronicles: “Meet Yabeda: Modular framework for instrumenting Ruby applications”

Installation

Most of the time you don't need to add this gem to your Gemfile directly (unless you're only collecting your custom metrics):

gem 'yabeda'

# Add some plugins to quickly start collecting some essential metrics:
# gem 'yabeda-rails'
# gem 'yabeda-sidekiq'

# Then add monitoring system adapter, e.g.:
# gem 'yabeda-prometheus'

And then execute:

$ bundle

Usage

Declare your metrics:

Yabeda.configure do
  group :your_app do
    counter   :bells_rang_count, comment: "Total number of bells being rang", tags: %i[bell_size]
    gauge     :whistles_active,  comment: "Number of whistles ready to whistle"
    histogram :whistle_runtime do
      comment "How long whistles are being active"
      unit :seconds
    end
    summary :bells_ringing_duration, unit: :seconds, comment: "How long bells are ringing"
  end
end

After your application was initialized and all metrics was declared, you need to apply Yabeda configuration:
```
Yabeda.configure!
```
If you're using Ruby on Rails then it will be configured automatically!

Access metric in your app and use it!

def ring_the_bell(id)
  bell = Bell.find(id)
  bell.ring!
  Yabeda.your_app.bells_rang_count.increment({bell_size: bell.size}, by: 1)
end

def whistle!
  Yabeda.your_app.whistle_runtime.measure do
    # Run your code
  end
end

Setup collecting of metrics that do not tied to specific events in you application. E.g.: reporting your app's current state

Yabeda.configure do
  # This block will be executed periodically few times in a minute
  # (by timer or external request depending on adapter you're using)
  # Keep it fast and simple!
  collect do
    your_app.whistles_active.set({}, Whistle.where(state: :active).count)
  end
end

Optionally setup default tags for all appropriate metrics

Yabeda.configure do
  # matches all metrics in all groups
  default_tag :rails_environment, 'production'

  # matches all metrics in the :your_app group
  default_tag :tag_name, 'override', group: :your_app
end

# You can redefine them for limited amount of time
Yabeda.with_tags(rails_environment: 'staging') do
  Yabeda.your_app.bells_rang_count.increment({bell_size: bell.size}, by: 1)
end

Note: any usage of with_tags must have all those tags defined on all metrics that are generated in the block.

Optionally override default tags using precedence:

The tag precedence from high to low is:
- Manually specified tags
- Thread local tags (specified by Yabeda.with_tags)
- Group specific tags
- Global tags
See the docs for the adapter you're using
Enjoy!

Available monitoring system adapters

Maintained by Yabeda

Prometheus:
- yabeda-prometheus — wraps official Ruby client for Prometheus.
- yabeda-prometheus-mmap — wraps GitLab's fork of Prometheus Ruby client which may work better for multi-process application servers.
Datadog
NewRelic

Third-party adapters

These are developed and maintained by other awesome folks:

Statsd
AWS CloudWatch
Honeybadger Insights
…and more! You can write your own adapter and open a pull request to add it into this list.

Available plugins to collect metrics

Maintained by Yabeda

[yabeda-rails] — basic request metrics for Ruby on Rails applications.
[yabeda-activerecord] — query performance and connection pool stats for apps using ActiveRecord to query databases.
[yabeda-sidekiq] — comprehensive set of metrics for monitoring Sidekiq jobs execution and queues.
[yabeda-faktory] — metrics for monitoring jobs execution by Ruby workers of Faktory.
[yabeda-graphql] — metrics to query and field-level monitoring for apps using GraphQL-Ruby.
[yabeda-puma-plugin] — metrics for internal state and performance of Puma application server.
[yabeda-http_requests] — monitor how many outgoing HTTP calls your application does (uses Sniffer).
[yabeda-schked] — monitor number and duration of Cron jobs executed by Schked.
[yabeda-anycable] — monitor number, duration, and status of AnyCable RPC calls.

Third-party plugins

These are developed and maintained by other awesome folks:

yabeda-grape — metrics for Grape framework.
yabeda-gruf — metrics for gRPC Ruby Framework
yabeda-gc — metrics for Ruby garbage collection.
yabeda-activejob — backend-agnostic metrics for background jobs.
yabeda-shoryuken — metrics for Shoryuken jobs execution message queues.
yabeda-rack-ratelimit — metrics for Rack::Ratelimit
yabeda-hanami — metrics for Hanami The web, with simplicity.
yabeda-jemalloc - metrics for Jemalloc via the stats FFI
yabeda-rack-queue - metrics for reporting queue times of Rack applications.
…and more! You can write your own adapter and open a pull request to add it into this list.

Configuration

Configuration is handled by [anyway_config] gem. With it you can load settings from environment variables (which names are constructed from config key upcased and prefixed with YABEDA_), YAML files, and other sources. See [anyway_config] docs for details.

Config key | Type | Default | Description | ---------- | -------- | ------- | ----------- | debug | boolean | false | Collects metrics measuring Yabeda performance |

Debugging metrics

Time of collector block run: yabeda_collect_duration (segmented by block source location). Collector blocks are used for collecting metrics of application state and usually makes some potentially slow queries to databases, network requests, etc.

These are only enabled in debug mode. To enable it either set debug config key to true (e.g. by specifying YABEDA_DEBUG=true in your environment variables or executing Yabeda.debug! in your code).

Testing

RSpec

Add the following to your rails_helper.rb (or spec_helper.rb):

require "yabeda/rspec"

Now you can use increment_yabeda_counter, update_yabeda_gauge, measure_yabeda_histogram, and observe_yabeda_summary matchers:

it "increments counters" do
  expect { subject }.to increment_yabeda_counter(Yabeda.myapp.foo_count).by(3)
end

You can scope metrics by used tags with with_tags:

it "updates gauges" do
  expect { subject }.to \
    update_yabeda_gauge("some_gauge_name").
    with_tags(method: "command", command: "subscribe")
end

Note that tags you specified doesn't need to be exact, but can be a subset of tags used on metric update. In this example updates with following sets of tags { method: "command", command: "subscribe", status: "SUCCESS" } and { method: "command", command: "subscribe", status: "FAILURE" } will make test example to pass.

And check for values with by for counters, to for gauges, and with for histograms and summaries (and you can use other matchers here):

expect { subject }.to \
  measure_yabeda_histogram(Yabeda.something.anything_runtime).
  with(be_between(0.005, 0.05))

You also can specify multiple tags and their expected values in with:

expect { whatever }.to increment_yabeda_counter(:my_counter).with(
  { tag: "foo" } => 1,
  { tag: "bar" } => (be >= 42),
)

Advanced usage

Limiting metrics and groups to specific adapters

You can limit, which metrics and groups should be available for specific adapter:

Yabeda.configure do
  group :internal do
    adapter :prometheus

    counter :foo
    gauge :bar
  end

  group :cloud do
    adapter :

Yabeda

Install / Use

README

Installation

Usage

Available monitoring system adapters

Maintained by Yabeda

Third-party adapters

Available plugins to collect metrics

Maintained by Yabeda

Third-party plugins

Configuration

Debugging metrics

Testing

RSpec

Advanced usage

Limiting metrics and groups to specific adapters