rspec-otel 0.0.7 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b966349d533ad57a8ee5fc1fd79b7ed99922beb6aad8fc1fb59e97d8062cdf5e
-  data.tar.gz: e167fba956f24f180846574e5b87214f906b0d35377d7b92230df99aa6244dc2
+  metadata.gz: 34bc15bc0e142300b4a3d26488b19cf53567d7398377699267c30092a4c81f24
+  data.tar.gz: 3d7b067208db46d4c30d8768f16de46681b5bbfed4d841d4e426ed558f17ae98
 SHA512:
-  metadata.gz: 5f19d4e4b8c94818c8d11e373380fc527c8e61f875e24189c3fa401a38d49f1647eb4f5e4862dea702de3397fd2ec81ee6deca4612056678c8de9faa90208eae
-  data.tar.gz: a3320a67e728db92483d66a7cad492abbc7785cb7088417ab8e9e23b1648db348b0b32e869b308d6369a0cb7c267c613a17e7f0f810d11ab5138a4cbb6072b98
+  metadata.gz: cd70b47b5b70a3b3eb9c6ef8f73bc5ea6e3bc5ab9e834ec94e3defce8f0ac34912a16df748a15757a1c46208b11a9f77614a2e1acfdffdadc3bc025847c0f812
+  data.tar.gz: f224136edc1819bff811c66cba4b2d6b449bd286e99272b32a84c2247746882956a3d2b62fd3319978a7150719a94c93e57635c1960d45c0b65b194ac2653ca5

data/README.md

@@ -73,6 +73,47 @@ Several conditions can be added to the matcher:
 _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:
+
+```ruby
+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:
+
+```ruby
+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).
+
+```ruby
+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`:

data/lib/rspec_otel/matchers/emit_metric.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module RspecOtel
+  module Matchers
+    class EmitMetric
+      def initialize(name)
+        @name = name
+        @kind = nil
+        @filters = []
+        @before_count = 0
+        @pre_snapshot = {}
+        @closest_metric = nil
+        @closest_filter_count = 0
+        @emitted_outside_block = false
+      end
+
+      def matches?(block)
+        execute_block(block) if block.respond_to?(:call)
+        matching_metric?
+      end
+
+      def of_type(kind)
+        @kind = kind
+        self
+      end
+
+      def with_attributes(attributes)
+        @filters << ->(dp) { attributes_match?(dp.attributes || {}, attributes) }
+        self
+      end
+
+      def without_attributes(attributes)
+        @filters << ->(dp) { !attributes_match?(dp.attributes || {}, attributes) }
+        self
+      end
+
+      def with_value(value)
+        @filters << lambda { |dp|
+          raise ArgumentError, 'with_value is not supported for histogram data points' unless dp.respond_to?(:value)
+
+          dp.value == value
+        }
+        self
+      end
+
+      def with_count(count)
+        @filters << lambda { |dp|
+          raise ArgumentError, 'with_count is only supported for histogram data points' if dp.respond_to?(:value)
+
+          dp.count == count
+        }
+        self
+      end
+
+      def failure_message
+        closest = @closest_metric || new_snapshots.first
+        if closest.nil?
+          "expected metric #{printable_name} to have been emitted, but no metrics were emitted at all"
+        elsif @emitted_outside_block
+          "expected metric #{printable_name} to have been emitted within the block, but it was already emitted before"
+        else
+          "expected metric #{printable_name} to have been emitted, but it couldn't be found. " \
+            "Found a close matching metric named `#{closest.name}`#{MetricDetails.new(closest)}"
+        end
+      end
+
+      def failure_message_when_negated
+        "expected metric #{printable_name} to not have been emitted"
+      end
+
+      def supports_block_expectations?
+        true
+      end
+
+      private
+
+      def execute_block(block)
+        RspecOtel.metric_exporter.pull
+        @pre_snapshot = build_pre_snapshot(RspecOtel.metric_exporter.metric_snapshots)
+        @before_count = RspecOtel.metric_exporter.metric_snapshots.length
+        block.call
+        RspecOtel.metric_exporter.pull
+      end
+
+      def matching_metric?
+        new_snapshots.each do |metric_data|
+          next unless name_matches?(metric_data.name)
+          next unless kind_matches?(metric_data.instrument_kind)
+
+          return true if matching_data_point?(metric_data)
+
+          @closest_metric ||= metric_data
+        end
+
+        false
+      end
+
+      def matching_data_point?(metric_data)
+        any_changed = false
+        metric_data.data_points.each do |data_point|
+          next unless data_point_changed?(metric_data.name, metric_data.instrument_kind, data_point)
+
+          any_changed = true
+          return true if all_filters_match?(metric_data, data_point)
+        end
+        @emitted_outside_block ||= !any_changed
+        false
+      end
+
+      def all_filters_match?(metric_data, data_point)
+        count = @filters.count { |f| f.call(data_point) }
+        if count > @closest_filter_count
+          @closest_metric = metric_data
+          @closest_filter_count = count
+        end
+        count == @filters.length
+      end
+
+      def data_point_changed?(metric_name, instrument_kind, data_point)
+        pre = @pre_snapshot.dig(metric_name, data_point.attributes)
+        return true if pre.nil?
+        return false if observable_instrument?(instrument_kind)
+
+        pre != data_point_magnitude(data_point)
+      end
+
+      def observable_instrument?(instrument_kind)
+        %i[observable_counter observable_gauge observable_up_down_counter].include?(instrument_kind)
+      end
+
+      def data_point_magnitude(data_point)
+        data_point.respond_to?(:value) ? data_point.value : data_point.count
+      end
+
+      def build_pre_snapshot(snapshots)
+        # metric_snapshots accumulates across pulls; if the same metric name appears multiple
+        # times, to_h keeps the last entry — which is the most recent (and correct) baseline.
+        snapshots.to_h do |metric_data|
+          [metric_data.name, metric_data.data_points.to_h { |dp| [dp.attributes, data_point_magnitude(dp)] }]
+        end
+      end
+
+      def new_snapshots
+        RspecOtel.metric_exporter.metric_snapshots[@before_count..]
+      end
+
+      def kind_matches?(instrument_kind)
+        @kind.nil? || instrument_kind == @kind
+      end
+
+      def name_matches?(metric_name)
+        case @name
+        when String then metric_name == @name
+        when Regexp then metric_name.match?(@name)
+        end
+      end
+
+      def printable_name
+        case @name
+        when String then "'#{@name}'"
+        when Regexp then @name.inspect
+        end
+      end
+
+      def attributes_match?(actual, expected)
+        expected.all? { |k, v| actual[k] == v }
+      end
+    end
+  end
+end

