prometheus_exporter-ext 0.2.4 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e47f266c5bc957436f07c63c88f870e2eafe2744d358f762d291ed8b58b5aad5
-  data.tar.gz: 1a62ac477d59603197c5076f2d0b42e0f0bccaaa8082d509eec46bd7df547cc8
+  metadata.gz: 9f48189e693644e88572d2c0e53d88b5e3b24ff0d5fbf5a81ab83917a9a33611
+  data.tar.gz: 54899812b42e64fd0de8b68bde3ac516be1312d0d83bec943aa1aac6b61c93ae
 SHA512:
-  metadata.gz: 2475868468870c9ec5ce1fd819fc125c3ba22718df62c11ef5da6c27295d87ccbbeaf4aef7676bb7e52c43cdb786a25410f20cbabcad1e379048bc4767806a37
-  data.tar.gz: 8c83ba275e8f4233fccc3a55b7c4a069ded287880dc431680b736159d124bf8bb6a5dd0642547484b050f97e4ac47c5e8a1360850cd23f3e1185c89253c76832
+  metadata.gz: 293fff8a0de37c36dcfbec873546b8416443ac6717eaf2c1c112104a8bd117a115ccf9af9a793e3bb92d243cbe88e8709763b109deec2628b88f1f44651c4da9
+  data.tar.gz: 85f241c1fd687dd12648b37bba25d6608353ac0e8f493427ed870500ced02e3eb6931271b1b5023d86d4d3c1467bdefe8e58fbb339aef6a15801154e863707fe

data/CHANGELOG.md

