gitlab-labkit 0.39.0 → 0.41.0

data/lib/labkit/covered_experience/experience.rb

@@ -0,0 +1,287 @@
+# frozen_string_literal: true
+
+require 'active_support/hash_with_indifferent_access'
+require 'forwardable'
+require 'labkit/context'
+require 'labkit/covered_experience/current'
+require 'labkit/covered_experience/error'
+
+module Labkit
+  module CoveredExperience
+    URGENCY_THRESHOLDS_IN_SECONDS = {
+      sync_fast: 2,
+      sync_slow: 5,
+      async_fast: 15,
+      async_slow: 300
+    }.freeze
+
+    RESERVED_KEYWORDS = %w[
+      checkpoint
+      covered_experience
+      feature_category
+      urgency
+      start_time
+      checkpoint_time
+      end_time
+      elapsed_time_s
+      urgency_threshold_s
+      error
+      error_message
+      success
+    ].freeze
+
+    # The `Experience` class represents a single Covered Experience
+    # event to be measured and reported.
+    class Experience
+      extend Forwardable
+
+      attr_reader :error, :start_time
+
+      def initialize(definition)
+        @definition = definition
+      end
+
+      def id
+        @definition.covered_experience
+      end
+
+      # Rehydrate an Experience instance from serialized data.
+      #
+      # @param data [Hash] A hash of serialized data.
+      # @return [Experience]
+      def rehydrate(data = {})
+        @start_time = Time.iso8601(data["start_time"]) if data&.has_key?("start_time") && data["start_time"]
+        self
+      rescue ArgumentError
+        warn("Invalid #{id}, start_time: #{data['start_time']}")
+        self
+      end
+
+      # Start the Covered Experience.
+      #
+      # @yield [self] When a block is provided, the experience will be completed automatically.
+      # @param extra [Hash] Additional data to include in the log event
+      # @return [self]
+      # @raise [CoveredExperienceError] If the block raises an error.
+      #
+      # Usage:
+      #
+      #  CoveredExperience.new(definition).start do |experience|
+      #    experience.checkpoint
+      #    experience.checkpoint
+      #  end
+      #
+      #  experience = CoveredExperience.new(definition)
+      #  experience.start
+      #  experience.checkpoint
+      #  experience.complete
+      def start(**extra, &)
+        @start_time = Time.now.utc
+        checkpoint_counter.increment(checkpoint: "start", **base_labels)
+        log_event("start", **extra)
+
+        Labkit::CoveredExperience::Current.active_experiences[id] = self
+
+        return self unless block_given?
+
+        completable(**extra, &)
+      end
+
+      # Checkpoint the Covered Experience.
+      #
+      # @param extra [Hash] Additional data to include in the log event
+      # @raise [UnstartedError] If the experience has not been started and RAILS_ENV is development or test.
+      # @return [self]
+      def checkpoint(**extra)
+        return unless ensure_started!
+
+        @checkpoint_time = Time.now.utc
+        checkpoint_counter.increment(checkpoint: "intermediate", **base_labels)
+        log_event("intermediate", **extra)
+
+        self
+      end
+
+      # Resume the Covered Experience.
+      #
+      # @yield [self] When a block is provided, the experience will be completed automatically.
+      # @param extra [Hash] Additional data to include in the log
+      def resume(**extra, &)
+        return unless ensure_started!
+
+        checkpoint(checkpoint_action: 'resume', **extra)
+
+        return self unless block_given?
+
+        completable(**extra, &)
+      end
+
+      # Complete the Covered Experience.
+      #
+      # @param extra [Hash] Additional data to include in the log event
+      # @raise [UnstartedError] If the experience has not been started and RAILS_ENV is development or test.
+      # @return [self]
+      def complete(**extra)
+        return unless ensure_started!
+        return unless ensure_incomplete!
+
+        begin
+          @end_time = Time.now.utc
+        ensure
+          checkpoint_counter.increment(checkpoint: "end", **base_labels)
+          total_counter.increment(error: has_error?, **base_labels)
+          apdex_counter.increment(success: apdex_success?, **base_labels) unless has_error?
+          log_event("end", **extra)
+          Labkit::CoveredExperience::Current.active_experiences.delete(id)
+        end
+
+        self
+      end
+
+      # Marks the experience as failed with an error
+      #
+      # @param error [StandardError, String] The error that caused the experience to fail.
+      # @return [self]
+      def error!(error)
+        @error = error
+        self
+      end
+
+      def has_error?
+        !!@error
+      end
+
+      def to_h
+        return {} unless ensure_started!
+
+        { id => { "start_time" => @start_time&.iso8601(3) } }
+      end
+
+      private
+
+      def base_labels
+        @base_labels ||= @definition.to_h.slice(:covered_experience, :feature_category, :urgency)
+      end
+
+      def ensure_started!
+        return @start_time unless @start_time.nil?
+
+        err = UnstartedError.new("Covered Experience #{@definition.covered_experience} not started")
+
+        warn(err)
+        raise(err) if %w[development test].include?(ENV['RAILS_ENV'])
+      end
+
+      def completable(**extra, &)
+        begin
+          yield self
+        rescue StandardError => e
+          error!(e)
+          raise
+        ensure
+          complete(**extra)
+        end
+
+        self
+      end
+
+      def ensure_incomplete!
+        return true if @end_time.nil?
+
+        err = CompletedError.new("Covered Experience #{@definition.covered_experience} already completed")
+
+        warn(err)
+        raise(err) if %w[development test].include?(ENV['RAILS_ENV'])
+      end
+
+      def urgency_threshold
+        URGENCY_THRESHOLDS_IN_SECONDS[@definition.urgency.to_sym]
+      end
+
+      def elapsed_time
+        last_time = @end_time || @checkpoint_time || @start_time
+        last_time - @start_time
+      end
+
+      def apdex_success?
+        elapsed_time <= urgency_threshold
+      end
+
+      def checkpoint_counter
+        @checkpoint_counter ||= Labkit::Metrics::Client.counter(
+          :gitlab_covered_experience_checkpoint_total,
+          'Total checkpoints for covered experiences'
+        )
+      end
+
+      def total_counter
+        @total_counter ||= Labkit::Metrics::Client.counter(
+          :gitlab_covered_experience_total,
+          'Total covered experience events (success/failure)'
+        )
+      end
+
+      def apdex_counter
+        @apdex_counter ||= Labkit::Metrics::Client.counter(
+          :gitlab_covered_experience_apdex_total,
+          'Total covered experience apdex events'
+        )
+      end
+
+      def log_event(event_type, **extra)
+        validate_extra_parameters!(extra)
+
+        log_data = build_log_data(event_type, **extra)
+        logger.info(log_data)
+      end
+
+      def build_log_data(event_type, **extra)
+        log_data = ActiveSupport::HashWithIndifferentAccess.new(
+          checkpoint: event_type,
+          covered_experience: id,
+          feature_category: @definition.feature_category,
+          urgency: @definition.urgency,
+          start_time: @start_time,
+          checkpoint_time: @checkpoint_time,
+          end_time: @end_time,
+          elapsed_time_s: elapsed_time,
+          urgency_threshold_s: urgency_threshold
+        )
+        log_data.reverse_merge!(extra) if extra
+
+        if has_error?
+          log_data[:error] = true
+          log_data[:error_message] = @error.inspect
+        end
+
+        log_data.compact!
+
+        log_data
+      end
+
+      def warn(err, **extra)
+        case err
+        when StandardError
+          logger.warn(component: self.class.name, message: err.message, **extra)
+        when String
+          logger.warn(component: self.class.name, message: err, **extra)
+        end
+      end
+
+      def validate_extra_parameters!(extra)
+        return if extra.empty?
+
+        reserved_keys = extra.keys.map(&:to_s) & RESERVED_KEYWORDS
+        return if reserved_keys.empty?
+
+        err = ReservedKeywordError.new("Reserved keywords found in extra parameters: #{reserved_keys.join(', ')}")
+
+        raise(err) if %w[development test].include?(ENV['RAILS_ENV'])
+      end
+
+      def logger
+        Labkit::CoveredExperience.configuration.logger
+      end
+    end
+  end
+end