data/lib/rspec_otel/matchers/emit_span.rb

@@ -2,7 +2,7 @@
 
 module RspecOtel
   module Matchers
-    class EmitSpan # rubocop:disable Metrics/ClassLength
+    class EmitSpan
       attr_reader :name
 
       def initialize(name = nil)
@@ -14,95 +14,55 @@ module RspecOtel
         @filters << name_filter
       end
 
-      def matches?(block) # rubocop:disable Metrics/MethodLength
-        if block.respond_to?(:call)
-          @before_spans = RspecOtel.exporter.finished_spans
-          block.call
-        end
-
-        closest_count = 0
-        (RspecOtel.exporter.finished_spans - @before_spans).each do |span|
-          count = @filters.count { |f| f.call(span) }
-          @closest_span = span if count > closest_count
-          closest_count = count
-          return true if count == @filters.count
-        end
-
-        false
+      def matches?(block)
+        capture_before_spans(block)
+        matching_span?
       end
 
       def as_child
-        @filters << lambda do |span|
-          span.parent_span_id && span.parent_span_id != OpenTelemetry::Trace::INVALID_SPAN_ID
-        end
-
+        @filters << ->(span) { span.parent_span_id && span.parent_span_id != OpenTelemetry::Trace::INVALID_SPAN_ID }
         self
       end
 
       def as_root
-        @filters << lambda do |span|
-          span.parent_span_id == OpenTelemetry::Trace::INVALID_SPAN_ID
-        end
-
+        @filters << ->(span) { span.parent_span_id == OpenTelemetry::Trace::INVALID_SPAN_ID }
         self
       end
 
       def with_attributes(attributes)
-        @filters << lambda do |span|
-          attributes_match?(span.attributes, attributes)
-        end
-
+        @filters << ->(span) { attributes_match?(span.attributes, attributes) }
         self
       end
 
       def without_attributes(attributes)
-        @filters << lambda do |span|
-          !attributes_match?(span.attributes, attributes)
-        end
-
+        @filters << ->(span) { !attributes_match?(span.attributes, attributes) }
         self
       end
 
       def with_link(attributes = {})
-        @filters << lambda do |span|
-          span.links &&
-            link_match?(span.links, attributes)
-        end
-
+        @filters << ->(span) { span.links && link_match?(span.links, attributes) }
         self
       end
 
       def without_link(attributes = {})
