gitlab-labkit 0.42.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 869346480f346d49795eaf4f80e028c4cdbbdb8826345cfcfdff8ddf8e1887fd
-  data.tar.gz: 63ce86b345417ab4c6ad076dd6f83baca61d4e127c478b857e509c4b34814000
+  metadata.gz: 848c7a3b2a208349e041ead5190bb2f665190100e9c4868b3391f040674834b7
+  data.tar.gz: be220cf29fa57499b1101cabda163816fd37f77b09b5b3be93464cd87c6294b6
 SHA512:
-  metadata.gz: c18e81580f71d9d6833e5d7c07d58fb699ec82df5d8707af38adbedabe6e7a197d0fe1e3cef00f0df7afa740dc5f343c100faf283e97d586419a1134bcf0501b
-  data.tar.gz: c5d346b9f186a33faa420e5e6fe8513f7af58c829748fe98470c5b6d45d27cb0c2620f56f4cca56729e896ea3daf59d9caa3bdca4aad95b79c3fed5b0052635c
+  metadata.gz: e5e4181d842aa238bc113b4d1486471f71b44e3d04d7f8613583e2ae23eeb33a4c6e275a5fccb18b2db5a962c0e4ff294b2df7a6eb9bd6c08a8aaf88a9146a96
+  data.tar.gz: eeab7e40652242988f381b9192a9384a9098a7bd31ad8ef6e8f0b17c5c6f17032a8f2199f9b1fbe543e9d11ba04a30cb5c59a2b96d9bb86df3a30a026924e96f

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.6"
+    GL_ASDF_RUBY_VERSION: "3.4.7"
     GL_ASDF_SHELLCHECK_VERSION: "0.11"
     GL_ASDF_SHFMT_VERSION: "3.12"

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.94  # renovate:managed
+    rev: v3.0  # renovate:managed
 
     hooks:
       - id: shellcheck  # Run shellcheck for changed Shell files

data/.tool-versions

@@ -1,3 +1,3 @@
-ruby 3.4.6
+ruby 3.4.7
 shfmt 3.12
 shellcheck 0.11

data/README.md

