phobos_prometheus 0.3.2

data/Rakefile

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

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'phobos_prometheus'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require 'irb'
+IRB.start(__FILE__)

data/config/phobos_prometheus.yml.example

@@ -0,0 +1,46 @@
+metrics_prefix: phobos_app
+
+counters:
+  - instrumentation: listener.process_message
+  - instrumentation: listener.process_batch
+
+histograms:
+  - instrumentation: listener.process_message
+    bucket_name: message
+  - instrumentation: listener.process_batch
+    bucket_name: batch
+
+gauges:
+  - label: number_of_handlers
+    increment: listener.start_handler
+    decrement: listener.stop_handler
+
+buckets:
+  - name: message
+    bins:
+      - 2
+      - 4
+      - 8
+      - 16
+      - 32
+      - 64
+      - 128
+      - 256
+      - 512
+      - 1024
+      - 2048
+      - 4096
+  - name: batch
+    bins:
+      - 64
+      - 128
+      - 256
+      - 512
+      - 1024
+      - 2048
+      - 4096
+      - 8192
+      - 16384
+      - 32768
+      - 65536
+      - 131072

data/lib/phobos_prometheus.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require 'ostruct'
+require 'yaml'
+
+require 'phobos'
+require 'prometheus/client'
+require 'prometheus/client/formats/text'
+require 'sinatra/base'
+
+require 'phobos_prometheus/version'
+require 'phobos_prometheus/errors'
+require 'phobos_prometheus/logger'
+require 'phobos_prometheus/config_parser'
+require 'phobos_prometheus/collector/helper'
+require 'phobos_prometheus/collector/error_logger'
+require 'phobos_prometheus/collector/histogram'
+require 'phobos_prometheus/collector/counter'
+require 'phobos_prometheus/collector/gauge'
+require 'phobos_prometheus/collector'
+require 'phobos_prometheus/exporter_helper'
+require 'phobos_prometheus/exporter'
+
+# Prometheus collector for Phobos
+module PhobosPrometheus
+  class << self
+    include Logger
+    attr_reader :config, :metrics
+
+    # Public - configure and validate configuration
+    def configure(path)
+      @metrics ||= []
+      @config = ConfigParser.new(path).config
+
+      log_info('PhobosPrometheus configured')
+    end
+
+    # Public - after configured create the prometheus metrics
+    def subscribe
+      subscribe_counters
+      subscribe_histograms
+      subscribe_gauges
+
+      log_info('PhobosPrometheus subscribed') unless @metrics.empty?
+
+      self
+    end
+
+    private
+
+    def subscribe_counters
+      @config.counters.each do |counter|
+        @metrics << PhobosPrometheus::Collector::Counter.create(counter)
+      end
+    end
+
+    def subscribe_histograms
+      @config.histograms.each do |histogram|
+        @metrics << PhobosPrometheus::Collector::Histogram.create(histogram)
+      end
+    end
+
+    def subscribe_gauges
+      @config.gauges.each do |gauge|
+        @metrics << PhobosPrometheus::Collector::Gauge.create(gauge)
+      end
+    end
+  end
+end

data/lib/phobos_prometheus/collector.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module PhobosPrometheus
+  # Collector houses common metrics code
+  module Collector
+    EVENT_LABEL_BUILDER = proc do |event|
+      {
+        topic:    event.payload[:topic],
+        group_id: event.payload[:group_id],
+        handler:  event.payload[:handler]
+      }
+    end
+  end
+end

data/lib/phobos_prometheus/collector/counter.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module PhobosPrometheus
+  module Collector
+    # Collector class to track counter events
+    class Counter
+      include Helper
+      attr_reader :counter
+
+      def self.create(config)
+        instrumentation = config[:instrumentation]
+        raise(InvalidConfigurationError, 'Counter requires :instrumentation') \
+          unless instrumentation
+        new(instrumentation: instrumentation)
+      end
+
+      def initialize(instrumentation:)
+        @metrics_prefix = @instrumentation = @registry = @counter = nil
+        setup_collector_module(instrumentation: instrumentation)
+      end
+
+      def init_metrics(prometheus_label)
+        @counter = @registry.counter(
+          :"#{@metrics_prefix}_#{prometheus_label}_total",
+          "The total number of #{@instrumentation} events handled."
+        )
+      end
+
+      def update_metrics(event_label, _event)
+        @counter.increment(event_label)
+      end
+    end
+  end
+end

