gitlab-labkit 0.39.0 → 0.40.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 639ab73c3db48ed9078b0ae3743b5031d3d3e89dfde6aff9c65818b9aece82cb
-  data.tar.gz: ab65ac7320604017406ea64242c9dba98665ed12ad0f1268820e75031c301452
+  metadata.gz: 570e79f377fc9cfa11a87177437e6f66a6ed78c94958ad999744034922011e31
+  data.tar.gz: a58252e9bb1792ac0e6ca7e65d565f49803e917eb845de065ffb4921b1bf405c
 SHA512:
-  metadata.gz: 14feead5381e4d99a08cac69768dace5080d394c7267cc4c90fc44d0b5839b24838a16469e627f086a2731ac972f38729cb28cec96e84c2ac0ba5d1c27cc4eeb
-  data.tar.gz: aaae5ce7dbd8454862ce64a93a73280931802575213cfe18c35dee3a7edb410a240937da508b30c2cabe5dbefb0e3e534cbbd2c5a1428dcc2b6b8e90110392d8
+  metadata.gz: eb4718ca04e0c5769180e3e23e3e658ea914a60c12142efc6f26bfc8f25b9a29d467c1c8fb582f23827c4e6cf3c9d72e65d7a7a469ab37465eb479f650e8269a
+  data.tar.gz: 90c9bff31da38826e4d60d6ac623f97257a78fbea63ea86aba8a15dd22df69e069ed628af48fc5f4695d58f1157c098f22a8e9676f97e8345522073349603bf5

data/.copier-answers.yml

@@ -3,10 +3,11 @@
 # See the project for instructions on how to update the project
 #
 # Changes here will be overwritten by Copier; NEVER EDIT MANUALLY
-_commit: v1.31.0
+_commit: v1.35.1
 _src_path: https://gitlab.com/gitlab-com/gl-infra/common-template-copier.git
 ee_licensed: false
 golang: false
+helm: false
 initial_codeowners: '@reprazent @andrewn @mkaeppler @ayufan'
 jsonnet: false
 project_name: labkit-ruby

data/.gitlab-ci-asdf-versions.yml

@@ -1,5 +1,5 @@
 # DO NOT MANUALLY EDIT; Run ./scripts/update-asdf-version-variables.sh to update this
 variables:
-    GL_ASDF_RUBY_VERSION: "3.4.4"
+    GL_ASDF_RUBY_VERSION: "3.4.5"
     GL_ASDF_SHELLCHECK_VERSION: "0.10.0"
-    GL_ASDF_SHFMT_VERSION: "3.11.0"
+    GL_ASDF_SHFMT_VERSION: "3.12"

data/.gitlab-ci.yml

@@ -19,19 +19,13 @@ include:
   # It includes standard checks, gitlab-scanners, validations and release processes
   # common to all projects using this template library.
   # see https://gitlab.com/gitlab-com/gl-infra/common-ci-tasks/-/blob/main/templates/standard.md
-  - project: "gitlab-com/gl-infra/common-ci-tasks"
-    ref: v2.77 # renovate:managed
-    file: templates/standard.yml
+  - component: $CI_SERVER_FQDN/gitlab-com/gl-infra/common-ci-tasks/standard-build@v2.78
 
   # Runs rspec tests and rubocop on the project
   # see https://gitlab.com/gitlab-com/gl-infra/common-ci-tasks/-/blob/main/templates/ruby.md
-  - project: "gitlab-com/gl-infra/common-ci-tasks"
-    ref: v2.77 # renovate:managed
-    file: templates/ruby.yml
+  - component: $CI_SERVER_FQDN/gitlab-com/gl-infra/common-ci-tasks/ruby-build@v2.78
 
-  - project: "gitlab-com/gl-infra/common-ci-tasks"
-    ref: v2.77 # renovate:managed
-    file: "danger.yml"
+  - component: $CI_SERVER_FQDN/gitlab-com/gl-infra/common-ci-tasks/danger@v2.78
 
 .test_template: &test_definition
   extends: .with_bundle

data/.pre-commit-config.yaml

@@ -25,7 +25,7 @@ repos:
   # Documentation available at
   # https://gitlab.com/gitlab-com/gl-infra/common-ci-tasks/-/blob/main/docs/pre-commit.md
   - repo: https://gitlab.com/gitlab-com/gl-infra/common-ci-tasks
