gitlab-labkit 1.9.1 → 1.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 71d570681f92f33c67e9d40571f88ad6118dfdbf3aed305be7b58a9099a9ad8d
-  data.tar.gz: e03f282e419b06a8a030eaf5b9215eb99ced4883064c66abbca3ca84f9d452bf
+  metadata.gz: d63e4f781c8e316f19c419a52485bd751cef83e713f7da971e3285709760a669
+  data.tar.gz: a13c2d6a3b9f217f0d65c5a755ff213db29b21dad1e20d2cc5ea17a5bea3dda5
 SHA512:
-  metadata.gz: be28ccf4c08aeff50ce11cbe5fbe552b5b26ef2967dcdcb46b9a7437783cd20535c2794e95be097d23d59126db6f0731f0cd13783ec314f72208c4789ab2c73c
-  data.tar.gz: 7d972eaf40419b5b4c33ae4c283a72d496cfc81be35386d16924fc133b9b94f028456bd9e0bfc7f076799239f938dee931b7a7a20c690cabcb4fcab571df8b8a
+  metadata.gz: 5e5983bc819202df660c1965efb7d26dd74f89c7479d01974a3d4f56e5a2c09a4d9fa01cac41719d80048d6737a676cc3fb3d9492cfb1619eb715932cf2ad6ff
+  data.tar.gz: 44d1210ee82ef16a99150316f73b76be43942fedaad296b78c925a3e270a8e6b39e4e3cbf43e63488048b11f7d69b40ad3dcfdcc514b8d6bbb4dfe805a28173a

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/fields.rb

@@ -80,6 +80,28 @@ module Labkit
     # request receipt to first response byte written.
     TTFB_S = "ttfb_s"
 
+    # GitLab project numeric ID.
+    GL_PROJECT_ID = "gl_project_id"
+
+    # GitLab pipeline numeric ID.
+    GL_PIPELINE_ID = "gl_pipeline_id"
+
+    # Log event timestamp in ISO 8601 format (e.g. "2026-04-02T12:00:00.000Z").
+    TIMESTAMP = "timestamp"
+
+    # Log severity level (e.g. "info", "warn", "error").
+    SEVERITY = "severity"
+
+    # Human-readable log message describing the event.
+    LOG_MESSAGE = "message"
+
+    # Class name associated with a log event (e.g. exception class or worker
+    # class).
+    CLASS_NAME = "class_name"
+
+    # Name of the service or component emitting the log event.
+    SERVICE_NAME = "service_name"
+
     # Get the constant name for a field value
     # @param field_value [String] The field value (e.g., "gl_user_id")
     # @return [String, nil] The constant name (e.g., "GL_USER_ID") or nil if not found
@@ -97,8 +119,22 @@ module Labkit
       # to identify and track usage of deprecated fields in the codebase.
 
       MAPPINGS = {
-        Fields::GL_USER_ID => %w[user_id userid],
-        Fields::HTTP_STATUS_CODE => %w[status_code extra.status status_text],
+        Fields::CORRELATION_ID => %w[tags.correlation_id],
+        Fields::GL_USER_ID => %w[user_id userid extra.user_id extra.current_user_id meta.user_id],
+        Fields::GL_USER_NAME => %w[username extra.user meta.user],
+        Fields::ERROR_MESSAGE => %w[error err error.message exception.message graphql_errors],
+        Fields::HTTP_STATUS_CODE => %w[status_code extra.status status_text http_status],
+        Fields::HTTP_URL => %w[req_url],
+        Fields::DURATION_S => %w[duration duration_ms elapsed_time actual_duration time_ms total_time gitaly.duration],
+        Fields::REMOTE_IP => %w[ip source_ip ip_address meta.remote_ip],
+        Fields::HTTP_HOST => %w[hostname request_host gitlab_host kubernetes.host],
+        Fields::GL_PROJECT_ID => %w[extra.project_id meta.project_id meta.search.project_id job_project_id target_project_id],
+        Fields::GL_PIPELINE_ID => %w[extra.pipeline_id meta.pipeline_id root_pipeline_id],
+        Fields::TIMESTAMP => %w[start_time],
+        Fields::SEVERITY => %w[level],
+        Fields::LOG_MESSAGE => %w[msg custom_message extra.message fields.message graphql.message reason color_message exception.gitaly],
+        Fields::CLASS_NAME => %w[class author_class exception.class extra.class extra.class_name],
+        Fields::SERVICE_NAME => %w[service grpc.service_name auth_service type component subcomponent],
       }.freeze
 
       class << self

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.1
+  version: 1.11.0
 platform: ruby
 authors:
 - Andrew Newdigate