-        @filters << lambda do |span|
-          span.links.nil? ||
-            !link_match?(span.links, attributes)
-        end
-
+        @filters << ->(span) { span.links.nil? || !link_match?(span.links, attributes) }
         self
       end
 
       def with_event(name, attributes = {})
-        @filters << lambda do |span|
-          span.events &&
-            event_match?(span.events, OpenTelemetry::SDK::Trace::Event.new(name, attributes))
-        end
-
+        event = OpenTelemetry::SDK::Trace::Event.new(name, attributes)
+        @filters << ->(span) { span.events && event_match?(span.events, event) }
         self
       end
 
       def without_event(name, attributes = {})
-        @filters << lambda do |span|
-          span.events.nil? ||
-            !event_match?(span.events, OpenTelemetry::SDK::Trace::Event.new(name, attributes))
-        end
-
+        event = OpenTelemetry::SDK::Trace::Event.new(name, attributes)
+        @filters << ->(span) { span.events.nil? || !event_match?(span.events, event) }
         self
       end
 
       def with_status(code, description)
-        @filters << lambda do |span|
-          status_match?(span.status, code, description)
-        end
+        @filters << ->(span) { status_match?(span.status, code, description) }
         self
       end
 
@@ -116,15 +76,12 @@ module RspecOtel
 
       def failure_message
         closest = closest_span
-        expect_content = "expected span #{failure_match_description} #{printable_name} to have been emitted"
+        prefix = "expected span #{failure_match_description} #{printable_name} to have been emitted"
 
         case closest
-        when nil
-          "#{expect_content}, but there were no spans emitted at all"
-        when OpenTelemetry::SDK::Trace::SpanData
-          "#{expect_content}, but it couldn't be found. Found a close matching span named `#{closest.name}`"
-        else
-          raise "I don't know what to do with a #{closest.class} span"
+        when nil then "#{prefix}, but there were no spans emitted at all"
+        when OpenTelemetry::SDK::Trace::SpanData then closest_not_found_message(prefix, closest)
+        else raise "I don't know what to do with a #{closest.class} span"
         end
       end
 
@@ -138,6 +95,24 @@ module RspecOtel
 
       private
 
+      def capture_before_spans(block)
+        return unless block.respond_to?(:call)
+
+        @before_spans = RspecOtel.exporter.finished_spans
+        block.call
+      end
+
+      def matching_span?
+        closest_count = 0
+        (RspecOtel.exporter.finished_spans - @before_spans).each do |span|
+          count = @filters.count { |f| f.call(span) }
+          @closest_span = span if count > closest_count
+          closest_count = count
+          return true if count == @filters.count
+        end
+        false
+      end
+
       def closest_span
         return @closest_span unless @closest_span.nil?
 
@@ -219,6 +194,11 @@ module RspecOtel
 
         !link.empty?
       end
+
+      def closest_not_found_message(prefix, span)
+        "#{prefix}, but it couldn't be found. " \
+          "Found a close matching span named `#{span.name}`#{SpanDetails.new(span)}"
+      end
     end
   end
 end

data/lib/rspec_otel/matchers/metric_details.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module RspecOtel
+  module Matchers
+    class MetricDetails
+      def initialize(metric)
+        @metric = metric
+      end
+
+      def to_s
+        "\n#{[type_details, data_points_details].compact.join("\n")}"
+      end
+
+      private
+
+      def type_details
+        "  type: #{@metric.instrument_kind}"
+      end
+
+      def data_points_details
+        return unless @metric.data_points&.any?
+
+        format_collection('data_points', @metric.data_points) { |dp| format_data_point(dp) }
+      end
+
+      def format_collection(header, collection, &)
+        item_lines = collection.map(&)
+        "  #{header}:\n#{item_lines.join("\n")}"
+      end
+
+      def format_data_point(data_point)
+        magnitude_label = data_point.respond_to?(:value) ? "value: #{data_point.value}" : "count: #{data_point.count}"
+        attrs = data_point.attributes
+        attrs&.any? ? "    - #{magnitude_label} #{attrs.inspect}" : "    - #{magnitude_label}"
+      end
+    end
+  end
+end

