Yabeda

To test metrics in RSpec, first add require "yabeda/rspec" to your rails_helper.rb or spec_helper.rb.

You can then use several matchers to verify metric updates:

• increment_yabeda_counter(metric): Verifies a counter increased. Use .by(n) to check the amount.
• update_yabeda_gauge(metric_name): Verifies a gauge was updated. Use .to(value) to check the new value.
• measure_yabeda_histogram(metric): Verifies a histogram measurement. Use .with(value) to check the range/value.
• observe_yabeda_summary(metric): Verifies a summary observation.

You can also scope tests using .with_tags(...) and verify specific tag values using .with(...).

# spec_helper.rb
require "yabeda/rspec"

# Example tests

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

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

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

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

You can define custom metrics within a Yabeda.configure block using groups. Supported metric types include counter, gauge, histogram, and summary.

1. Declaration

Metrics are organized into groups. You can add comments, units, and tags during declaration.

2. Initialization

After declaring metrics, you must call Yabeda.configure! to apply the configuration. Note: If you are using Ruby on Rails, this step is handled automatically.

3. Usage

Access metrics via the group name on the Yabeda module. Use methods like .increment for counters or .measure for histograms.

4. Periodic Collection

Use the collect block to report metrics that represent the current state of your application (e.g., counting active records). This block is executed periodically by your adapter.

5. Default Tags

You can set global tags or group-specific tags. You can also temporarily override tags for a specific block of code using Yabeda.with_tags.

# 1. Declare 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. Apply configuration (Automatic in Rails)
Yabeda.configure!

# 3. Use metrics
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. Periodic collection
Yabeda.configure do
  collect do
    your_app.whistles_active.set({}, Whistle.where(state: :active).count)
  end
end

# 5. Default tags and overrides
Yabeda.configure do
  default_tag :rails_environment, 'production'
  default_tag :tag_name, 'override', group: :your_app
end

Yabeda.with_tags(rails_environment: 'staging') do
  Yabeda.your_app.bells_rang_count.increment({bell_size: bell.size}, by: 1)
end

To support a new monitoring system, you must create a class that inherits from Yabeda::BaseAdapter. You need to implement the register! method (or the specific register_X! methods) to handle different metric types, and the corresponding perform_X! methods to execute the actual metric updates in your monitoring system.

Metric Registration

For each metric type your system supports, implement the corresponding registration method:

• register_counter!(metric)
• register_gauge!(metric)
• register_histogram!(metric)
• register_summary!(metric)

If a method is not implemented, it should raise NotImplementedError.

Metric Execution

Once registered, the adapter must implement the execution methods:

• perform_counter_increment!(counter, tags, increment)
• perform_gauge_set!(metric, tags, value)
• perform_histogram_measure!(metric, tags, value)
• perform_summary_observe!(metric, tags, value)

Native Gauge Increment/Decrement

Yabeda::BaseAdapter provides an optional method perform_gauge_increment!(_gauge, _tags, _increment).

• If your monitoring system supports native gauge increments/decrements, implement this method and ensure it returns a non-nil value.
• If it does not support it, leave it as the default (which returns nil).

class MyCustomAdapter < Yabeda::BaseAdapter
  def register_counter!(metric)
    # implementation
  end

  def perform_counter_increment!(counter, tags, increment)
    # implementation
  end

  def perform_gauge_increment!(gauge, tags, increment)
    # return non-nil if supported
    true
  end
end