data/lib/labkit/covered_experience/null.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Labkit
+  module CoveredExperience
+    # Fakes Labkit::CoveredExperience::Experience.
+    class Null
+      include Singleton
+
+      def id = 'null'
+
+      def start(**_extra)
+        yield self if block_given?
+        self
+      end
+
+      def resume(**_extra)
+        yield self if block_given?
+        self
+      end
+
+      def push_attributes!(*_args) = self
+      def checkpoint(*_args) = self
+      def complete(*_args) = self
+      def error!(*_args) = self
+      def rehydrate(*_args, **_kwargs) = self
+      def to_h = {}
+    end
+  end
+end

data/lib/labkit/covered_experience/registry.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+require 'json-schema'
+require 'pathname'
+require 'yaml'
+
+module Labkit
+  module CoveredExperience
+    Definition = Data.define(:covered_experience, :description, :feature_category, :urgency)
+
+    class Registry
+      extend Forwardable
+
+      SCHEMA_PATH = File.expand_path('../../../config/covered_experiences/schema.json', __dir__)
+
+      def_delegator :@experiences, :empty?
+
+      # @param dir [String, Pathname] Directory path containing YAML file definitions
+      #   Defaults to 'config/covered_experiences' relative to the calling application's root
+      def initialize(dir: File.join("config", "covered_experiences"))
+        @dir = Pathname.new(Dir.pwd).join(dir)
+        @experiences = load_on_demand
+      end
+
+      # Retrieve a definition experience given a covered_experience_id.
+      #
+      # @param covered_experience_id [String, Symbol] Covered experience identifier
+      # @return [Experience, nil] An experience if present, otherwise nil
+      def [](covered_experience_id)
+        @experiences[covered_experience_id.to_s]
+      end
+
+      private
+
+      # Initialize a hash that loads experiences on-demand
+      #
+      # @return [Hash] Hash with lazy loading behavior
+      def load_on_demand
+        unless readable_dir?
+          warn("Directory not readable: #{@dir}")
+          return {}
+        end
+
+        Hash.new do |result, experience_id|
+          experience = load_experience(experience_id.to_s)
+          # we also store nil to memoize the value and avoid triggering load_experience again
+          result[experience_id.to_s] = experience
+        end
+      end
+
+      # Load a covered experience definition.
+      #
+      # @param experience_id [String] Experience identifier
+      # @return [Experience, nil] Loaded experience or nil if not found/invalid
+      def load_experience(experience_id)
+        file_path = @dir.join("#{experience_id}.yml")
+
+        unless file_path.exist?
+          warn("Invalid Covered Experience definition: #{experience_id}")
+          return nil
+        end
+
+        read_experience(file_path, experience_id)
+      end
+
+      def readable_dir?
+        @dir.exist? && @dir.directory? && @dir.readable?
+      end
+
+      # Read and validate a definition experience file
+      #
+      # @param file_path [Pathname] Path to the definition file
+      # @param experience_id [String] Expected experience ID
+      # @return [Experience, nil] Parsed experience or nil if invalid
+      def read_experience(file_path, experience_id)
+        content = YAML.safe_load(file_path.read)
+        return nil unless content.is_a?(Hash)
+
+        errors = JSON::Validator.fully_validate(schema, content)
+        return Definition.new(covered_experience: experience_id, **content) if errors.empty?
+
+        warn("Invalid schema for #{file_path}")
+
+        nil
+      rescue Psych::SyntaxError => e
+        warn("Invalid definition file #{file_path}: #{e.message}")
+      rescue StandardError => e
+        warn("Unexpected error processing #{file_path}: #{e.message}")
+      end
+
+      def schema
+        @schema ||= JSON.parse(File.read(SCHEMA_PATH))
+      end
+
+      def warn(message)
+        logger.warn(component: self.class.name, message: message)
+      end
+
+      def logger
+        Labkit::CoveredExperience.configuration.logger
+      end
+    end
+  end
+end