data/lib/rspec_otel/matchers/span_details.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module RspecOtel
+  module Matchers
+    class SpanDetails
+      def initialize(span)
+        @span = span
+      end
+
+      def to_s
+        lines = [attributes_details, events_details, links_details, status_details].compact
+        return '' if lines.empty?
+
+        "\n#{lines.join("\n")}"
+      end
+
+      private
+
+      def attributes_details
+        return unless @span.attributes&.any?
+
+        "  attributes: #{@span.attributes.inspect}"
+      end
+
+      def events_details
+        return unless @span.events&.any?
+
+        format_collection('events', @span.events) { |e| format_item(e.name, e.attributes) }
+      end
+
+      def links_details
+        return unless @span.links&.any?
+
+        format_collection('links', @span.links) { |l| format_item('link', l.attributes) }
+      end
+
+      def status_details
+        return if @span.status.nil? || @span.status.code == OpenTelemetry::Trace::Status::UNSET
+
+        label = status_label(@span.status.code)
+        desc = @span.status.description
+        status_str = desc.to_s.empty? ? label : "#{label} (#{desc})"
+        "  status: #{status_str}"
+      end
+
+      def format_collection(header, collection, &)
+        item_lines = collection.map(&)
+        "  #{header}:\n#{item_lines.join("\n")}"
+      end
+
+      def format_item(label, attributes)
+        attributes&.any? ? "    - #{label} #{attributes.inspect}" : "    - #{label}"
+      end
+
+      def status_label(code)
+        case code
+        when OpenTelemetry::Trace::Status::OK    then 'ok'
+        when OpenTelemetry::Trace::Status::ERROR then 'error'
+        else 'unknown'
+        end
+      end
+    end
+  end
+end

data/lib/rspec_otel/matchers.rb

@@ -5,7 +5,14 @@ module RspecOtel
     def emit_span(name)
       EmitSpan.new(name)
     end
+
+    def emit_metric(name)
+      EmitMetric.new(name)
+    end
   end
 end
 
 require 'rspec_otel/matchers/emit_span'
+require 'rspec_otel/matchers/emit_metric'
+require 'rspec_otel/matchers/span_details'
+require 'rspec_otel/matchers/metric_details'

data/lib/rspec_otel/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RspecOtel
-  VERSION = '0.0.7'
+  VERSION = '0.1.0'
 end

data/lib/rspec_otel.rb

@@ -2,12 +2,17 @@
 
 require 'opentelemetry/sdk'
 require 'opentelemetry-test-helpers'
+require 'opentelemetry-metrics-sdk'
 
 module RspecOtel
   def self.exporter
     @exporter ||= OpenTelemetry::SDK::Trace::Export::InMemorySpanExporter.new
   end
 
+  def self.metric_exporter
+    @metric_exporter ||= OpenTelemetry::SDK::Metrics::Export::InMemoryMetricPullExporter.new
+  end
+
   def self.record
     span_processor = OpenTelemetry::SDK::Trace::Export::SimpleSpanProcessor.new(exporter)
 
@@ -15,6 +20,10 @@ module RspecOtel
       c.add_span_processor span_processor
     end
 
+    meter_provider = OpenTelemetry::SDK::Metrics::MeterProvider.new
+    meter_provider.add_metric_reader(metric_exporter)
+    OpenTelemetry.meter_provider = meter_provider
+
     yield
   ensure
     reset
@@ -22,7 +31,9 @@ module RspecOtel
 
   def self.reset
     OpenTelemetry::TestHelpers.reset_opentelemetry
+    OpenTelemetry.meter_provider = OpenTelemetry::Internal::ProxyMeterProvider.new
     @exporter = nil
+    @metric_exporter = nil
   end
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rspec-otel
 version: !ruby/object:Gem::Version
-  version: 0.0.7
+  version: 0.1.0
 platform: ruby
 authors:
 - Damien MATHIEU
@@ -9,6 +9,20 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: opentelemetry-api
   requirement: !ruby/object:Gem::Requirement
@@ -23,6 +37,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-metrics-sdk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.12'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.12'
 - !ruby/object:Gem::Dependency
   name: opentelemetry-sdk
   requirement: !ruby/object:Gem::Requirement
@@ -76,7 +104,10 @@ files:
 - README.md
 - lib/rspec_otel.rb
 - lib/rspec_otel/matchers.rb
+- lib/rspec_otel/matchers/emit_metric.rb
 - lib/rspec_otel/matchers/emit_span.rb
+- lib/rspec_otel/matchers/metric_details.rb
+- lib/rspec_otel/matchers/span_details.rb
 - lib/rspec_otel/rspec.rb
 - lib/rspec_otel/version.rb
 homepage: https://github.com/dmathieu/rspec-otel
@@ -98,7 +129,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.6
 specification_version: 4
 summary: RSpec matchers for the OpenTelemetry framework
 test_files: []