data/lib/phobos_prometheus/collector/error_logger.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module PhobosPrometheus
+  module Collector
+    # ErrorLogger logs errors to stdout
+    class ErrorLogger
+      include Logger
+      def initialize(error, event, instrumentation_label)
+        @error = error
+        @event = event
+        @instrumentation_label = instrumentation_label
+      end
+
+      def log
+        log_error(
+          Hash(
+            message: 'PhobosPrometheus: Error occured in metrics handler for subscribed event',
+            instrumentation_label: @instrumentation_label,
+            event: @event,
+            exception_class: @error.class.to_s,
+            exception_message: @error.message,
+            backtrace: @error.backtrace
+          )
+        )
+      end
+    end
+  end
+end

data/lib/phobos_prometheus/collector/gauge.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module PhobosPrometheus
+  module Collector
+    # Collector class to track gauge events
+    class Gauge
+      attr_reader :gauge, :registry
+
+      def self.create(config)
+        label = config[:label]
+        increment = config[:increment]
+        decrement = config[:decrement]
+
+        raise(InvalidConfigurationError, 'Gauge requires :label, :increment and :decrement') \
+          unless label && increment && decrement
+        new(label: label, increment: increment, decrement: decrement)
+      end
+
+      def initialize(label:, increment:, decrement:)
+        @registry = Prometheus::Client.registry
+        @metrics_prefix = PhobosPrometheus.config.metrics_prefix || 'phobos_client'
+        @increment = increment
+        @decrement = decrement
+        @label = label
+        @gauge = @registry.gauge(
+          :"#{@metrics_prefix}_#{label}", "The current count of #{@label}"
+        )
+
+        subscribe_metrics
+      end
+
+      def subscribe_metrics
+        Phobos::Instrumentation.subscribe(@increment) do |event|
+          safely_update_metrics(event, :increment)
+        end
+
+        Phobos::Instrumentation.subscribe(@decrement) do |event|
+          safely_update_metrics(event, :decrement)
+        end
+      end
+
+      # rubocop:disable Lint/RescueWithoutErrorClass
+      def safely_update_metrics(event, operation)
+        event_label = EVENT_LABEL_BUILDER.call(event)
+        # .increment and .decrement is not released yet
+        # @gauge.public_send(operation, event_label)
+        current = @gauge.get(event_label) || 0
+        if operation == :increment
+          @gauge.set(event_label, current + 1)
+        else
+          @gauge.set(event_label, current - 1)
+        end
+      rescue => error
+        ErrorLogger.new(error, event, @label).log
+      end
+      # rubocop:enable Lint/RescueWithoutErrorClass
+    end
+  end
+end

data/lib/phobos_prometheus/collector/helper.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module PhobosPrometheus
+  module Collector
+    # Shared code between collectors.
+    # Using module to avoid introducing inheritance
+    module Helper
+      attr_reader :registry
+
+      def setup_collector_module(instrumentation:)
+        @instrumentation = instrumentation
+        @registry = Prometheus::Client.registry
+        @metrics_prefix = PhobosPrometheus.config.metrics_prefix || 'phobos_client'
+
+        init_metrics(instrumentation.sub('.', '_'))
+        subscribe_metrics
+      end
+
+      def subscribe_metrics
+        Phobos::Instrumentation.subscribe(@instrumentation) do |event|
+          safely_update_metrics(event)
+        end
+      end
+
+      # rubocop:disable Lint/RescueWithoutErrorClass
+      def safely_update_metrics(event)
+        event_label = EVENT_LABEL_BUILDER.call(event)
+        update_metrics(event_label, event)
+      rescue => error
+        ErrorLogger.new(error, event, @instrumentation).log
+      end
+      # rubocop:enable Lint/RescueWithoutErrorClass
+    end
+  end
+end