-    rev: v2.77  # renovate:managed
+    rev: v2.85  # renovate:managed
 
     hooks:
       - id: shellcheck  # Run shellcheck for changed Shell files

data/.tool-versions

@@ -1,3 +1,3 @@
-ruby 3.4.4
-shfmt 3.11.0
+ruby 3.4.5
+shfmt 3.12
 shellcheck 0.10.0

data/README.md

@@ -19,10 +19,12 @@ The changelog is available via [**tagged release notes**](https://gitlab.com/git
 LabKit-Ruby provides functionality in a number of areas:
 
 1. `Labkit::Context` used for providing context information to log messages.
-1. `Labkit::Correlation` For accessing the correlation id. (Generated and propagated by `Labkit::Context`)
+1. `Labkit::Correlation` for accessing the correlation id. (Generated and propagated by `Labkit::Context`)
+1. `Labkit::CoveredExperience` for tracking covered experiences. More on the [README](./lib/labkit/covered_experiences/README.md).
 1. `Labkit::FIPS` for checking for FIPS mode and using FIPS-compliant algorithms.
 1. `Labkit::Logging` for sanitizing log messages.
 1. `Labkit::Metrics` for metrics. More on the [README](./lib/labkit/metrics/README.md).
+1. `Labkit::RSpec` for RSpec matchers to test Labkit functionality (requires selective loading). More on the [README](./lib/labkit/rspec/README.md).
 1. `Labkit::Tracing` for handling and propagating distributed traces.
 
 ## Developing

data/config/covered_experiences/schema.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "http://json-schema.org/draft-06/schema#",
+  "$id": "https://gitlab.com/gitlab-org/ruby/gems/labkit-ruby/-/raw/master/config/covered_experiences/schema.json",
+  "title": "Covered Experience Definition",
+  "description": "Schema for GitLab Covered Experience files",
+  "type": "object",
+  "properties": {
+    "description": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Human-readable description of the covered experience"
+    },
+    "feature_category": {
+      "type": "string",
+      "minLength": 1,
+      "description": "GitLab feature category this experience belongs to"
+    },
+    "urgency": {
+      "type": "string",
+      "enum": [
+        "sync_fast",
+        "sync_slow",
+        "async_fast",
+        "async_slow"
+      ],
+      "description": "Urgency level for this covered experience"
+    }
+  },
+  "required": [
+    "description",
+    "feature_category",
+    "urgency"
+  ]
+}
+

data/config/covered_experiences/testing_sample.yml

@@ -0,0 +1,4 @@
+# yaml-language-server: $schema=./schema.json
+description: "Creating a new merge request in a project"
+feature_category: "source_code_management"
+urgency: "sync_fast"

data/gitlab-labkit.gemspec

@@ -25,6 +25,7 @@ Gem::Specification.new do |spec|
   spec.add_runtime_dependency "grpc", ">= 1.62" # Be sure to update the "grpc-tools" dev_dependency too
   spec.add_runtime_dependency "google-protobuf", "~> 3" # Keep the major version to 3 until we update the `grpc` gem
   spec.add_runtime_dependency "jaeger-client", "~> 1.1.0"
+  spec.add_runtime_dependency 'json-schema', '~> 5.1'
   spec.add_runtime_dependency "opentracing", "~> 0.4"
   spec.add_runtime_dependency "pg_query", ">= 6.1.0", "< 7.0"
   spec.add_runtime_dependency "prometheus-client-mmap", "~> 1.2.9"

data/lib/gitlab-labkit.rb

@@ -7,8 +7,9 @@
 module Labkit
   autoload :System, "labkit/system"
 
-  autoload :Correlation, "labkit/correlation"
   autoload :Context, "labkit/context"
+  autoload :Correlation, "labkit/correlation"
+  autoload :CoveredExperience, "labkit/covered_experience"
   autoload :FIPS, "labkit/fips"
   autoload :Tracing, "labkit/tracing"
   autoload :Logging, "labkit/logging"

data/lib/labkit/context.rb

@@ -5,6 +5,7 @@ require "securerandom"
 require "active_support/core_ext/module/delegation"
 require "active_support/core_ext/string/starts_ends_with"
 require "active_support/core_ext/string/inflections"
+require "active_support/core_ext/object/blank"
 
 module Labkit
   # A context can be used to provide structured information on what resources

data/lib/labkit/covered_experience/README.md

