gitlab-labkit 0.37.0 → 0.40.0

data/lib/labkit/covered_experience.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require 'labkit/covered_experience/error'
+require 'labkit/covered_experience/experience'
+require 'labkit/covered_experience/null'
+require 'labkit/covered_experience/registry'
+require 'labkit/logging/json_logger'
+
+module Labkit
+  # Labkit::CoveredExperience namespace module.
+  #
+  # This module is responsible for managing covered experiences, which are
+  # specific events or activities within the application that are measured
+  # and reported for performance monitoring and analysis.
+  module CoveredExperience
+    # Configuration class for CoveredExperience
+    class Configuration
+      attr_accessor :logger
+
+      def initialize
+        @logger = Labkit::Logging::JsonLogger.new($stdout)
+      end
+    end
+
+    class << self
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def reset_configuration
+        @configuration = nil
+      end
+
+      def configure
+        yield(configuration) if block_given?
+      end
+
+      def registry
+        @registry ||= Registry.new
+      end
+
+      def reset
+        @registry = nil
+      end
+
+      def get(experience_id)
+        definition = registry[experience_id]
+
+        if definition
+          Experience.new(definition)
+        else
+          raise_or_null(experience_id)
+        end
+      end
+
+      def start(experience_id, &)
+        get(experience_id).start(&)
+      end
+
+      private
+
+      def raise_or_null(experience_id)
+        return Null.instance unless %w[development test].include?(ENV['RAILS_ENV'])
+
+        raise(NotFoundError, "Covered Experience #{experience_id} not found in the registry")
+      end
+    end
+  end
+end

data/lib/labkit/logging/json_logger.rb

@@ -52,6 +52,7 @@ module Labkit
           data[:message] = message
         when Hash
           reject_reserved_log_keys!(message)
+          format_time!(data)
           data.merge!(message)
         end
 
@@ -77,6 +78,16 @@ module Labkit
                   "\n\nUse key names that are descriptive e.g. by using a prefix."
         end
       end
+
+      def format_time!(hash)
+        hash.each do |key, value|
+          if value.is_a?(Time)
+            hash[key] = value.utc.iso8601(3)
+          elsif value.is_a?(Hash)
+            format_time(value)
+          end
+        end
+      end
     end
   end
 end

data/lib/labkit/metrics/README.md

@@ -0,0 +1,98 @@
+# Labkit::Metrics
+
+## Usage
+
+```ruby
+# create a new counter metric and returns it
+http_requests = Labkit::Metrics::Client.counter(:http_requests, 'A counter of HTTP requests made')
+# start using the counter
+http_requests.increment
+
+# resets the registry and reinitializes all metrics files
+Labkit::Metrics::Client.reset!
+
+# retrieves the metric (be it a counter, gauge, histogram, summary)
+http_requests = Labkit::Metrics::Client.get(:http_requests)
+```
+
+### Counter
+
+```ruby
+counter = Labkit::Metrics::Client.counter(:service_requests_total, '...')
+
+# increment the counter for a given label set
+counter.increment({ service: 'foo' })
+
+# increment by a given value
+counter.increment({ service: 'bar' }, 5)
+
+# get current value for a given label set
+counter.get({ service: 'bar' })
+# => 5
+```
+
+### Gauge
+
+```ruby
+gauge = Labkit::Metrics::Client.gauge(:room_temperature_celsius, '...')
+
+# set a value
+gauge.set({ room: 'kitchen' }, 21.534)
+
+# retrieve the current value for a given label set
+gauge.get({ room: 'kitchen' })
+# => 21.534
+```
+
+### Histogram
+
+```ruby
+histogram = Labkit::Metrics::Client.histogram(:service_latency_seconds, '...')
+
+# record a value
+histogram.observe({ service: 'users' }, Benchmark.realtime { service.call(arg) })
+
+# retrieve the current bucket values
+histogram.get({ service: 'users' })
+# => { 0.005 => 3, 0.01 => 15, 0.025 => 18, ..., 2.5 => 42, 5 => 42, 10 => 42 }
+```
+
+### Summary
+
+```ruby
+summary = Labkit::Metrics::Client.summary(:service_latency_seconds, '...')
+
+# record a value
+summary.observe({ service: 'database' }, Benchmark.realtime { service.call() })
+
+# retrieve the current quantile values
+summary.get({ service: 'database' })
+# => { 0.5 => 0.1233122, 0.9 => 3.4323, 0.99 => 5.3428231 }
+```
+
+## Rack middleware
+
+```ruby
+# config.ru
+
+require 'rack'
+require 'labkit/metrics/rack_exporter'
+
+use Labkit::Metrics::RackExporter
+
+run ->(env) { [200, {'Content-Type' => 'text/html'}, ['OK']] }
+```
+
+## Configuration
+
+```ruby
+# config/initializers/metrics.rb
+
+Labkit::Metrics::Client.reinitialize_on_pid_change(force: true)
+
+Labkit::Metrics::Client.configure do |config|
+  config.logger = Gitlab::AppLogger
+  config.multiprocess_files_dir = 'tmp/prometheus_multiproc_dir'
+  config.pid_provider = ::Prometheus::PidProvider.method(:worker_id)
+end
+```