data/lib/phobos_prometheus/collector/histogram.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module PhobosPrometheus
+  module Collector
+    # Collector class to track histogram events
+    class Histogram
+      include Helper
+      attr_reader :histogram
+
+      # Buckets in ms for histogram
+      BUCKETS = [5, 10, 25, 50, 100, 250, 500, 750, 1500, 3000, 5000].freeze
+
+      def self.create(config)
+        instrumentation = config[:instrumentation]
+        bucket_name = config[:bucket_name]
+        raise(InvalidConfigurationError, 'Histogram requires :bucket_name and :instrumentation') \
+          unless instrumentation && bucket_name
+        new(
+          instrumentation: instrumentation,
+          bucket_name: bucket_name
+        )
+      end
+
+      def initialize(instrumentation:, bucket_name:)
+        @metrics_prefix = @instrumentation = @registry = @histogram = nil
+        @buckets = fetch_bucket_size(bucket_name) || BUCKETS
+        setup_collector_module(instrumentation: instrumentation)
+      end
+
+      def fetch_bucket_size(bucket_name)
+        PhobosPrometheus.config.buckets.find { |bucket| bucket.name == bucket_name }.bins
+      end
+
+      def init_metrics(prometheus_label)
+        @histogram = @registry.histogram(
+          :"#{@metrics_prefix}_#{prometheus_label}_duration",
+          "The duration spent (in ms) consuming #{@instrumentation} events.",
+          {},
+          @buckets
+        )
+      end
+
+      def update_metrics(event_label, event)
+        @histogram.observe(event_label, event.duration)
+      end
+    end
+  end
+end