data/lib/labkit/covered_experience.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require 'labkit/covered_experience/current'
+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, :registry_path
+
+      def initialize
+        @logger = Labkit::Logging::JsonLogger.new($stdout)
+        @registry_path = File.join("config", "covered_experiences")
+      end
+    end
+
+    class << self
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def reset_configuration
+        @configuration = nil
+      end
+
+      def configure
+        yield(configuration) if block_given?
+        # Reset registry when configuration changes to pick up new registry_path
+        @registry = nil
+      end
+
+      def registry
+        @registry ||= Registry.new(dir: configuration.registry_path)
+      end
+
+      def reset
+        @registry = nil
+        reset_configuration
+      end
+
+      # Retrieves a covered experience using the experience_id.
+      # It retrieves from the current context when available,
+      # otherwise it instantiates a new experience with the definition
+      # from the registry.
+      #
+      # @param experience_id [String, Symbol] The ID of the experience to retrieve.
+      # @return [Experience, Null] The found experience or a Null object if not found (in production/staging).
+      def get(experience_id)
+        find_current(experience_id) || raise_or_null(experience_id)
+      end
+
+      # Starts a covered experience using the experience_id.
+      #
+      # @param experience_id [String, Symbol] The ID of the experience to start.
+      # @param extra [Hash] Additional data to include in the log event.
+      # @return [Experience, Null] The started experience or a Null object if not found (in production/staging).
+      def start(experience_id, **extra, &)
+        get(experience_id).start(**extra, &)
+      end
+
+      # Resumes a covered experience using the experience_id.
+      #
+      # @param experience_id [String, Symbol] The ID of the experience to resume.
+      # @return [Experience, Null] The started experience or a Null object if not found (in production/staging).
+      def resume(experience_id, **extra, &)
+        get(experience_id).resume(**extra, &)
+      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
+
+      def find_current(experience_id)
+        xp = Current.active_experiences[experience_id.to_s]
+        return xp unless xp.nil?
+
+        definition = registry[experience_id]
+        Experience.new(definition) if definition
+      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/middleware/rack.rb

@@ -25,6 +25,8 @@ module Labkit
 
           [status, headers, response]
         end
+      ensure
+        reset_current_experiences
       end
 
       private
