gitlab-labkit 1.9.0 → 1.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ce6ea44972e6b4b1831c66fd9980f6b501d7c517d89e987cd13e54fa8869fd8d
-  data.tar.gz: e03f282e419b06a8a030eaf5b9215eb99ced4883064c66abbca3ca84f9d452bf
+  metadata.gz: ce9130ded76934b6e21e82724c7371548b9e790e451179a7e70cd14f545969d7
+  data.tar.gz: 1463999f63f123911a57a45d6943fb68e25daa07338cc2afd49f9592cb71ffb0
 SHA512:
-  metadata.gz: 602a91b5315f74bdfd68997e7c5dd7bc4c4ec888fb7ab79e68baa98ca0173b77d59a826bcdb695c492665ef3d3f46e586863ea06274245b0d8047e46297408bd
-  data.tar.gz: 7d972eaf40419b5b4c33ae4c283a72d496cfc81be35386d16924fc133b9b94f028456bd9e0bfc7f076799239f938dee931b7a7a20c690cabcb4fcab571df8b8a
+  metadata.gz: df940f5abe8e939c2bb84440ed9ad340dc2e4a359dddc330d752f778e1d9c7c5aa2a6d19ee233081a7fc0cfd512e7cf5e54ad44fd419d11b2d0f85030ad6fd56
+  data.tar.gz: eee7205f950d1c9bf59060d25d0e5e7a196dadc98b521064813014129e022b2e3c9a5adfad68332b4ba1e2b9f75cbe6a6e8625cc228daa9d2976edbc05a31c25

data/.copier-answers.yml

@@ -3,7 +3,7 @@
 # See the project for instructions on how to update the project
 #
 # Changes here will be overwritten by Copier; NEVER EDIT MANUALLY
-_commit: v1.43.0
+_commit: v1.45.0
 _src_path: https://gitlab.com/gitlab-com/gl-infra/common-template-copier.git
 ee_licensed: false
 golang: false

data/CODEOWNERS

@@ -1,4 +1,4 @@
 # CODEOWNERS is used to lookup assignees for
 # Renovate Bot dependency change Merge Requests.
 # https://docs.renovatebot.com/configuration-options/#assigneesfromcodeowners
-* @reprazent @andrewn @mkaeppler @ayufan @hmerscher @d.barrett @splattael
+* @reprazent @andrewn @mkaeppler @ayufan @hmerscher @d.barrett @splattael @e_forbes @M_Alvarez

data/lib/labkit/rspec/README.md