@@ -20,7 +20,7 @@ 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::CoveredExperience` for tracking covered experiences. More on the [README](./lib/labkit/covered_experience/README.md).
+1. `Labkit::UserExperienceSli` for tracking User Experience SLIs. More on the [README](./lib/labkit/user_experience_sli/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).

data/config/{covered_experiences → user_experience_slis}/schema.json

@@ -1,14 +1,14 @@
 {
   "$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",
+  "$id": "https://gitlab.com/gitlab-org/ruby/gems/labkit-ruby/-/raw/master/config/user_experience_slis/schema.json",
+  "title": "User Experience SLI Definition",
+  "description": "Schema for GitLab User Experience SLI files",
   "type": "object",
   "properties": {
     "description": {
       "type": "string",
       "minLength": 1,
-      "description": "Human-readable description of the covered experience"
+      "description": "Human-readable description of the user experience"
     },
     "feature_category": {
       "type": "string",
@@ -23,7 +23,7 @@
         "async_fast",
         "async_slow"
       ],
-      "description": "Urgency level for this covered experience"
+      "description": "Urgency level for this user experience"
     }
   },
   "required": [

data/gitlab-labkit.gemspec

@@ -22,7 +22,7 @@ Gem::Specification.new do |spec|
   # Please maintain alphabetical order for dependencies
   spec.add_runtime_dependency "actionpack", ">= 5.0.0", "< 8.1.0"
   spec.add_runtime_dependency "activesupport", ">= 5.0.0", "< 8.1.0"
-  spec.add_runtime_dependency "grpc", ">= 1.62" # Be sure to update the "grpc-tools" dev_dependency too
+  spec.add_runtime_dependency "grpc", ">= 1.75" # 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'
@@ -36,7 +36,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "faraday", "~> 1.10.3"
   spec.add_development_dependency "gitlab-dangerfiles", "~> 2.11.0"
   spec.add_development_dependency "gitlab-styles", "~> 13.0.2"
-  spec.add_development_dependency "grpc-tools", ">= 1.62"
+  spec.add_development_dependency "grpc-tools", ">= 1.75"
   spec.add_development_dependency "httparty", "~> 0.22.0"
   spec.add_development_dependency "httpclient", "~> 2.9.0"
   spec.add_development_dependency "irb", "~> 1.15.2"

data/lib/gitlab-labkit.rb

@@ -9,7 +9,8 @@ module Labkit
 
   autoload :Context, "labkit/context"
   autoload :Correlation, "labkit/correlation"
-  autoload :CoveredExperience, "labkit/covered_experience"
+  autoload :CoveredExperience, "labkit/user_experience_sli" # Backward compatibility alias
+  autoload :UserExperienceSli, "labkit/user_experience_sli"
   autoload :FIPS, "labkit/fips"
   autoload :Tracing, "labkit/tracing"
   autoload :Logging, "labkit/logging"

data/lib/labkit/fields.rb

@@ -18,24 +18,37 @@ module Labkit
   #   data[Labkit::Fields::GL_USER_ID] = user.id
   #   ...
   #
+  # Labkit (Go): https://gitlab.com/gitlab-org/labkit/-/tree/master/fields?ref_type=heads
+  #
+  # For Engineers Looking to add fields:
+  #
+  # These fields are derived from the Go Labkit variant. Please ensure that you've made the
+  # respective changes in that repository prior to including the fields in this package.
+  #
+  # Please see the handbook page for more information
+  # https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/observability_field_standardisation/
   module Fields
     # correlation_id - string
     #
+    # correlation_id - string
     # This field is used to correlate
     # the logs emitted by all of our systems.
-    #
     # This should be present in all log line
     # emissions.
     CORRELATION_ID = "correlation_id"
 
-    # We'll need to add the rest of the top
-    # level fields here:
-    # [endpoint_id, duration_s, status_code]
-
-    # gl_user_id - integer
+    # GitLabUserID - an integer field that
+    # captures the user's numeric ID for logging purposes.
     GL_USER_ID = "gl_user_id"
 
-    # gl_user_name - string
+    # GitLabUserName - a string field that
+    # captures the user's username for logging purposes.
     GL_USER_NAME = "gl_user_name"
+
+    # New fields being added to this section should have
+    # the appropriate doc comments added above. These
+    # should clearly indicate what the intended use of the
+    # field is and should be replicated across the labkit
+    # variations.
   end
 end

data/lib/labkit/middleware/rack.rb

@@ -59,13 +59,13 @@ module Labkit
       # 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
+      # By explicitly resetting here, we ensure user 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)
+        return unless defined?(Labkit::UserExperienceSli::Current)
 
-        Labkit::CoveredExperience::Current.reset
+        Labkit::UserExperienceSli::Current.reset
       end
     end
   end

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

@@ -13,7 +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
+            chain.add Labkit::Middleware::Sidekiq::UserExperienceSli::Client
           end
         end
 

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

@@ -13,7 +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
+            chain.add Labkit::Middleware::Sidekiq::UserExperienceSli::Server
           end
         end
 

data/lib/labkit/middleware/sidekiq/{covered_experience → user_experience_sli}/client.rb

@@ -1,22 +1,22 @@
 # frozen_string_literal: true
 
-require 'labkit/covered_experience/current'
+require 'labkit/user_experience_sli/current'
 
 module Labkit
   module Middleware
     module Sidekiq
-      module CoveredExperience
+      module UserExperienceSli
         # 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)|
+            data = Labkit::UserExperienceSli::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?
+            job[Labkit::UserExperienceSli::Current::AGGREGATION_KEY] = data unless data.empty?
 
             yield
           end

data/lib/labkit/middleware/sidekiq/{covered_experience → user_experience_sli}/server.rb

@@ -3,20 +3,20 @@
 module Labkit
   module Middleware
     module Sidekiq
-      module CoveredExperience
+      module UserExperienceSli
         # 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)
+            job[Labkit::UserExperienceSli::Current::AGGREGATION_KEY]&.each do |experience_id, data|
+              xp = Labkit::UserExperienceSli::Current.rehydrate(experience_id, **data)
               xp.checkpoint(checkpoint_action: "sidekiq_job_started", worker: job["class"].to_s)
             end
 
             yield
 
           ensure
-            Labkit::CoveredExperience::Current.reset
+            Labkit::UserExperienceSli::Current.reset
           end
         end
       end

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

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Labkit
+  module Middleware
+    module Sidekiq
+      # This module contains all the sidekiq middleware regarding user
+      # experience SLIs
+      module UserExperienceSli
+        autoload :Client, "labkit/middleware/sidekiq/user_experience_sli/client"
+        autoload :Server, "labkit/middleware/sidekiq/user_experience_sli/server"
+      end
+
+      # Backward compatibility alias
+      CoveredExperience = UserExperienceSli
+    end
+  end
+end

data/lib/labkit/middleware/sidekiq.rb

@@ -7,7 +7,8 @@ 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 :UserExperienceSli, "labkit/middleware/sidekiq/user_experience_sli"
+      autoload :CoveredExperience, "labkit/middleware/sidekiq/user_experience_sli" # Backward compatibility
       autoload :Tracing, "labkit/middleware/sidekiq/tracing"
     end
   end

data/lib/labkit/rspec/README.md

@@ -19,61 +19,70 @@ This approach ensures that:
 
 ## Available Matchers
 
-### Covered Experience Matchers
+### User Experience Matchers
 
-These matchers help you test that your code properly instruments covered experiences with the expected metrics.
+These matchers help you test that your code properly instruments user experience SLIs with the expected metrics.
 
-#### `start_covered_experience`
+#### `start_user_experience`
 
-Tests that a covered experience is started (checkpoint=start metric is incremented).
+Tests that a user experience is started (checkpoint=start metric is incremented).
 
 ```ruby