@@ -44,6 +46,27 @@ module Labkit
           .merge("version" => "1")
           .to_json
       end
+
+      # Reset Current experiences to prevent memory leaks and cross-request contamination.
+      #
+      # Rails applications automatically call ActiveSupport::CurrentAttributes.reset_all
+      # after each request via https://github.com/rails/rails/blob/2d4f445051b63853d48c642d0ab59ab026aa1d6a/activesupport/lib/active_support/railtie.rb,
+      # but we must handle other scenarios where this middleware might be used:
+      #
+      # 1. Non-Rails Rack applications (Sinatra, Grape, plain Rack apps)
+      # 2. Custom Rack stacks that don't include ActiveSupport::Railtie
+      # 3. Test environments where Rails middleware stack might be bypassed
+      # 4. Microservices or API-only applications with minimal middleware
+      # 5. Background job processors that use Rack but not Rails' full stack
+      #
+      # By explicitly resetting here, we ensure covered experiences are properly
+      # cleaned up regardless of the application framework or middleware configuration.
+      def reset_current_experiences
+        # Only reset if the Current class is loaded to avoid unnecessary dependencies
+        return unless defined?(Labkit::CoveredExperience::Current)
+
+        Labkit::CoveredExperience::Current.reset
+      end
     end
   end
 end

data/lib/labkit/middleware/sidekiq/client.rb

@@ -13,6 +13,7 @@ module Labkit
           @chain ||= ::Sidekiq::Middleware::Chain.new do |chain|
             chain.add Labkit::Middleware::Sidekiq::Context::Client
             chain.add Labkit::Middleware::Sidekiq::Tracing::Client if Labkit::Tracing.enabled?
+            chain.add Labkit::Middleware::Sidekiq::CoveredExperience::Client
           end
         end
 

data/lib/labkit/middleware/sidekiq/covered_experience/client.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'labkit/covered_experience/current'
+
+module Labkit
+  module Middleware
+    module Sidekiq
+      module CoveredExperience
+        # This middleware for Sidekiq-client wraps scheduling jobs with covered
+        # experience context. It retrieves the current experiences and
+        # populates the job with them.
+        class Client
+          def call(worker_class, job, _queue, _redis_pool)
+            data = Labkit::CoveredExperience::Current.active_experiences.inject({}) do |data, (_, xp)|
+              xp.checkpoint(checkpoint_action: "sidekiq_job_scheduled", worker: worker_class.to_s)
+              data.merge!(xp.to_h)
+            end
+
+            job[Labkit::CoveredExperience::Current::AGGREGATION_KEY] = data unless data.empty?
+
+            yield
+          end
+        end
+      end
+    end
+  end
+end

data/lib/labkit/middleware/sidekiq/covered_experience/server.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Labkit
+  module Middleware
+    module Sidekiq
+      module CoveredExperience
+        # This middleware for Sidekiq-server rehydrates the current experiences
+        # serialized to the job
+        class Server
+          def call(_worker_class, job, _queue)
+            job[Labkit::CoveredExperience::Current::AGGREGATION_KEY]&.each do |experience_id, data|
+              xp = Labkit::CoveredExperience::Current.rehydrate(experience_id, **data)
+              xp.checkpoint(checkpoint_action: "sidekiq_job_started", worker: job["class"].to_s)
+            end
+
+            yield
+
+          ensure
+            Labkit::CoveredExperience::Current.reset
+          end
+        end
+      end
+    end
+  end
+end

data/lib/labkit/middleware/sidekiq/covered_experience.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Labkit
+  module Middleware
+    module Sidekiq
+      # This module contains all the sidekiq middleware regarding covered
+      # experiences
+      module CoveredExperience
+        autoload :Client, "labkit/middleware/sidekiq/covered_experience/client"
+        autoload :Server, "labkit/middleware/sidekiq/covered_experience/server"
+      end
+    end
+  end
+end

data/lib/labkit/middleware/sidekiq/server.rb

@@ -13,6 +13,7 @@ module Labkit
           @chain ||= ::Sidekiq::Middleware::Chain.new do |chain|
             chain.add Labkit::Middleware::Sidekiq::Context::Server
             chain.add Labkit::Middleware::Sidekiq::Tracing::Server if Labkit::Tracing.enabled?
+            chain.add Labkit::Middleware::Sidekiq::CoveredExperience::Server
           end
         end
 

data/lib/labkit/middleware/sidekiq.rb

@@ -7,6 +7,7 @@ module Labkit
       autoload :Client, "labkit/middleware/sidekiq/client"
       autoload :Server, "labkit/middleware/sidekiq/server"
       autoload :Context, "labkit/middleware/sidekiq/context"
+      autoload :CoveredExperience, "labkit/middleware/sidekiq/covered_experience"
       autoload :Tracing, "labkit/middleware/sidekiq/tracing"
     end
   end