@@ -0,0 +1,28 @@
+## [Unreleased]
+
+## [0.3.2] - 2026-06-11
+- fix gemspec missing `spec.files` so the published gem actually ships its source files (0.3.1 and earlier shipped empty)
+
+## [0.3.1] - 2024-05-04
+- ProcCpu add hostname label
+
+## [0.3.0] - 2024-05-04
+- replace ProcStat with ProcCpu
+
+## [0.2.4] - 2024-05-03
+- add PrometheusExporter::Ext::Server::ProcStatCollector
+
+## [0.2.3] - 2024-05-03
+- add PrometheusExporter::Ext::Instrumentation::ProcStat
+
+## [0.2.2] - 2023-12-08
+- fix send_metrics RSpec matcher
+
+## [0.2.1] - 2023-12-06
+- add gauge_with_expire, add tests, update readme
+
+## [0.2.0] - 2023-12-06
+- remove gauge_with_time, add expired_stats_collector, add tests
+
+## [0.1.0] - 2023-11-26
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 Denis Talakevich
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,273 @@
+# PrometheusExporter::Ext
+
+![Tests](https://github.com/didww/prometheus_exporter-ext/workflows/Tests/badge.svg)
+
+Extension for [Ruby Prometheus Exporter](https://github.com/discourse/prometheus_exporter).
+Adds DSL for building your custom Prometheus instrumentations and collectors.
+Allow to remove/zero expired gauge metrics in a collector.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add prometheus_exporter-ext
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install prometheus_exporter-ext
+
+## Usage
+
+### When metrics should be send on particular event
+create instrumentation
+```ruby
+# lib/prometheus/my_instrumentation.rb
+require 'prometheus_exporter/ext'
+require 'prometheus_exporter/ext/instrumentation/base_stats'
+
+module Prometheus
+  class MyInstrumentation < ::PrometheusExporter::Ext::Instrumentation::BaseStats
+    self.type = 'my'
+
+    def collect(duration, operation)
+      collect_data(
+        labels: { operation_name: operation },
+        last_duration_seconds: duration,
+        duration_seconds_sum: duration,
+        duration_seconds_count: 1
+      )
+    rescue StandardError => e
+      Rails.logger.error("Failed to send metrics Prometheus #{self.class.name} #{e}")
+      Rails.error.report(e, handled: true, severity: :error, context: { prometheus: self.class.name })
+    end
+  end
+end
+```
+
+then send metrics from your code
+```ruby
+  time_start = Time.current.to_i
+begin
+  MyOperation.run
+ensure
+  duration = Time.current.to_i - time_start
+  Prometheus::MyInstrumentation.new.collect(duration, 'my_operation')
+  ## you can add additional labels or override client
+  Prometheus::MyInstrumentation.new(
+    client: PrometheusExporter::Client.new(...),
+    labels: { foo: 'bar' }
+  ).collect(duration)
+end
+```
+
+so metrics will be collected by
+```ruby
+require 'prometheus_exporter/ext'
+require 'prometheus_exporter/ext/server/stats_collector'
+
+module Prometheus
+  class MyCollector < ::PrometheusExporter::Server::TypeCollector
+    include ::PrometheusExporter::Ext::Server::StatsCollector
+    self.type = 'my'
+
+    # The `register_gauge_with_expire` will remove or zero expired metric.
+    # when no :strategy option passed, default is `:removing`, available options are `:removing, :zeroing`.
+    # when no :ttl option passed, default is 60, any numeric greater than 0 can be used.
+    register_gauge_with_expire :last_duration_seconds, 'duration of last operation execution', ttl: 300
+    
+    register_counter :task_duration_seconds_sum, 'sum of operation execution durations'
+    register_counter :task_duration_seconds_count, 'sum of operation execution runs'
+  end
+end
+```
+
+as alternative you can use `ExpiredStatsCollector` if you want all metric data to be removed after expiration
+```ruby
+require 'prometheus_exporter/ext'
+require 'prometheus_exporter/ext/server/stats_collector'
+
+module Prometheus
+  class MyCollector < ::PrometheusExporter::Server::TypeCollector
+    include ::PrometheusExporter::Ext::Server::ExpiredStatsCollector
+    self.type = 'my'
+    self.ttl = 300 # default 60
+    
+    # Optionally you can expire old_metric when specific new metric is collected.
+    # If this block returns true then old_metric will be removed.
+    unique_metric_by do |new_metric, old_metric|
+      new_metric['labels'] == old_metric['labels']
+    end
+
+    register_gauge :last_duration_seconds, 'duration of last operation execution'
+    register_counter :task_duration_seconds_sum, 'sum of operation execution durations'
+    register_counter :task_duration_seconds_count, 'sum of operation execution runs'
+  end
+end
+````
+
+### When metrics should be send periodically with given frequency
+create instrumentation
+```ruby
+# lib/prometheus/my_instrumentation.rb
+require 'prometheus_exporter/ext'
+require 'prometheus_exporter/ext/instrumentation/periodic_stats'
+
+module Prometheus
+  class MyPeriodicInstrumentation < ::PrometheusExporter::Ext::Instrumentation::PeriodicStats
+    self.type = 'my'
+
+    def collect
+      count = MyItem.processed.count
+      last_duration = MyItem.processed.last&.duration
+      collect_data(
+        labels: { some_label: 'some_value' },
+        last_processed_duration: last_duration || 0,
+        processed_count: count
+      )
+    rescue StandardError => e
+      Rails.logger.error("Failed to send metrics Prometheus #{self.class.name} #{e}")
+      Rails.error.report(e, handled: true, severity: :error, context: { prometheus: self.class.name })
+    end
+  end
+end
+```
+
+then send metrics from your code
+```ruby
+Prometheus::MyInstrumentation.start
+## you can override frequency in seconds
+Prometheus::MyInstrumentation.start(frequency: 60)
+## also you can add additional labels or override client
+Prometheus::MyInstrumentation.start(
+  client: PrometheusExporter::Client.new(...),
+  labels: { foo: 'bar' }
+)
+# to stop instrumentation call `Prometheus::MyInstrumentation.stop`
+```
+
+so metrics will be collected by
+```ruby
+require 'prometheus_exporter/ext'
+require 'prometheus_exporter/ext/server/stats_collector'
+
+module Prometheus
+  class MyCollector < ::PrometheusExporter::Server::TypeCollector
+    include ::PrometheusExporter::Ext::Server::StatsCollector
+    self.type = 'my'
+    
+    # Default ttl 60, default strategy `:removing`.
+    register_gauge_with_expire :last_processed_duration, 'duration of last processed record'
+    register_metric :processed_count, :gauge_with_time, 'count of processed records'
+  end
+end
+```
+
+as alternative you can use `ExpiredStatsCollector` if you want all metric data to be removed after expiration
+```ruby
+require 'prometheus_exporter/ext'
+require 'prometheus_exporter/ext/server/stats_collector'
+
+module Prometheus
+  class MyCollector < ::PrometheusExporter::Server::TypeCollector
+    include ::PrometheusExporter::Ext::Server::ExpiredStatsCollector
+    self.type = 'my'
+    # By default ttl is 60
+    # By default deletes old metrics only when it's expired
+
+    register_gauge :last_processed_duration, 'duration of last processed record'
+    register_metric :processed_count, :gauge_with_time, 'count of processed records'
+  end
+end
+````
+
+### You also can easily test your instrumentations and collectors using new matchers
+
+instrumentation test
+```ruby
+require 'prometheus_exporter/ext/rspec'
+
+RSpec.describe Prometheus::MyInstrumentation do
+  describe '#collect' do
+    subject { described_class.new.collect(duration, operation) }
+    let(:duration) { 1.23 }
+    let(:operation) { 'test' }
+
+    it 'sends prometheus metrics' do
+      expect { subject }.to send_metrics(
+        [
+          type: 'my',
+          labels: { operation_name: operation },
+          last_duration_seconds: duration,
+          duration_seconds_sum: duration,
+          duration_seconds_count: 1
+        ]
+      )
+    end
+  end
+end
+```
+
+collector test
+```ruby
+RSpec.describe Prometheus::MyCollector do
+  describe '#collect' do
+    subject do
+      collector.metrics
+    end
+
+    let(:collector) { described_class.new }
+    let(:metric) do
+      {
+        type: 'my',
+        labels: { operation_name: 'test' },
+        last_duration_seconds: 1.2,
+        duration_seconds_sum: 3.4,
+        duration_seconds_count: 1
+      }
+    end
+    
+    let(:collect_data) do
+      collector.collect(metric.deep_stringify_keys)
+    end
+
+    it 'observes prometheus metrics' do
+      subject
+      expect(collector.metrics).to contain_exactly(
+        a_gauge_with_expire_metric('my_last_duration_seconds').with(1.2, metric[:labels]),
+        a_counter_metric('my_duration_seconds_sum').with(3.4, metric[:labels]),
+        a_counter_metric('my_duration_seconds_count').with(1, metric[:labels])
+      )
+    end
+    
+    context 'when collected data is expired' do
+      let(:collect_data) do
+        super()
+        sleep 60.1 # when gauge_with_expire ttl is 60
+      end
+
+      it 'observes empty prometheus metrics' do
+        subject
+        expect(collector.metrics).to contain_exactly(
+          a_gauge_with_expire_metric('my_last_duration_seconds').empty,
+          a_counter_metric('my_duration_seconds_sum').with(3.4, metric[:labels]),
+          a_counter_metric('my_duration_seconds_count').with(1, metric[:labels])
+        )
+      end
+    end
+  end
+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 the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/didww/prometheus_exporter-ext.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: [:spec, :rubocop]

data/lib/prometheus_exporter/ext/instrumentation/base_stats.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'prometheus_exporter/client'
+require_relative '../../ext'
+
+module PrometheusExporter::Ext::Instrumentation
+  class BaseStats
+    class << self
+      attr_accessor :type
+    end
+
+    def initialize(client: PrometheusExporter::Client.default, labels: {})
+      @labels = labels.transform_keys(&:to_sym)
+      @client = client
+    end
+
+    def type
+      self.class.type
+    end
+
+    def collect
+      raise NotImplementedError
+    end
+
+    private
+
+    # @param data [Array,Hash]
+    def collect_data(data)
+      data_list = data.is_a?(Array) ? data : [data]
+      metrics = data_list.map { |data_item| build_metric(data_item) }
+      metrics.map { |metric| @client.send_json(metric) }
+    end
+
+    # @param data [Hash]
+    # @return [Hash]
+    def build_metric(data)
+      metric = data.transform_keys(&:to_sym)
+      metric[:type] = type
+      metric[:labels] ||= {}
+      metric[:labels].transform_keys!(&:to_sym)
+      metric[:labels].merge!(@labels)
+      metric
+    end
+  end
+end

data/lib/prometheus_exporter/ext/instrumentation/periodic_stats.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative 'base_stats'
+
+module PrometheusExporter::Ext::Instrumentation
+  class PeriodicStats < BaseStats
+    class << self
+      def start(frequency: 30, client: PrometheusExporter::Client.default, **)
+        raise ArgumentError, 'Expected frequency to be a number' unless frequency.is_a?(Numeric)
+        raise ArgumentError, 'Expected frequency to be a positive number' if frequency.negative?
+
+        klass = self
+        stop
+        instrumentation = new(client:, **)
+        @stop_thread = false
+
+        @thread = Thread.new do
+          until @stop_thread
+            begin
+              instrumentation.collect
+            rescue StandardError => e
+              client.logger.error("#{klass} Prometheus Exporter Failed To Collect Stats")
+              client.logger.error("#{e.class} #{e.backtrace&.join("\n")}")
+            ensure
+              sleep frequency
+            end
+          end
+        end
+      end
+
+      def started?
+        !!@thread&.alive?
+      end
+
+      def stop
+        # to avoid a warning
+        @thread = nil unless defined?(@thread)
+
+        if @thread&.alive?
+          @stop_thread = true
+          @thread.wakeup
+          @thread.join
+        end
+        @thread = nil
+      end
+    end
+  end
+end

data/lib/prometheus_exporter/ext/instrumentation/proc_cpu.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative 'periodic_stats'
+require_relative '../proc_self_stat'
+
+module PrometheusExporter::Ext::Instrumentation
+  class ProcCpu < PeriodicStats
+    self.type = 'proc_cpu'
+
+    class << self
+      def start(type:, labels: {}, **)
+        labels = labels.merge(type:)
+
+        super(labels:, **)
+      end
+    end
+
+    def initialize(...)
+      @last_cpu_time = 0.0
+      super
+    end
+
+    def collect
+      stat = PrometheusExporter::Ext::ProcSelfStat.get
+      collect_data(
+        labels: {
+          pid: stat.pid,
+          hostname: ::PrometheusExporter.hostname
+        },
+        usage_seconds_total: stat.cpu_time - @last_cpu_time
+      )
+      @last_cpu_time = stat.cpu_time
+    end
+  end
+end

data/lib/prometheus_exporter/ext/metric/gauge_with_expire.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require 'prometheus_exporter/metric'
+require_relative '../../ext'
+
+module PrometheusExporter::Ext::Metric
+  class GaugeWithExpire < PrometheusExporter::Metric::Gauge
+    NULLIFY_STRATEGY_UPDATE = ->(labels) { expiration_times[labels] = now_time + ttl }.freeze
+    NULLIFY_STRATEGY_EXPIRE = ->(labels) { data.delete(labels) }.freeze
+    ZEROING_STRATEGY_UPDATE = ->(labels) do
+      if data[labels].zero?
+        expiration_times.delete(labels)
+      else
+        expiration_times[labels] = now_time + ttl
+      end
+    end.freeze
+    ZEROING_STRATEGY_EXPIRE = ->(labels) { data[labels] = 0 }.freeze
+
+    class << self
+      # @return [Hash]
+      #   key - strategy name
+      #   value [Hash] with keys: :on_update, :on_expire
+      #     :on_update [Proc] yieldparam labels [Hash] - updates expiration_times after data was updated (instance exec)
+      #     :on_expire [Proc] yieldparam labels [Hash] - updates data after expiration_times was expired (instance exec)
+      def strategies
+        {
+          removing: { on_update: NULLIFY_STRATEGY_UPDATE, on_expire: NULLIFY_STRATEGY_EXPIRE },
+          zeroing: { on_update: ZEROING_STRATEGY_UPDATE, on_expire: ZEROING_STRATEGY_EXPIRE }
+        }
+      end
+
+      def default_ttl
+        60
+      end
+    end
+
+    attr_reader :ttl, :expiration_times
+
+    def initialize(name, help, opts = {})
+      super(name, help)
+      @ttl = opts[:ttl] || self.class.default_ttl
+      raise ArgumentError, ':ttl must be numeric' unless ttl.is_a?(Numeric)
+      raise ArgumentError, ":ttl must be greater than zero: #{ttl.inspect}" unless ttl.positive?
+
+      @strategy = self.class.strategies.fetch(opts[:strategy] || :removing) do
+        raise ArgumentError, "Unknown strategy: #{opts[:strategy].inspect}"
+      end
+    end
+
+    def reset!
+      @expiration_times = {}
+      super
+    end
+
+    def metric_text
+      expire
+      super
+    end
+
+    def remove(labels)
+      result = super
+      remove_expired_at(labels)
+      result
+    end
+
+    def observe(value, labels = {})
+      result = super
+      value.nil? ? remove_expired_at(labels) : update_expired_at(labels)
+      result
+    end
+
+    def increment(labels = {}, value = 1)
+      result = super
+      update_expired_at(labels)
+      result
+    end
+
+    def decrement(labels = {}, value = 1)
+      result = super
+      update_expired_at(labels)
+      result
+    end
+
+    def expire
+      now = now_time
+      expiration_times.each do |labels, expired_at|
+        if expired_at < now
+          remove_data_when_expired(labels)
+          remove_expired_at(labels)
+        end
+      end
+    end
+
+    def to_h
+      expire
+      super
+    end
+
+    private
+
+    def remove_data_when_expired(labels)
+      instance_exec(labels, &@strategy[:on_expire])
+    end
+
+    def update_expired_at(labels)
+      instance_exec(labels, &@strategy[:on_update])
+    end
+
+    def remove_expired_at(labels)
+      expiration_times.delete(labels)
+    end
+
+    def now_time
+      ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/prometheus_exporter/ext/proc_self_stat.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module PrometheusExporter::Ext
+  # https://man7.org/linux/man-pages/man5/proc_pid_stat.5.html
+  class ProcSelfStat
+    KERNEL_PAGE_SIZE = `getconf PAGESIZE`.chomp.to_i rescue 4096 # rubocop:disable Style/RescueModifier
+    TICKS_PER_SEC = Etc.sysconf(Etc::SC_CLK_TCK)
+
+    class << self
+      def get
+        stat = File.read('/proc/self/stat')
+        parts = stat.match(/\A(\d+)\s\((.*)\)\s([A-Z])\s(.*)/)[1..]
+        rest = parts.pop.split
+        new(*parts, *rest)
+      end
+    end
+
+    attr_reader :pid,
+                :comm,
+                :state,
+                :utime,
+                :stime,
+                :starttime,
+                :vsize,
+                :rss
+
+    def initialize(*fields)
+      @pid = fields[0]
+      @comm = fields[1]
+      @state = fields[2]
+      @utime = Integer(fields[13])
+      @stime = Integer(fields[14])
+      @starttime = Integer(fields[21])
+      @vsize = Integer(fields[22])
+      @rss = Integer(fields[23])
+      @fields = fields
+    end
+
+    # @return [Float]
+    def cpu_time
+      (utime + stime).to_f / TICKS_PER_SEC
+    end
+
+    # @return [Integer]
+    def rss_bytes
+      rss * KERNEL_PAGE_SIZE
+    end
+
+    def to_a
+      @fields.dup
+    end
+
+    def to_h
+      {
+        pid:,
+        comm:,
+        state:,
+        utime:,
+        stime:,
+        starttime:,
+        vsize:,
+        rss:
+      }
+    end
+
+    def to_s
+      "#<#{self.class.name} #{to_h.map { |k, v| "#{k}=#{v.inspect}" }.join(' ')}>"
+    end
+
+    def inspect
+      to_s
+    end
+  end
+end

data/lib/prometheus_exporter/ext/rspec/matchers.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'date'
+require_relative 'metric_matcher'
+require_relative 'send_metrics_matcher'
+
+module PrometheusExporter::Ext::RSpec
+  module Matchers
+    def send_metrics(*expected)
+      expected = nil if expected.empty?
+      PrometheusExporter::Ext::RSpec::SendMetricsMatcher.new(expected)
+    end
+
+    def a_prometheus_metric(klass, name)
+      MetricMatcher.new(klass, name)
+    end
+
+    def a_gauge_metric(name)
+      a_prometheus_metric(PrometheusExporter::Metric::Gauge, name)
+    end
+
+    def a_gauge_with_expire_metric(name)
+      a_prometheus_metric(PrometheusExporter::Ext::Metric::GaugeWithExpire, name)
+    end
+
+    def a_counter_metric(name)
+      a_prometheus_metric(PrometheusExporter::Metric::Counter, name)
+    end
+
+    def a_histogram_metric(name)
+      a_prometheus_metric(PrometheusExporter::Metric::Histogram, name)
+    end
+
+    def a_summary_metric(name)
+      a_prometheus_metric(PrometheusExporter::Metric::Summary, name)
+    end
+  end
+end

data/lib/prometheus_exporter/ext/rspec/metric_matcher.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module PrometheusExporter::Ext::RSpec
+  class MetricMatcher
+    include RSpec::Matchers::DSL::DefaultImplementations
+    include RSpec::Matchers
+    include RSpec::Matchers::Composable
+
+    attr_reader :metric_class, :metric_name, :metric_payload, :actual
+
+    def initialize(metric_class, metric_name)
+      @metric_class = metric_class
+      @metric_name = metric_name.to_s
+      @metric_payload = nil
+    end
+
+    def name
+      'be a prometheus metric'
+    end
+
+    def expected
+      "#{metric_class}(name=#{metric_name}, to_h=#{description_of(metric_payload)})"
+    end
+
+    def matches?(actual)
+      @actual = actual
+
+      return false unless values_match?(metric_class, actual.class)
+      return false unless values_match?(metric_name, actual.name.to_s)
+
+      actual_payload = actual.to_h.transform_keys { |labels| labels.transform_keys(&:to_s) }
+      return false if !metric_payload.nil? && !values_match?(metric_payload, actual_payload)
+
+      true
+    end
+
+    def with(value, labels)
+      @metric_payload ||= {}
+      metric_payload[labels.transform_keys(&:to_s)] = value
+      self
+    end
+
+    def empty
+      @metric_payload = {}
+      self
+    end
+
+    def description_of(object)
+      RSpec::Support::ObjectFormatter.new(nil).format(object)
+    end
+  end
+end

data/lib/prometheus_exporter/ext/rspec/send_metrics_matcher.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module PrometheusExporter::Ext::RSpec
+  class SendMetricsMatcher
+    include RSpec::Matchers::DSL::DefaultImplementations
+    include RSpec::Matchers
+    include RSpec::Matchers::Composable
+
+    attr_reader :expected, :actual
+
+    # @param expected [Array<Hash(Symbol)>,nil]
+    def initialize(expected)
+      @expected = expected
+      @ordered = false
+      @times = nil
+    end
+
+    def name
+      'sends metrics to prometheus'
+    end
+
+    def supports_block_expectations?
+      true
+    end
+
+    def matches?(actual_proc)
+      raise ArgumentError, "#{name} matcher supports only block expectations" unless actual_proc.is_a?(Proc)
+
+      metrics_before = PrometheusExporter::Ext::RSpec::TestClient.instance.metrics
+      actual_proc.call
+      metrics_after = PrometheusExporter::Ext::RSpec::TestClient.instance.metrics - metrics_before
+      @actual = metrics_after.map { |metric| deep_symbolize_keys(metric) }
+
+      if expected
+        expected_value = @ordered ? expected : match_array(expected)
+        values_match?(expected_value, actual)
+      elsif @times
+        values_match?(@times, actual.size)
+      else
+        actual.size >= 1
+      end
+    end
+
+    def failure_message
+      if expected
+        expected_value = @ordered ? expected : match_array(expected)
+        +"expected #{name} to receive #{description_of(expected_value)}, but got\n    #{description_of(actual)}"
+      elsif @times
+        values_match?(@times, actual.size)
+        +"expected #{name} to receive #{@times} metrics, but got #{actual.size}\n    #{description_of(actual)}"
+      else
+        actual.size
+        +"expected #{name} to receive more than 1 metric, but got #{actual.size}\n    #{description_of(actual)}"
+      end
+    end
+
+    def ordered
+      raise ArgumentError, 'ordered cannot be when expected not provided' if expected.nil?
+      raise ArgumentError, 'ordered cannot be used with times' if @times
+
+      @ordered = true
+      self
+    end
+
+    def times(qty)
+      raise ArgumentError, 'times argument must be an integer' unless qty.is_a?(Integer)
+      raise ArgumentError, 'times argument must be >= 1' unless qty >= 1
+      raise ArgumentError, 'ordered cannot be when expected is provided' unless expected.nil?
+      raise ArgumentError, 'ordered cannot be used with times' if @ordered
+
+      @times = qty
+      self
+    end
+
+    def description_of(object)
+      RSpec::Support::ObjectFormatter.new(nil).format(object)
+    end
+
+    private
+
+    def deep_symbolize_keys(hash)
+      new_hash = {}
+      hash.each do |k, v|
+        new_hash[k.to_sym] = v.is_a?(Hash) ? deep_symbolize_keys(v) : v
+      end
+      new_hash
+    end
+  end
+end

data/lib/prometheus_exporter/ext/rspec/test_client.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'singleton'
+
+module PrometheusExporter::Ext::RSpec
+  class TestClient
+    include Singleton
+
+    def initialize
+      super
+      reset
+    end
+
+    def metrics
+      @metrics.dup
+    end
+
+    def send_json(data)
+      @metrics << data
+    end
+
+    def reset
+      @metrics = []
+    end
+
+    def stop
+      nil
+    end
+  end
+end

data/lib/prometheus_exporter/ext/rspec.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'prometheus_exporter/client'
+require_relative 'rspec/matchers'
+require_relative 'rspec/test_client'
+
+# Setups default client before it used anywhere.
+# use `include_examples :observes_prometheus_metrics` in specs
+PrometheusExporter::Client.default = PrometheusExporter::Ext::RSpec::TestClient.instance
+
+RSpec.configure do |config|
+  config.include PrometheusExporter::Ext::RSpec::Matchers
+
+  config.before do
+    PrometheusExporter::Ext::RSpec::TestClient.instance.reset
+  end
+end

data/lib/prometheus_exporter/ext/server/base_collector_methods.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require 'prometheus_exporter/metric'
+require_relative '../metric/gauge_with_expire'
+
+module PrometheusExporter::Ext::Server
+  module BaseCollectorMethods
+    class << self
+      private
+
+      def included(klass)
+        super
+        klass.singleton_class.attr_accessor :type, :registered_metrics
+        klass.registered_metrics = {}
+        klass.extend ClassMethods
+      end
+    end
+
+    module ClassMethods
+      # Registers metric observer.
+      # @param name [Symbol] metric name.
+      # @param help [String] metric description.
+      # @param metric_class [Class<PrometheusExporter::Metric::Base>] observer class.
+      # @param args [Array] additional arguments for observer class.
+      # rubocop:disable Metrics/ParameterLists
+      def register_metric(name, help, metric_class, *args)
+        # rubocop:enable Metrics/ParameterLists
+        name = name.to_s
+        raise ArgumentError, "metric #{name} is already registered" if registered_metrics.key?(name)
+
+        registered_metrics[name] = { help:, metric_class:, args: }
+      end
+
+      # Registers PrometheusExporter::Metric::Counter observer.
+      # @param name [Symbol] metric name.
+      # @param help [String] metric description.
+      def register_counter(name, help)
+        register_metric(name, help, PrometheusExporter::Metric::Counter)
+      end
+
+      # Registers PrometheusExporter::Metric::Gauge observer.
+      # @param name [Symbol] metric name.
+      # @param help [String] metric description.
+      def register_gauge(name, help)
+        register_metric(name, help, PrometheusExporter::Metric::Gauge)
+      end
+
+      # Registers PrometheusExporter::Metric::Summary observer.
+      # @param name [Symbol] metric name.
+      # @param help [String] metric description.
+      # @param opts [Hash] additional options, supports `quantiles` key.
+      def register_summary(name, help, opts = {})
+        register_metric(name, help, PrometheusExporter::Metric::Summary, opts)
+      end
+
+      # Registers PrometheusExporter::Metric::Histogram observer.
+      # @param name [Symbol] metric name.
+      # @param help [String] metric description.
+      # @param opts [Hash] additional options, supports `buckets` key.
+      def register_histogram(name, help, opts = {})
+        register_metric(name, help, PrometheusExporter::Metric::Histogram, opts)
+      end
+    end
+
+    # @return [String]
+    def type
+      self.class.type
+    end
+
+    private
+
+    # Adds metrics to observers with matched name.
+    # @param observers [Hash] returned by #build_observers.
+    # @param obj [Hash] metric data.
+    def fill_observers(observers, obj)
+      observers.each do |name, observer|
+        value = obj[name]
+        observer.observe(value, obj['labels']) if value
+      end
+    end
+
+    # Generally metrics sent via PrometheusExporter::Ext::Instrumentation::BaseStats populate labels to `labels` key.
+    # But PrometheusExporter::Client populate it's own labels to `custom_labels` key.
+    # Here we merge them into single `labels` key.
+    # @param obj [Hash]
+    # @return [Hash]
+    def normalize_labels(obj)
+      obj['labels'] ||= {}
+      custom_labels = obj.delete('custom_labels')
+      obj['labels'].merge!(custom_labels) if custom_labels
+      obj
+    end
+
+    # @return [Hash] key is metric name, value is observer.
+    def build_observers
+      observers = {}
+      self.class.registered_metrics.each do |name, metric|
+        observers[name] = metric[:metric_class].new("#{type}_#{name}", metric[:help], *metric[:args])
+      end
+      observers
+    end
+  end
+end

data/lib/prometheus_exporter/ext/server/expired_stats_collector.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'prometheus_exporter/server/metrics_container'
+require_relative 'base_collector_methods'
+
+module PrometheusExporter::Ext::Server
+  module ExpiredStatsCollector
+    class << self
+      private
+
+      def included(klass)
+        super
+        klass.include BaseCollectorMethods
+        klass.singleton_class.attr_accessor :filter, :ttl
+        klass.ttl = 60
+        klass.extend ClassMethods
+      end
+    end
+
+    module ClassMethods
+      # Defines a rule how old metric will be replaced with new one.
+      # @yield compare new metric with existing one.
+      # @yieldparam new_metric [Hash] new metric data.
+      # @yieldparam old_metric [Hash] existing metric data.
+      # @yieldreturn [Boolean] if true existing metric will be replaced with new one.
+      def unique_metric_by(&block)
+        @filter = block
+      end
+    end
+
+    def initialize
+      super
+      @data = PrometheusExporter::Server::MetricsContainer.new(
+        ttl: self.class.ttl,
+        filter: self.class.filter
+      )
+    end
+
+    # Returns all metrics collected by this collector.
+    # @return [Array<PrometheusExporter::Metric::Base>]
+    def metrics
+      observers = build_observers
+      @data.each do |obj|
+        fill_observers(observers, obj)
+      end
+
+      observers.values
+    end
+
+    # Collects metric data received from client.
+    # @param obj [Hash] metric data.
+    def collect(obj)
+      normalize_labels(obj)
+      @data << obj
+    end
+  end
+end

data/lib/prometheus_exporter/ext/server/proc_cpu_collector.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative 'stats_collector'
+
+module PrometheusExporter::Ext::Server
+  class ProcCpuCollector < PrometheusExporter::Server::TypeCollector
+    include ::PrometheusExporter::Ext::Server::StatsCollector
+    self.type = 'proc_cpu'
+
+    register_counter :usage_seconds_total, 'Cumulative CPU time consumed by the process in core-seconds'
+  end
+end

data/lib/prometheus_exporter/ext/server/singleton_web_server.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'prometheus_exporter/server/web_server'
+require_relative '../../ext'
+
+module PrometheusExporter::Ext::Server
+  class SingletonWebServer < PrometheusExporter::Server::WebServer
+    class << self
+      attr_accessor :server
+
+      def start(opts)
+        self.server = new(opts)
+        server.start
+      end
+
+      def stop
+        server.stop
+        self.server = nil
+      end
+
+      def build_htpasswd(htpasswd_path, username:, password:)
+        htpasswd = WEBrick::HTTPAuth::Htpasswd.new(htpasswd_path)
+        htpasswd.set_passwd PrometheusExporter::DEFAULT_REALM, username, password
+        htpasswd.flush
+      end
+
+      # @yieldparam collector [PrometheusExporter::Server::Collector]
+      def configure_collector
+        yield server.collector
+      end
+    end
+  end
+end

data/lib/prometheus_exporter/ext/server/stats_collector.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative 'base_collector_methods'
+
+module PrometheusExporter::Ext::Server
+  module StatsCollector
+    class << self
+      private
+
+      def included(klass)
+        super
+        klass.include BaseCollectorMethods
+        klass.extend ClassMethods
+      end
+    end
+
+    module ClassMethods
+      # Registers PrometheusExporter::Metric::GaugeWithExpire observer.
+      # @param name [Symbol] metric name.
+      # @param help [String] metric description.
+      # @param opts [Hash] additional options, supports `ttl` and `strategy` keys.
+      def register_gauge_with_expire(name, help, opts = {})
+        register_metric(name, help, PrometheusExporter::Ext::Metric::GaugeWithExpire, opts)
+      end
+    end
+
+    def initialize
+      super
+      @observers = build_observers
+    end
+
+    # Returns all metrics collected by this collector.
+    # @return [Array<PrometheusExporter::Metric::Base>]
+    def metrics
+      @observers.values
+    end
+
+    # Collects metric data received from client.
+    # @param obj [Hash] metric data.
+    def collect(obj)
+      obj = normalize_labels(obj)
+      fill_observers(@observers, obj)
+    end
+  end
+end

data/lib/prometheus_exporter/ext/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module PrometheusExporter
+  module Ext
+    VERSION = '0.3.2'
+  end
+end

data/lib/prometheus_exporter/ext.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative 'ext/version'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: prometheus_exporter-ext
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.3.2
 platform: ruby
 authors:
 - Denis Talakevich
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-05-03 00:00:00.000000000 Z
+date: 2026-06-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: prometheus_exporter
@@ -30,7 +30,28 @@ email:
 executables: []
 extensions: []
 extra_rdoc_files: []
-files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/prometheus_exporter/ext.rb
+- lib/prometheus_exporter/ext/instrumentation/base_stats.rb
+- lib/prometheus_exporter/ext/instrumentation/periodic_stats.rb
+- lib/prometheus_exporter/ext/instrumentation/proc_cpu.rb
+- lib/prometheus_exporter/ext/metric/gauge_with_expire.rb
+- lib/prometheus_exporter/ext/proc_self_stat.rb
+- lib/prometheus_exporter/ext/rspec.rb
+- lib/prometheus_exporter/ext/rspec/matchers.rb
+- lib/prometheus_exporter/ext/rspec/metric_matcher.rb
+- lib/prometheus_exporter/ext/rspec/send_metrics_matcher.rb
+- lib/prometheus_exporter/ext/rspec/test_client.rb
+- lib/prometheus_exporter/ext/server/base_collector_methods.rb
+- lib/prometheus_exporter/ext/server/expired_stats_collector.rb
+- lib/prometheus_exporter/ext/server/proc_cpu_collector.rb
+- lib/prometheus_exporter/ext/server/singleton_web_server.rb
+- lib/prometheus_exporter/ext/server/stats_collector.rb
+- lib/prometheus_exporter/ext/version.rb
 homepage: https://github.com/senid231/prometheus_exporter-ext
 licenses:
 - MIT
@@ -54,7 +75,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.6
+rubygems_version: 3.5.16
 signing_key:
 specification_version: 4
 summary: Extended Prometheus Exporter for Ruby