@@ -74,15 +74,6 @@ expect { subject }.to complete_user_experience('rails_request', error: true, suc
 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:

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

@@ -203,6 +203,59 @@ RSpec::Matchers.define :complete_user_experience do |user_experience_id, error:
   end
 end
 
+# Matcher for verifying UserExperience observed metrics instrumentation.
+#
+# Usage:
+#   expect { subject }.to observed_user_experience('rails_request')
+#
+# This matcher verifies that the following metrics are incremented with specific labels:
+# - gitlab_user_experience_checkpoint_total (with checkpoint=start)
+# - gitlab_user_experience_checkpoint_total (with checkpoint=end)
+# - gitlab_user_experience_total (with error=false)
+# - gitlab_user_experience_apdex_total (with success=true)
+#
+# Parameters:
+# - 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 :observed_user_experience do |user_experience_id, error: false, success: true|
+  include Labkit::RSpec::Matchers::UserExperience
+
+  description { "observe user experience '#{user_experience_id}'" }
+  supports_block_expectations
+
+  match do |actual|
+    labels = attributes(user_experience_id)
+
+    start_before = checkpoint_counter&.get(labels.merge(checkpoint: "start")).to_i
+    end_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
+
+    start_after = checkpoint_counter&.get(labels.merge(checkpoint: "start")).to_i
+    end_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
+
+    @start_change = start_after - start_before
+    @end_change = end_after - end_before
+    @total_change = total_after - total_before
+    @apdex_change = apdex_after - apdex_before
+
+    @start_change == 1 && @end_change == 1 && @total_change == 1 && @apdex_change == (error ? 0 : 1)
+  end
+
+  failure_message do
+    "Failed to observe user experience '#{user_experience_id}':\n" \
+      "expected checkpoint='start' counter to increase by 1, but increased by #{@start_change}\n" \
+      "expected checkpoint='end' counter to increase by 1, but increased by #{@end_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 #{error ? 0 : 1}, 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

data/lib/labkit/user_experience_sli/README.md

@@ -161,6 +161,26 @@ experience.checkpoint
 experience.complete
 ```
 
+#### Observing a Past Experience
+
+When an action already happened and you want to record its duration retroactively, use `observed`. It fires the start and end metrics without registering in the active context:
+
+```ruby
+Labkit::UserExperienceSli.observed('merge_request_creation', start_time: start_time_of_past_action)
+```
+
+You can also signal that an error occurred during the action:
+
+```ruby
+Labkit::UserExperienceSli.observed('merge_request_creation', start_time: start_time_of_past_action, error: true)
+```
+
+Extra labels are forwarded to both the start and end log events:
+
+```ruby
+Labkit::UserExperienceSli.observed('merge_request_creation', start_time: start_time_of_past_action, worker: 'MyWorker')
+```
+
 #### Resuming Experiences
 
 You can resume a user experience SLI that was previously started and stored in the context. This is useful for distributed operations or when work spans multiple processes.

data/lib/labkit/user_experience_sli/experience.rb

@@ -135,6 +135,28 @@ module Labkit
         self
       end
 
+      # Records a past User Experience by its duration.
+      #
+      # @param start_time [Time] The time when the experience started.
+      # @param error [Boolean] Whether the experience ended in an error.
+      # @param extra [Hash] Additional data to include in the log events.
+      # @return [self]
+      def observed(start_time:, error: false, **extra)
+        @start_time = start_time.utc
+        @end_time = Time.now.utc
+        error!("observed_error") if error
+
+        checkpoint_counter.increment(checkpoint: "start", **base_labels)
+        log_event("start", **extra)
+
+        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)
+
+        self
+      end
+
       # Marks the experience as failed with an error
       #
       # @param error [StandardError, String] The error that caused the experience to fail.

data/lib/labkit/user_experience_sli/null.rb

@@ -20,6 +20,7 @@ module Labkit
         self
       end
 
+      def observed(**_kwargs) = self
       def push_attributes!(*_args) = self
       def checkpoint(*_args) = self
       def complete(*_args) = self

data/lib/labkit/user_experience_sli.rb

@@ -77,7 +77,7 @@ module Labkit
         reset_configuration
       end
 
-      # Retrieves a covered experience using the experience_id.
+      # Retrieves a user 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.
@@ -88,7 +88,7 @@ module Labkit
         find_current(experience_id) || raise_or_null(experience_id)
       end
 
-      # Starts a covered experience using the experience_id.
+      # Starts a user 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.
@@ -97,7 +97,19 @@ module Labkit
         get(experience_id).start(**extra, &)
       end
 
-      # Resumes a covered experience using the experience_id.
+      # Records a past user experience by its duration atomically.
+      #
+      # @param experience_id [String, Symbol] The ID of the experience.
+      # @param start_time [Time] The time when the experience started.
+      # @param extra [Hash] Additional data to include in the log events.
+      # @return [Experience, Null] The observed experience or a Null object if not found (in production/staging).
+      def observed(experience_id, start_time:, **extra)
+        definition = registry[experience_id]
+        experience = definition ? Experience.new(definition) : raise_or_null(experience_id)
+        experience.observed(start_time: start_time, **extra)
+      end
+
+      # Resumes a user 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).

data/scripts/prepare-dev-env.sh

@@ -54,6 +54,7 @@ fi
 # install mise/asdf dependencies
 echo "installing required plugins with mise install.."
 mise plugins update -q
+mise trust
 mise install
 
 # set PROMPT_COMMAND to empty value for mise if unset

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gitlab-labkit
 version: !ruby/object:Gem::Version
-  version: 1.9.0
+  version: 1.10.0
 platform: ruby
 authors:
 - Andrew Newdigate