-expect { subject }.to start_covered_experience('rails_request')
+expect { subject }.to start_user_experience('rails_request')
 
 # Test that it does NOT start
-expect { subject }.not_to start_covered_experience('rails_request')
+expect { subject }.not_to start_user_experience('rails_request')
 ```
 
-#### `checkpoint_covered_experience`
+#### `checkpoint_user_experience`
 
-Tests that a covered experience checkpoint is recorded (checkpoint=intermediate metric is incremented).
+Tests that a user experience checkpoint is recorded (checkpoint=intermediate metric is incremented).
 
 ```ruby
-expect { subject }.to checkpoint_covered_experience('rails_request')
+expect { subject }.to checkpoint_user_experience('rails_request')
 
 # Test that it does NOT checkpoint
-expect { subject }.not_to checkpoint_covered_experience('rails_request')
+expect { subject }.not_to checkpoint_user_experience('rails_request')
 ```
 
-#### `resume_covered_experience`
+#### `resume_user_experience`
 
-Tests that a covered experience is resumed (checkpoint=intermediate metric is incremented). This is an alias for `checkpoint_covered_experience` that provides more semantic meaning when testing code that resumes a covered experience previously started.
+Tests that a user experience is resumed (checkpoint=intermediate metric is incremented). This is an alias for `checkpoint_user_experience` that provides more semantic meaning when testing code that resumes a user experience previously started.
 
 ```ruby
-expect { subject }.to resume_covered_experience('rails_request')
+expect { subject }.to resume_user_experience('rails_request')
 
 # Test that it does NOT resume
-expect { subject }.not_to resume_covered_experience('rails_request')
+expect { subject }.not_to resume_user_experience('rails_request')
 ```
 
-#### `complete_covered_experience`
+#### `complete_user_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)
+Tests that a user experience is completed with the expected metrics:
+- `gitlab_user_experience_checkpoint_total` (with checkpoint=end)
+- `gitlab_user_experience_total` (with error flag)
+- `gitlab_user_experience_apdex_total` (with success flag)
 
 ```ruby
 # Test successful completion
-expect { subject }.to complete_covered_experience('rails_request')
+expect { subject }.to complete_user_experience('rails_request')
 
 # Test completion with error
-expect { subject }.to complete_covered_experience('rails_request', error: true, success: false)
+expect { subject }.to complete_user_experience('rails_request', error: true, success: false)
 
 # Test that it does NOT complete
-expect { subject }.not_to complete_covered_experience('rails_request')
+expect { subject }.not_to complete_user_experience('rails_request')
 ```
 
+### Legacy Matchers (Backward Compatibility)
+
+For backward compatibility, the following legacy matchers are still available but deprecated. Please migrate to the new `*_user_experience` matchers above.
+
+- `start_covered_experience`
+- `checkpoint_covered_experience`
+- `resume_covered_experience`
+- `complete_covered_experience`
+
 ## Example Usage
 
 ### In your spec_helper.rb or rails_helper.rb:
@@ -96,8 +105,8 @@ end
 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')
+      expect { get :index }.to start_user_experience('rails_request')
+        .and complete_user_experience('rails_request')
     end
 
     context 'when an error occurs' do
@@ -106,7 +115,7 @@ RSpec.describe MyController, type: :controller do
       end
 
       it 'records the error in metrics' do
-        expect { get :index }.to complete_covered_experience('rails_request', error: true, success: false)
+        expect { get :index }.to complete_user_experience('rails_request', error: true, success: false)
       end
     end
   end