data/lib/labkit/metrics/client.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "forwardable"
+require "singleton"
+require 'concurrent-ruby'
+require "prometheus/client"
+require "labkit/metrics/registry"
+require "labkit/metrics/null"
+
+module Labkit
+  module Metrics
+    InvalidLabelSet = Class.new(RuntimeError)
+
+    # A thin wrapper around Prometheus::Client from the prometheus-client-mmap gem
+    # https://gitlab.com/gitlab-org/ruby/gems/prometheus-client-mmap
+    class Client
+      include Singleton
+      extend Forwardable
+
+      def_delegators :wrapped_client, :configure, :reinitialize_on_pid_change, :configuration
+
+      def initialize
+        @enabled = Concurrent::AtomicBoolean.new(true)
+      end
+
+      def wrapped_client
+        @client ||= ::Prometheus::Client
+      end
+
+      def disable!
+        @enabled.make_false
+      end
+
+      def enable!
+        @enabled.make_true
+      end
+
+      def enabled?
+        @enabled.true? && metrics_folder_present?
+      end
+
+      def safe_provide_metric(metric_type, name, *args)
+        return Null.instance unless enabled?
+
+        Registry.safe_register(metric_type, name, *args)
+      end
+
+      def metrics_folder_present?
+        dir = configuration.multiprocess_files_dir
+        dir && Dir.exist?(dir) && File.writable?(dir)
+      end
+
+      def counter(name, docstring, base_labels = {})
+        safe_provide_metric(:counter, name, docstring, base_labels)
+      end
+
+      def summary(name, docstring, base_labels = {})
+        safe_provide_metric(:summary, name, docstring, base_labels)
+      end
+
+      def histogram(
+        name, docstring, base_labels = {},
+        buckets = Prometheus::Client::Histogram::DEFAULT_BUCKETS)
+        safe_provide_metric(:histogram, name, docstring, base_labels, buckets)
+      end
+
+      def gauge(name, docstring, base_labels = {}, multiprocess_mode = :all)
+        safe_provide_metric(:gauge, name, docstring, base_labels, multiprocess_mode)
+      end
+
+      def reset!
+        Registry.reset!
+      end
+
+      def get(metric_name)
+        Registry.get(metric_name)
+      end
+
+      class << self
+        extend Forwardable
+
+        def_delegators :instance,
+          :enable!, :disable!, :counter, :gauge, :histogram, :summary, :reset!, :enabled?,
+          :configure, :reinitialize_on_pid_change, :configuration, :get
+
+        private :instance
+      end
+    end
+  end
+end

data/lib/labkit/metrics/null.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Labkit
+  module Metrics
+    # Fakes Prometheus::Client::Metric and all derived metrics.
+    # Explicitly avoiding meta-programming to make interface more obvious to interact with.
+    class Null
+      include Singleton
+
+      attr_reader :name, :docstring, :base_labels
+
+      def get(*args); end
+      def set(*args); end
+      def increment(*args); end
+      def decrement(*args); end
+      def observe(*args); end
+      def values(*args); end
+    end
+  end
+end

data/lib/labkit/metrics/rack_exporter.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "prometheus/client/rack/exporter"
+
+module Labkit
+  module Metrics
+    # A wrapper around the Rack exporter middleware provided by
+    # prometheus-client-mmap gem
+    # https://gitlab.com/gitlab-org/ruby/gems/prometheus-client-mmap
+    class RackExporter < Prometheus::Client::Rack::Exporter; end
+  end
+end

data/lib/labkit/metrics/registry.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "prometheus/client"
+
+module Labkit
+  module Metrics
+    InvalidMetricType = Class.new(StandardError)
+
+    # A thin wrapper around Prometheus::Client::Registry.
+    # It provides a thread-safe way to register metrics with the Prometheus registry.
+    class Registry
+      class << self
+        INIT_REGISTRY_MUTEX = Mutex.new
+        REGISTER_MUTEX = Mutex.new
+
+        # Registers a metric with the Prometheus registry in a thread-safe manner.
+        # If the metric already exists, it returns the existing metric.
+        # If the metric does not exist, it creates a new one.
+        # Each metric-name is only registered once for a type (counter, gauge, histogram, summary),
+        # even if multiple threads attempt to register the same metric simultaneously.
+        #
+        # @param metric_type [Symbol] The type of metric to register (:counter, :gauge, :histogram, :summary)
+        # @param name [Symbol, String] The name of the metric
+        # @param args [Array] Additional arguments to pass to the metric constructor
+        # @return [Prometheus::Client::Metric] The registered metric
+        # @raise [InvalidMetricType] If the metric_type is not supported
+        #
+        # @example
+        #   # Register a counter
+        #   counter = Registry.safe_register(:counter, :http_requests_total, 'Total HTTP requests')
+        def safe_register(metric_type, name, *args)
+          REGISTER_MUTEX.synchronize do
+            get(name) || wrapped_registry.method(metric_type).call(name, *args)
+          end
+        end
+
+        # Cleans up the Prometheus registry and resets it to a new state.
+        def reset!
+          INIT_REGISTRY_MUTEX.synchronize do
+            Prometheus::Client.cleanup!
+            Prometheus::Client.reset!
+            @registry = nil
+          end
+        end
+
+        # Returns the metric for the given name from the Prometheus registry.
+        #
+        # @param metric_name [Symbol, String] The name of the metric
+        # @return [Prometheus::Client::Metric, nil] The registered metric or nil if it does not exist
+        def get(metric_name)
+          wrapped_registry.get(metric_name)
+        end
+
+        private
+
+        def wrapped_registry
+          @registry ||= init_registry
+        end
+
+        def init_registry
+          # Prometheus::Client.registry initializes a new registry with an underlying hash
+          # storing metrics and a mutex synchronizing the writes to that hash.
+          # This means we need to make sure we only build one registry, for accessing from within Labkit.
+          INIT_REGISTRY_MUTEX.synchronize { Prometheus::Client.registry }
+        end
+      end
+    end
+  end
+end