data/lib/phobos_prometheus/config_parser.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+module PhobosPrometheus
+  # Validate Counters
+  class CountersValidator
+    include Logger
+    COUNTER_INSTRUMENTATION_MISSING = 'Missing required key :instrumentation for counter'
+    COUNTER_INVALID_KEY = 'Invalid configuration option detected at counter level, ignoring'
+    COUNTER_KEYS = [:instrumentation].freeze
+
+    def initialize(counters)
+      @counters = counters
+    end
+
+    def validate
+      @counters.map do |counter|
+        validate_counter(counter)
+      end
+    end
+
+    def validate_counter(counter)
+      Helper.assert_required_key(counter, :instrumentation) || \
+        Helper.fail_config(COUNTER_INSTRUMENTATION_MISSING)
+      Helper.check_invalid_keys(COUNTER_KEYS, counter) || \
+        log_warn(COUNTER_INVALID_KEY)
+    end
+  end
+
+  # Validate Histograms
+  class HistogramsValidator
+    include Logger
+    HISTOGRAM_INSTRUMENTATION_MISSING = 'Missing required key :instrumentation for histogram'
+    HISTOGRAM_BUCKET_NAME_MISSING = 'Missing required key :bucket_name for histogram'
+    HISTOGRAM_INVALID_BUCKET = 'Invalid bucket reference specified for histogram'
+    HISTOGRAM_INVALID_KEY = 'Invalid configuration option detected at histogram level, ignoring'
+    HISTOGRAM_KEYS = [:instrumentation, :bucket_name].freeze
+
+    def initialize(histograms, buckets)
+      @histograms = histograms
+      @buckets = buckets
+    end
+
+    def validate
+      @histograms.map do |histogram|
+        validate_histogram(histogram)
+      end
+    end
+
+    def validate_histogram(histogram)
+      Helper.assert_required_key(histogram, :instrumentation) || \
+        Helper.fail_config(HISTOGRAM_INSTRUMENTATION_MISSING)
+      Helper.assert_required_key(histogram, :bucket_name) || \
+        Helper.fail_config(HISTOGRAM_BUCKET_NAME_MISSING)
+      assert_bucket_exists(histogram['bucket_name']) || Helper.fail_config(HISTOGRAM_INVALID_BUCKET)
+      Helper.check_invalid_keys(HISTOGRAM_KEYS, histogram) || \
+        log_warn(HISTOGRAM_INVALID_KEY)
+    end
+
+    def assert_bucket_exists(name)
+      @buckets.any? { |key| key.name == name }
+    end
+  end
+
+  # Validate buckets
+  class BucketsValidator
+    include Logger
+    BUCKET_NAME_MISSING = 'Missing required key :name for bucket'
+    BUCKET_BINS_MISSING = 'Missing required key :bins for bucket'
+    BUCKET_BINS_EMPTY = 'Bucket config bad, bins are empty'
+    BUCKET_INVALID_KEY = 'Invalid configuration option detected at bucket level, ignoring'
+    BUCKET_KEYS = [:name, :bins].freeze
+
+    def initialize(buckets)
+      @buckets = buckets
+    end
+
+    def validate
+      @buckets.map do |bucket|
+        validate_bucket(bucket)
+      end
+    end
+
+    def validate_bucket(bucket)
+      Helper.assert_required_key(bucket, :name) || Helper.fail_config(BUCKET_NAME_MISSING)
+      Helper.assert_required_key(bucket, :bins) || Helper.fail_config(BUCKET_BINS_MISSING)
+      Helper.assert_array_of_type(bucket, :bins, Integer) || Helper.fail_config(BUCKET_BINS_EMPTY)
+      Helper.check_invalid_keys(BUCKET_KEYS, bucket) || \
+        log_warn(BUCKET_INVALID_KEY)
+    end
+  end
+
+  # Validate gauges
+  class GaugesValidator
+    include Logger
+    GAUGE_LABEL_MISSING = 'Missing required key :label for gauge'
+    GAUGE_INCREMENT_MISSING = 'Missing required key :increment for gauge'
+    GAUGE_DECREMENT_MISSING = 'Missing required key :decrement for gauge'
+    GAUGE_INVALID_KEY = 'Invalid configuration option detected at gauge level, ignoring'
+    GAUGE_KEYS = [:label, :increment, :decrement].freeze
+
+    def initialize(gauges)
+      @gauges = gauges
+    end
+
+    def validate
+      @gauges.map do |gauge|
+        validate_gauge(gauge)
+      end
+    end
+
+    def validate_gauge(gauge)
+      Helper.assert_required_key(gauge, :label) || Helper.fail_config(GAUGE_LABEL_MISSING)
+      Helper.assert_required_key(gauge, :increment) || Helper.fail_config(GAUGE_INCREMENT_MISSING)
+      Helper.assert_required_key(gauge, :decrement) || Helper.fail_config(GAUGE_DECREMENT_MISSING)
+      Helper.check_invalid_keys(GAUGE_KEYS, gauge) || \
+        log_warn(GAUGE_INVALID_KEY)
+    end
+  end
+
+  # Helper for operations not dependent on instance state
+  module Helper
+    def self.read_config(path)
+      Phobos::DeepStruct.new(
+        YAML.safe_load(
+          ERB.new(
+            File.read(File.expand_path(path))
+          ).result
+        )
+      )
+    end
+
+    def self.assert_required_key(metric, required)
+      metric.keys.any? { |key| key.to_sym == required }
+    end
+
+    def self.assert_array_of_type(metric, key, type)
+      ary = metric[key.to_s]
+      ary.is_a?(Array) && \
+        ary.all? { |value| value.is_a? type }
+    end
+
+    def self.fail_config(message)
+      raise(InvalidConfigurationError, message)
+    end
+
+    def self.check_invalid_keys(keys, metric)
+      metric.keys.all? { |key| keys.include?(key.to_sym) }
+    end
+  end
+
+  # Config validates and parses configuration yml
+  class ConfigParser
+    include Logger
+    attr_reader :config
+
+    ROOT_MISSING_COLLECTORS = 'No histograms, gauges nor counters are configured. ' \
+                              'Metrics will not be recorded'
+    ROOT_INVALID_KEY = 'Invalid configuration option detected at root level, ignoring'
+    ROOT_KEYS = [:metrics_prefix, :counters, :histograms, :buckets, :gauges].freeze
+
+    def initialize(path)
+      @config = Helper.read_config(path)
+      validate_config
+      @config.counters = [] unless @config.counters
+      @config.histograms = [] unless @config.histograms
+      @config.gauges = [] unless @config.gauges
+      @config.freeze
+    end
+
+    def validate_config
+      validate_root
+      validate_counters
+      validate_histograms
+      validate_buckets
+      validate_gauges
+    end
+
+    def validate_root
+      assert_required_root_keys
+      Helper.check_invalid_keys(ROOT_KEYS, @config.to_h) || \
+        log_warn(ROOT_INVALID_KEY)
+    end
+
+    def validate_counters
+      CountersValidator.new(@config.to_h[:counters] || []).validate
+    end
+
+    def validate_histograms
+      HistogramsValidator.new(@config.to_h[:histograms] || [], @config.buckets).validate
+    end
+
+    def validate_buckets
+      BucketsValidator.new(@config.to_h[:buckets] || []).validate
+    end
+
+    def validate_gauges
+      GaugesValidator.new(@config.to_h[:gauges] || []).validate
+    end
+
+    def assert_required_root_keys
+      @config.counters || @config.histograms || @config.gauges || \
+        log_warn(ROOT_MISSING_COLLECTORS)
+    end
+  end
+end