RSpec Otel

RSpec matchers to be used with the OpenTelemetry framework

Installation

Add this line to your Gemfile:

gem 'rspec-otel'

Within your spec helper, require the gem:

require 'rspec_otel'

And include the matchers within the rspec configuration:

RSpec.configure do |config|
  config.include RspecOtel::Matchers
end

Usage

Matching the presence of a span

You can match the emission of a span with the emit_span matcher:

require 'spec_helper'

RSpec.describe 'User API' do
  it 'emits a span' do
    expect do
      get :user, id: 1
    end.to emit_span('GET /user')
  end
end

emit_span will also match a regular expression:

require 'spec_helper'

RSpec.describe 'User API' do
  it 'emits a span' do
    expect do
      get :user, id: 1
    end.to emit_span(/^GET /)
  end
end

Several conditions can be added to the matcher:

• as_root - Will match spans that are the root of a trace.
• as_child - Will match spans that are not the root of a trace
• with_attributes - Will match only the spans with the specified attributes.
• without_attributes - Will only match the spans that do not have the specified attributes
• with_event - Will match only the spans with the specified event.
• without_event - Will only match the spans that do not have the specified event
• with_link - Will match only the spans with the specified link.
• without_link - Will only match the spans that do not have the specified link
• with_status - Will match only the spans that have the proper status.
• with_exception - Will match only the spans that have the specified exception event.
• without_exception - Will match only the spans that do not have the specified exception event.

The *_event condition can be called multiple times with different events.

Matching the presence of a metric

You can match the emission of a metric with the emit_metric matcher:

require 'spec_helper'

RSpec.describe 'User API' do
  it 'emits a metric' do
    expect do
      get :user, id: 1
    end.to emit_metric('http.server.duration')
  end
end

emit_metric will also match a regular expression:

expect do
  get :user, id: 1
end.to emit_metric(/^http\.server\./)

Several conditions can be added to the matcher:

• of_type - Will match only metrics of the specified instrument kind (:counter, :histogram, :gauge, :up_down_counter, :observable_counter, :observable_gauge, :observable_up_down_counter).
• with_attributes - Will match only the metrics with the specified attributes on a data point.
• without_attributes - Will only match the metrics that do not have the specified attributes on any data point.
• with_value - Will match only the metrics where a data point has the specified value (applies to counters, gauges, and up-down counters).
• with_count - Will match only the metrics where a histogram data point has the specified recording count (applies to histograms only).

expect do
  get :user, id: 1
end.to emit_metric('http.server.duration')
       .of_type(:histogram)
       .with_attributes({ 'http.request.method' => 'GET' })

Disabling

We wrap every example in a new OpenTelemetry SDK configuration by default, if you wish to disable this you can tag your example with :rspec_otel_disable_tracing:

require 'spec_helper'

RSpec.describe 'User API', :rspec_otel_disable_tracing do
  it 'tests my code' do
    expect(true).to be true
  end
end

Compatibility

RSpec Otel ensures compatibility with the currently supported versions of the Ruby Language.