@@ -127,6 +136,6 @@ end
 
 ## Requirements
 
-- The covered experience must be registered in `Labkit::CoveredExperience::Registry`
+- The user experience SLI must be registered in `Labkit::UserExperienceSli::Registry`
 - Metrics must be properly configured in your test environment
-- The code under test must use Labkit's covered experience instrumentation
+- The code under test must use Labkit's user experience SLI instrumentation

data/lib/labkit/rspec/matchers/{covered_experience_matchers.rb → user_experience_matchers.rb}

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# RSpec matchers for testing Labkit CoveredExperience functionality
+# RSpec matchers for testing Labkit UserExperience functionality
 #
 # This file must be explicitly required in your test setup:
 #   require 'labkit/rspec/matchers'
@@ -10,49 +10,49 @@ raise LoadError, "RSpec is not loaded. Please require 'rspec' before requiring '
 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?
+      # Helper module for UserExperience functionality
+      module UserExperience
+        def attributes(user_experience_id)
+          raise ArgumentError, "user_experience_id is required" if user_experience_id.nil?
 
-          definition = Labkit::CoveredExperience::Registry.new[covered_experience_id]
-          definition.to_h.slice(:covered_experience, :feature_category, :urgency)
+          definition = Labkit::UserExperienceSli::Registry.new[user_experience_id]
+          definition.to_h.slice(:user_experience_id, :feature_category, :urgency)
         end
 
         def checkpoint_counter
-          Labkit::Metrics::Client.get(:gitlab_covered_experience_checkpoint_total)
+          Labkit::Metrics::Client.get(:gitlab_user_experience_checkpoint_total)
         end
 
         def total_counter
-          Labkit::Metrics::Client.get(:gitlab_covered_experience_total)
+          Labkit::Metrics::Client.get(:gitlab_user_experience_total)
         end
 
         def apdex_counter
-          Labkit::Metrics::Client.get(:gitlab_covered_experience_apdex_total)
+          Labkit::Metrics::Client.get(:gitlab_user_experience_apdex_total)
         end
       end
     end
   end
 end
 
-# Matcher for verifying CoveredExperience start metrics instrumentation.
+# Matcher for verifying UserExperience start metrics instrumentation.
 #
 # Usage:
-#   expect { subject }.to start_covered_experience('rails_request')
+#   expect { subject }.to start_user_experience('rails_request')
 #
 # This matcher verifies that the following metric is incremented:
-# - gitlab_covered_experience_checkpoint_total (with checkpoint=start)
+# - gitlab_user_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
+# - user_experience_id: Required. The ID of the user experience (e.g., 'rails_request')
+RSpec::Matchers.define :start_user_experience do |user_experience_id|
+  include Labkit::RSpec::Matchers::UserExperience
 
-  description { "start covered experience '#{covered_experience_id}'" }
+  description { "start user experience '#{user_experience_id}'" }
   supports_block_expectations
 
   match do |actual|
-    labels = attributes(covered_experience_id)
+    labels = attributes(user_experience_id)
 
     checkpoint_before = checkpoint_counter&.get(labels.merge(checkpoint: "start")).to_i
 
@@ -66,29 +66,29 @@ RSpec::Matchers.define :start_covered_experience do |covered_experience_id|
   end
 
   failure_message do
-    "Failed to checkpoint covered experience '#{covered_experience_id}':\n" \
+    "Failed to checkpoint user experience '#{user_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.
+# Matcher for verifying UserExperience checkpoint metrics instrumentation.
 #
 # Usage:
-#   expect { subject }.to checkpoint_covered_experience('rails_request')
+#   expect { subject }.to checkpoint_user_experience('rails_request')
 #
 # This matcher verifies that the following metric is incremented:
-# - gitlab_covered_experience_checkpoint_total (with checkpoint=intermediate)
+# - gitlab_user_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, by: 1|
-  include Labkit::RSpec::Matchers::CoveredExperience
+# - user_experience_id: Required. The ID of the user experience (e.g., 'rails_request')
+RSpec::Matchers.define :checkpoint_user_experience do |user_experience_id, by: 1|
+  include Labkit::RSpec::Matchers::UserExperience
 
-  description { "checkpoint covered experience '#{covered_experience_id}'" }
+  description { "checkpoint user experience '#{user_experience_id}'" }
   supports_block_expectations
 
   match do |actual|