data/lib/labkit/metrics.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "prometheus/client/formats/text"
+
+module Labkit
+  # Metrics provides functionality for producing metrics
+  module Metrics
+    autoload :Client, "labkit/metrics/client"
+    autoload :RackExporter, "labkit/metrics/rack_exporter"
+    autoload :Null, "labkit/metrics/null"
+
+    class << self
+      def prometheus_metrics_text
+        dir = Client.configuration.multiprocess_files_dir
+        ::Prometheus::Client::Formats::Text.marshal_multiprocess(dir)
+      end
+    end
+  end
+end

data/lib/labkit/rspec/README.md

@@ -0,0 +1,121 @@
+# Labkit RSpec Support
+
+This module provides RSpec matchers for testing Labkit functionality in your Rails applications.
+
+## Setup
+
+You must explicitly require the RSpec matchers in your test files:
+
+```ruby
+# In your spec_helper.rb or rails_helper.rb
+require 'labkit/rspec/matchers'
+```
+
+This approach ensures that:
+- Test dependencies are not loaded in production environments
+- You have explicit control over which matchers are available
+- The gem remains lightweight for non-testing use cases
+
+
+## Available Matchers
+
+### Covered Experience Matchers
+
+These matchers help you test that your code properly instruments covered experiences with the expected metrics.
+
+#### `start_covered_experience`
+
+Tests that a covered experience is started (checkpoint=start metric is incremented).
+
+```ruby
+expect { subject }.to start_covered_experience('rails_request')
+
+# Test that it does NOT start
+expect { subject }.not_to start_covered_experience('rails_request')
+```
+
+#### `checkpoint_covered_experience`
+
+Tests that a covered experience checkpoint is recorded (checkpoint=intermediate metric is incremented).
+
+```ruby
+expect { subject }.to checkpoint_covered_experience('rails_request')
+
+# Test that it does NOT checkpoint
+expect { subject }.not_to checkpoint_covered_experience('rails_request')
+```
+
+#### `complete_covered_experience`
+
+Tests that a covered experience is completed with the expected metrics:
+- `gitlab_covered_experience_checkpoint_total` (with checkpoint=end)
+- `gitlab_covered_experience_total` (with error flag)
+- `gitlab_covered_experience_apdex_total` (with success flag)
+
+```ruby
+# Test successful completion
+expect { subject }.to complete_covered_experience('rails_request')
+
+# Test completion with error
+expect { subject }.to complete_covered_experience('rails_request', error: true, success: false)
+
+# Test that it does NOT complete
+expect { subject }.not_to complete_covered_experience('rails_request')
+```
+
+## Example Usage
+
+### In your spec_helper.rb or rails_helper.rb:
+
+```ruby
+# spec/spec_helper.rb or spec/rails_helper.rb
+require 'gitlab-labkit'
+
+# Explicitly require the RSpec matchers
+require 'labkit/rspec/matchers'
+
+RSpec.configure do |config|
+  # Your other RSpec configuration...
+end
+```
+
+### In your test files:
+
+```ruby
+RSpec.describe MyController, type: :controller do
+  describe '#index' do
+    it 'instruments the request properly' do
+      expect { get :index }.to start_covered_experience('rails_request')
+        .and complete_covered_experience('rails_request')
+    end
+
+    context 'when an error occurs' do
+      before do
+        allow(MyService).to receive(:call).and_raise(StandardError)
+      end
+
+      it 'records the error in metrics' do
+        expect { get :index }.to complete_covered_experience('rails_request', error: true, success: false)
+      end
+    end
+  end
+end
+```
+
+### For individual spec files (alternative approach):
+
+```ruby
+# spec/controllers/my_controller_spec.rb
+require 'spec_helper'
+require 'labkit/rspec/matchers' # Can also be required per-file if needed
+
+RSpec.describe MyController do
+  # Your tests using the matchers...
+end
+```
+
+## Requirements
+
+- The covered experience must be registered in `Labkit::CoveredExperience::Registry`
+- Metrics must be properly configured in your test environment
+- The code under test must use Labkit's covered experience instrumentation