/yabeda

Extendable framework for collecting and exporting metrics from your Ruby application

Primary LanguageRubyMIT LicenseMIT

Yabeda

Gem Version Tests status

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

Sponsored by Evil Martians

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

  1. 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
  2. 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!

  3. 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
  4. 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
  5. 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.

  6. 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
  7. See the docs for the adapter you're using

  8. Enjoy!

Available monitoring system adapters

Maintained by Yabeda

Third-party adapters

These are developed and maintained by other awesome folks:

  • Statsd
  • AWS CloudWatch
  • …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

Third-party plugins

These are developed and maintained by other awesome folks:

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),
)

Roadmap (aka TODO or Help wanted)

  • Ability to change metric settings for individual adapters

    histogram :foo, comment: "say what?" do
      adapter :prometheus do
        buckets [0.01, 0.5, , 60, 300, 3600]
      end
    end
  • Ability to route some metrics only for given adapter:

    adapter :prometheus do
      include_group :sidekiq
    end

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Releasing

  1. Bump version number in lib/yabeda/version.rb

    In case of pre-releases keep in mind rubygems/rubygems#3086 and check version with command like Gem::Version.new(Yabeda::VERSION).to_s

  2. Fill CHANGELOG.md with missing changes, add header with version and date.

  3. Make a commit:

    git add lib/yabeda/version.rb CHANGELOG.md
    version=$(ruby -r ./lib/yabeda/version.rb -e "puts Gem::Version.new(Yabeda::VERSION)")
    git commit --message="${version}: " --edit
  4. Create annotated tag:

    git tag v${version} --annotate --message="${version}: " --edit --sign
  5. Fill version name into subject line and (optionally) some description (changes will be taken from changelog and appended automatically)

  6. Push it:

    git push --follow-tags

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/yabeda-rb/yabeda.

License

The gem is available as open source under the terms of the MIT License.