@@ -0,0 +1,134 @@
+# Covered Experience
+
+This module covers the definition for Covered Experiences, as described in the [blueprint](https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/covered_experience_slis/#covered-experience-definition).
+
+## Configuration
+
+### Logger Configuration
+
+By default, `Labkit::CoveredExperience` uses `Labkit::Logging::JsonLogger.new($stdout)` for logging. You can configure a custom logger:
+
+```ruby
+Labkit::CoveredExperience.configure do |config|
+  config.logger = Labkit::Logging::JsonLogger.new($stdout)
+end
+```
+
+This configuration affects all Covered Experience instances and their logging output.
+
+### Covered Experience Definitions
+
+Covered experience definitions will be lazy loaded from the default directory (`config/covered_experiences`).
+
+Create a new covered experience file in the registry directory, e.g. config/covered_experiences/merge_request_creation.yaml
+
+The basename of the file will be taken as the covered_experience_id.
+
+The schema header is optional, but if you're using VSCode (or any other editor with support), you can get them validated
+instantaneously in the editor via a [JSON schema plugin](https://marketplace.visualstudio.com/items?itemName=remcohaszing.schemastore).
+
+```yaml
+# yaml-language-server: $schema=https://gitlab.com/gitlab-org/ruby/gems/labkit-ruby/-/raw/master/config/covered_experiences/schema.json
+description: "Creating a new merge request in a project"
+feature_category: "source_code_management"
+urgency: "sync_fast"
+```
+
+**Feature category**
+
+https://docs.gitlab.com/development/feature_categorization/#feature-categorization.
+
+**Urgency**
+
+| Threshold    | Description                                                                                                                                                      | Examples                                                                       | Value |
+|--------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------|-------|
+| `sync_fast`  | A user is awaiting a synchronous response which needs to be returned before they can continue with their action                                                  | A full-page render                                                             | 2s    |
+| `sync_slow`  | A user is awaiting a synchronous response which needs to be returned before they can continue with their action, but which the user may accept a slower response | Displaying a full-text search response while displaying an amusement animation | 5s    |
+| `async_fast` | An async process which may block a user from continuing with their user journey                                                                                  | MR diff update after git push                                                  | 15s   |
+| `async_slow` | An async process which will not block a user and will not be immediately noticed as being slow                                                                   | Notification following an assignment                                           | 5m    |
+
+## Usage
+
+The `Labkit::CoveredExperience` module provides a simple API for measuring and tracking covered experiences in your application.
+
+
+#### Accessing a Covered Experience
+
+```ruby
+# Get a covered experience by ID
+experience = Labkit::CoveredExperience.get('merge_request_creation')
+```
+
+#### Using with a Block (Recommended)
+
+The simplest way to use covered experiences is with a block, which automatically handles starting and completing the experience:
+
+```ruby
+Labkit::CoveredExperience.start('merge_request_creation') do |experience|
+  # Your code here
+  create_merge_request
+
+  # Add checkpoints for important milestones
+  experience.checkpoint
+
+  validate_merge_request
+  experience.checkpoint
+
+  send_notifications
+end
+```
+
+#### Manual Control
+
+For more control, you can manually start, checkpoint, and complete experiences:
+
+```ruby
+experience = Labkit::CoveredExperience.get('merge_request_creation')
+experience.start
+
+# Perform some work
+create_merge_request
+
+# Mark important milestones
+experience.checkpoint
+
+# Perform more work
+validate_merge_request
+experience.checkpoint
+
+# Complete the experience
+experience.complete
+```
+
+### Error Handling
+
+When using the block form, errors are automatically captured:
+
+```ruby
+Labkit::CoveredExperience.start('merge_request_creation') do |experience|
+  # If this raises an exception, it will be captured automatically
+  risky_operation
+end
+```
+
+For manual control, you can mark errors explicitly:
+
+```ruby
+experience = Labkit::CoveredExperience.get('merge_request_creation')
+experience.start
+
+begin
+  risky_operation
+rescue StandardError => e
+  experience.error!(e)
+  raise
+ensure
+  experience.complete
+end
+```
+
+### Error Behavior
+
+- In `development` and `test` environments, accessing a non-existent covered experience will raise a `NotFoundError`
+- In other environments, a null object is returned that safely ignores all method calls
+- Attempting to checkpoint or complete an unstarted experience will raise an `UnstartedError` in `development` and `test` environments

data/lib/labkit/covered_experience/error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Labkit
+  module CoveredExperience
+    CoveredExperienceError = Class.new(StandardError)
+    UnstartedError = Class.new(CoveredExperienceError)
+    NotFoundError = Class.new(CoveredExperienceError)
+  end
+end

data/lib/labkit/covered_experience/experience.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+require 'labkit/context'
+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
+
+    # The `Experience` class represents a single Covered Experience
+    # event to be measured and reported.
+    class Experience
+      attr_reader :error
+
+      def initialize(definition)
+        @definition = definition
+      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")
+        log_event("start", **extra)
+
+        return self unless block_given?
+
+        begin
+          yield self
+          self
+        rescue StandardError => e
+          error!(e)
+          raise
+        ensure
+          complete(**extra)
+        end
+      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")
+        log_event("intermediate", **extra)
+
+        self
+      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!
+
+        begin
+          @end_time = Time.now.utc
+        ensure
+          checkpoint_counter.increment(checkpoint: "end")
+          total_counter.increment(error: has_error?)
+          apdex_counter.increment(success: apdex_success?) unless has_error?
+          log_event("end", **extra)
+        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
+
+      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 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',
+          base_labels
+        )
+      end
+
+      def total_counter
+        @total_counter ||= Labkit::Metrics::Client.counter(
+          :gitlab_covered_experience_total,
+          'Total covered experience events (success/failure)',
+          base_labels
+        )
+      end
+
+      def apdex_counter
+        @apdex_counter ||= Labkit::Metrics::Client.counter(
+          :gitlab_covered_experience_apdex_total,
+          'Total covered experience apdex events',
+          base_labels
+        )
+      end
+
+      def log_event(event_type, **extra)
+        log_data = build_log_data(event_type, **extra)
+        logger.info(log_data)
+      end
+
+      def build_log_data(event_type, **extra)
+        log_data = {
+          checkpoint: event_type,
+          covered_experience: @definition.covered_experience,
+          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.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(exception)
+        logger.warn(component: self.class.name, message: exception.message)
+      end
+
+      def logger
+        Labkit::CoveredExperience.configuration.logger
+      end
+    end
+  end
+end

data/lib/labkit/covered_experience/null.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Labkit
+  module CoveredExperience
+    # Fakes Labkit::CoveredExperience::Experience.
+    class Null
+      include Singleton
+
+      attr_reader :id, :description, :feature_category, :urgency
+
+      def start(*_args)
+        yield self if block_given?
+        self
+      end
+
+      def push_attributes!(*_args) = self
+      def checkpoint(*_args) = self
+      def complete(*_args) = self
+      def error!(*_args) = self
+    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,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/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

data/lib/labkit/rspec/matchers/covered_experience_matchers.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+# RSpec matchers for testing Labkit CoveredExperience functionality
+#
+# This file must be explicitly required in your test setup:
+#   require 'labkit/rspec/matchers'
+
+raise LoadError, "RSpec is not loaded. Please require 'rspec' before requiring 'labkit/rspec/matchers'" unless defined?(RSpec)
+
+module Labkit
+  module RSpec
+    module Matchers
+      # Helper module for CoveredExperience functionality
+      module CoveredExperience
+        def attributes(covered_experience_id)
+          raise ArgumentError, "covered_experience_id is required" if covered_experience_id.nil?
+
+          definition = Labkit::CoveredExperience::Registry.new[covered_experience_id]
+          definition.to_h.slice(:covered_experience, :feature_category, :urgency)
+        end
+
+        def checkpoint_counter
+          Labkit::Metrics::Client.get(:gitlab_covered_experience_checkpoint_total)
+        end
+
+        def total_counter
+          Labkit::Metrics::Client.get(:gitlab_covered_experience_total)
+        end
+
+        def apdex_counter
+          Labkit::Metrics::Client.get(:gitlab_covered_experience_apdex_total)
+        end
+      end
+    end
+  end
+end
+
+# Matcher for verifying CoveredExperience start metrics instrumentation.
+#
+# Usage:
+#   expect { subject }.to start_covered_experience('rails_request')
+#
+# This matcher verifies that the following metric is incremented:
+# - gitlab_covered_experience_checkpoint_total (with checkpoint=start)
+#
+# Parameters:
+# - covered_experience_id: Required. The ID of the covered experience (e.g., 'rails_request')
+RSpec::Matchers.define :start_covered_experience do |covered_experience_id|
+  include Labkit::RSpec::Matchers::CoveredExperience
+
+  description { "start covered experience '#{covered_experience_id}'" }
+  supports_block_expectations
+
+  match do |actual|
+    labels = attributes(covered_experience_id)
+
+    checkpoint_before = checkpoint_counter&.get(labels.merge(checkpoint: "start")).to_i
+
+    actual.call
+
+    checkpoint_after = checkpoint_counter&.get(labels.merge(checkpoint: "start")).to_i
+
+    @checkpoint_change = checkpoint_after - checkpoint_before
+
+    @checkpoint_change == 1
+  end
+
+  failure_message do
+    "Failed to checkpoint covered experience '#{covered_experience_id}':\n" \
+      "expected checkpoint='start' counter to increase by 1, but increased by #{@checkpoint_change}"
+  end
+end
+
+# Matcher for verifying CoveredExperience checkpoint metrics instrumentation.
+#
+# Usage:
+#   expect { subject }.to checkpoint_covered_experience('rails_request')
+#
+# This matcher verifies that the following metric is incremented:
+# - gitlab_covered_experience_checkpoint_total (with checkpoint=intermediate)
+#
+# Parameters:
+# - covered_experience_id: Required. The ID of the covered experience (e.g., 'rails_request')
+RSpec::Matchers.define :checkpoint_covered_experience do |covered_experience_id|
+  include Labkit::RSpec::Matchers::CoveredExperience
+
+  description { "checkpoint covered experience '#{covered_experience_id}'" }
+  supports_block_expectations
+
+  match do |actual|
+    labels = attributes(covered_experience_id)
+
+    checkpoint_before = checkpoint_counter&.get(labels.merge(checkpoint: "intermediate")).to_i
+
+    actual.call
+
+    checkpoint_after = checkpoint_counter&.get(labels.merge(checkpoint: "intermediate")).to_i
+    @checkpoint_change = checkpoint_after - checkpoint_before
+
+    @checkpoint_change == 1
+  end
+
+  failure_message do
+    "Failed to checkpoint covered experience '#{covered_experience_id}':\n" \
+      "expected checkpoint='intermediate' counter to increase by 1, but increased by #{@checkpoint_change}"
+  end
+
+  match_when_negated do |actual|
+    labels = attributes(covered_experience_id)
+
+    checkpoint_before = checkpoint_counter&.get(labels.merge(checkpoint: "intermediate")).to_i
+
+    actual.call
+
+    checkpoint_after = checkpoint_counter&.get(labels.merge(checkpoint: "intermediate")).to_i
+    @checkpoint_change = checkpoint_after - checkpoint_before
+
+    @checkpoint_change.zero?
+  end
+
+  failure_message_when_negated do
+    "Expected covered experience '#{covered_experience_id}' NOT to checkpoint:\n" \
+      "expected checkpoint='intermediate' counter to increase by 0, but increased by #{@checkpoint_change}"
+  end
+end
+
+# Matcher for verifying CoveredExperience completion metrics instrumentation.
+#
+# Usage:
+#   expect { subject }.to complete_covered_experience('rails_request')
+#
+# This matcher verifies that the following metrics are incremented with specific labels:
+# - gitlab_covered_experience_checkpoint_total (with checkpoint=end)
+# - gitlab_covered_experience_total (with error=false)
+# - gitlab_covered_experience_apdex_total (with success=true)
+#
+# Parameters:
+# - covered_experience_id: Required. The ID of the covered experience (e.g., 'rails_request')
+# - error: Optional. The expected error flag for gitlab_covered_experience_total (false by default)
+# - success: Optional. The expected success flag for gitlab_covered_experience_apdex_total (true by default)
+RSpec::Matchers.define :complete_covered_experience do |covered_experience_id, error: false, success: true|
+  include Labkit::RSpec::Matchers::CoveredExperience
+
+  description { "complete covered experience '#{covered_experience_id}'" }
+  supports_block_expectations
+
+  match do |actual|
+    labels = attributes(covered_experience_id)
+
+    checkpoint_before = checkpoint_counter&.get(labels.merge(checkpoint: "end")).to_i
+    total_before = total_counter&.get(labels.merge(error: error)).to_i
+    apdex_before = apdex_counter&.get(labels.merge(success: success)).to_i
+
+    actual.call
+
+    checkpoint_after = checkpoint_counter&.get(labels.merge(checkpoint: "end")).to_i
+    total_after = total_counter&.get(labels.merge(error: error)).to_i
+    apdex_after = apdex_counter&.get(labels.merge(success: success)).to_i
+    @checkpoint_change = checkpoint_after - checkpoint_before
+    @total_change = total_after - total_before
+    @apdex_change = apdex_after - apdex_before
+
+    @checkpoint_change == 1 && @total_change == 1 && @apdex_change == (error ? 0 : 1)
+  end
+
+  failure_message do
+    "Failed to complete covered experience '#{covered_experience_id}':\n" \
+      "expected checkpoint='end' counter to increase by 1, but increased by #{@checkpoint_change}\n" \
+      "expected total='error: #{error}' counter to increase by 1, but increased by #{@total_change}\n" \
+      "expected apdex='success: #{success}' counter to increase by 1, but increased by #{@apdex_change}"
+  end
+
+  match_when_negated do |actual|
+    labels = attributes(covered_experience_id)
+
+    checkpoint_before = checkpoint_counter&.get(labels.merge(checkpoint: "end")).to_i
+    total_before = total_counter&.get(labels.merge(error: error)).to_i
+    apdex_before = apdex_counter&.get(labels.merge(success: success)).to_i
+
+    actual.call
+
+    checkpoint_after = checkpoint_counter&.get(labels.merge(checkpoint: "end")).to_i
+    total_after = total_counter&.get(labels.merge(error: error)).to_i
+    apdex_after = apdex_counter&.get(labels.merge(success: success)).to_i
+    @checkpoint_change = checkpoint_after - checkpoint_before
+    @total_change = total_after - total_before
+    @apdex_change = apdex_after - apdex_before
+
+    @checkpoint_change.zero? && @total_change.zero? && @apdex_change == (error ? 1 : 0)
+  end
+
+  failure_message_when_negated do
+    "Failed covered experience '#{covered_experience_id}' NOT to complete:\n" \
+      "expected checkpoint='end' counter to increase by 0, but increased by #{@checkpoint_change}\n" \
+      "expected total='error: #{error}' counter to increase by 0, but increased by #{@total_change}\n" \
+      "expected apdex='success: #{success}' counter to increase by 0, but increased by #{@apdex_change}"
+  end
+end

data/lib/labkit/rspec/matchers.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# RSpec matchers loader for Labkit
+#
+# This file loads all available RSpec matchers for Labkit.
+# It must be explicitly required in your test setup.
+
+raise LoadError, "RSpec is not loaded. Please require 'rspec' before requiring 'labkit/rspec/matchers'" unless defined?(RSpec)
+
+require_relative 'matchers/covered_experience_matchers'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gitlab-labkit
 version: !ruby/object:Gem::Version
-  version: 0.39.0
+  version: 0.40.0
 platform: ruby
 authors:
 - Andrew Newdigate
@@ -91,6 +91,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 1.1.0
+- !ruby/object:Gem::Dependency
+  name: json-schema
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.1'
 - !ruby/object:Gem::Dependency
   name: opentracing
   requirement: !ruby/object:Gem::Requirement
@@ -433,6 +447,8 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- config/covered_experiences/schema.json
+- config/covered_experiences/testing_sample.yml
 - gitlab-labkit.gemspec
 - lib/gitlab-labkit.rb
 - lib/labkit/context.rb
@@ -442,6 +458,12 @@ files:
 - lib/labkit/correlation/grpc/client_interceptor.rb
 - lib/labkit/correlation/grpc/grpc_common.rb
 - lib/labkit/correlation/grpc/server_interceptor.rb
+- lib/labkit/covered_experience.rb
+- lib/labkit/covered_experience/README.md
+- lib/labkit/covered_experience/error.rb
+- lib/labkit/covered_experience/experience.rb
+- lib/labkit/covered_experience/null.rb
+- lib/labkit/covered_experience/registry.rb
 - lib/labkit/excon_publisher.rb
 - lib/labkit/fips.rb
 - lib/labkit/httpclient_publisher.rb
@@ -469,6 +491,9 @@ files:
 - lib/labkit/middleware/sidekiq/tracing/server.rb
 - lib/labkit/middleware/sidekiq/tracing/sidekiq_common.rb
 - lib/labkit/net_http_publisher.rb
+- lib/labkit/rspec/README.md
+- lib/labkit/rspec/matchers.rb
+- lib/labkit/rspec/matchers/covered_experience_matchers.rb
 - lib/labkit/system.rb
 - lib/labkit/tracing.rb
 - lib/labkit/tracing/abstract_instrumenter.rb
@@ -525,7 +550,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Instrumentation for GitLab
 test_files: []