-    labels = attributes(covered_experience_id)
+    labels = attributes(user_experience_id)
 
     checkpoint_before = checkpoint_counter&.get(labels.merge(checkpoint: "intermediate")).to_i
 
@@ -104,12 +104,12 @@ RSpec::Matchers.define :checkpoint_covered_experience do |covered_experience_id,
   end
 
   failure_message do
-    "Failed to checkpoint covered experience '#{covered_experience_id}':\n" \
+    "Failed to checkpoint user experience '#{user_experience_id}':\n" \
       "expected checkpoint='intermediate' counter to increase by at least #{by}, but increased by #{@checkpoint_change}"
   end
 
   match_when_negated do |actual|
-    labels = attributes(covered_experience_id)
+    labels = attributes(user_experience_id)
 
     checkpoint_before = checkpoint_counter&.get(labels.merge(checkpoint: "intermediate")).to_i
 
@@ -122,36 +122,36 @@ RSpec::Matchers.define :checkpoint_covered_experience do |covered_experience_id,
   end
 
   failure_message_when_negated do
-    "Expected covered experience '#{covered_experience_id}' NOT to checkpoint:\n" \
+    "Expected user experience '#{user_experience_id}' NOT to checkpoint:\n" \
       "expected checkpoint='intermediate' counter not to increase, but increased by #{@checkpoint_change}"
   end
 end
 
-# Alias for checkpoint_covered_experience matcher
-RSpec::Matchers.alias_matcher :resume_covered_experience, :checkpoint_covered_experience
+# Alias for checkpoint_user_experience matcher
+RSpec::Matchers.alias_matcher :resume_user_experience, :checkpoint_user_experience
 
-# Matcher for verifying CoveredExperience completion metrics instrumentation.
+# Matcher for verifying UserExperience completion metrics instrumentation.
 #
 # Usage:
-#   expect { subject }.to complete_covered_experience('rails_request')
+#   expect { subject }.to complete_user_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)
+# - gitlab_user_experience_checkpoint_total (with checkpoint=end)
+# - gitlab_user_experience_total (with error=false)
+# - gitlab_user_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
+# - user_experience_id: Required. The ID of the user experience (e.g., 'rails_request')
+# - error: Optional. The expected error flag for gitlab_user_experience_total (false by default)
+# - success: Optional. The expected success flag for gitlab_user_experience_apdex_total (true by default)
+RSpec::Matchers.define :complete_user_experience do |user_experience_id, error: false, success: true|
+  include Labkit::RSpec::Matchers::UserExperience
 
-  description { "complete covered experience '#{covered_experience_id}'" }
+  description { "complete user experience '#{user_experience_id}'" }
   supports_block_expectations
 
   match do |actual|
-    labels = attributes(covered_experience_id)
+    labels = attributes(user_experience_id)
 
     checkpoint_before = checkpoint_counter&.get(labels.merge(checkpoint: "end")).to_i
     total_before = total_counter&.get(labels.merge(error: error)).to_i
@@ -170,14 +170,14 @@ RSpec::Matchers.define :complete_covered_experience do |covered_experience_id, e
   end
 
   failure_message do
-    "Failed to complete covered experience '#{covered_experience_id}':\n" \
+    "Failed to complete user experience '#{user_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)
+    labels = attributes(user_experience_id)
 
     checkpoint_before = checkpoint_counter&.get(labels.merge(checkpoint: "end")).to_i
     total_before = total_counter&.get(labels.merge(error: error)).to_i
@@ -196,9 +196,15 @@ RSpec::Matchers.define :complete_covered_experience do |covered_experience_id, e
   end
 
   failure_message_when_negated do
-    "Failed covered experience '#{covered_experience_id}' NOT to complete:\n" \
+    "Failed user experience '#{user_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
+
+# Backward compatibility matchers for CoveredExperience
+RSpec::Matchers.alias_matcher :start_covered_experience, :start_user_experience
+RSpec::Matchers.alias_matcher :checkpoint_covered_experience, :checkpoint_user_experience
+RSpec::Matchers.alias_matcher :resume_covered_experience, :checkpoint_user_experience
+RSpec::Matchers.alias_matcher :complete_covered_experience, :complete_user_experience

data/lib/labkit/rspec/matchers.rb

@@ -7,4 +7,4 @@
 
 raise LoadError, "RSpec is not loaded. Please require 'rspec' before requiring 'labkit/rspec/matchers'" unless defined?(RSpec)
 
-require_relative 'matchers/covered_experience_matchers'
+require_relative 'matchers/user_experience_matchers'