gitlab-labkit 0.37.0 → 0.40.0

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'

data/renovate.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "extends": [
+    "gitlab>gitlab-com/gl-infra/common-ci-tasks:renovate-common",
+    "gitlab>gitlab-com/gl-infra/common-ci-tasks:renovate-truncated-versions"
+  ]
+}

data/scripts/install-asdf-plugins.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# Vendored from https://gitlab.com/gitlab-com/gl-infra/common-template-copier
+# Consider contributing upstream when updating this file
+
+# This file is deprecated: going forward running `mise install` should be sufficient.
+
+set -euo pipefail
+IFS=$'\n\t'
+
+echo >&2 -e "2024-08-07: this file is deprecated: going forward, simply run 'mise install' to install plugins."
+echo >&2 -e "Recommended reading: https://gitlab.com/gitlab-com/gl-infra/common-ci-tasks/-/blob/main/docs/developer-setup.md"
+
+mise install

data/scripts/prepare-dev-env.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# Vendored from https://gitlab.com/gitlab-com/gl-infra/common-template-copier
+# Consider contributing upstream when updating this file
+
+set -euo pipefail
+
+# ---------------------------------------------------------
+# This script will prepare your development environment
+# while working on this project. Run it after cloning this
+# project.
+#
+# It's recommended that you review
+# https://gitlab.com/gitlab-com/gl-infra/common-ci-tasks/-/blob/main/docs/developer-setup.md
+# first.
+# ---------------------------------------------------------
+
+cd "$(dirname "${BASH_SOURCE[0]}")/.."
+
+warn() {
+  echo >&2 -e "${1-}"
+  echo >&2 -e "Recommended reading: https://gitlab.com/gitlab-com/gl-infra/common-ci-tasks/-/blob/main/docs/developer-setup.md"
+}
+
+if command -v mise >/dev/null; then
+  echo >&2 -e "mise installed..."
+elif command -v rtx >/dev/null; then
+  warn "⚠️ 2024-01-02: 'rtx' has changed to 'mise'; please replace 'rtx' with 'mise'"
+  exit 1
+elif [[ -n ${ASDF_DIR-} ]]; then
+  warn "⚠️ 2024-08-07: 'asdf' is no longer supported; please uninstall and replace with 'mise'"
+  exit 1
+else
+  warn "mise is not installed."
+  exit 1
+fi
+
+# Do some validation to ensure that the environment is not misconfigured, as this may
+# save a bunch of debugging effort down the line.
+
+# Detect Rosetta 2
+if [[ $(uname -m) == "arm64" ]] && [[ $(uname -p) == "x86_64" ]]; then
+  echo "This shell is running in Rosetta emulating x86_64. Please use native mode Apple Silicon." >&2
+  echo "For help visit https://gitlab.com/gitlab-com/gl-infra/common-ci-tasks/-/blob/main/docs/developer-setup.md" >&2
+  exit 1
+fi
+
+# Detect ancient versions of bash
+if ((BASH_VERSINFO[0] < 4)); then
+  echo "You're running bash < v4.0.0. Please upgrade to a newer version." >&2
+  echo "For help visit https://gitlab.com/gitlab-com/gl-infra/common-ci-tasks/-/blob/main/docs/developer-setup.md" >&2
+  exit 1
+fi
+
+# install mise/asdf dependencies
+echo "installing required plugins with mise install.."
+mise plugins update
+mise install
+eval "$(mise activate bash)"
+
+# pre-commit is optional
+if command -v pre-commit &>/dev/null; then
+  echo "running pre-commit install..."
+  pre-commit install
+  pre-commit install-hooks
+  pre-commit install --hook-type commit-msg
+else
+  warn "pre-commit is not installed. Skipping."
+fi

data/scripts/update-asdf-version-variables.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+# Vendored from https://gitlab.com/gitlab-com/gl-infra/common-template-copier
+# Consider contributing upstream when updating this file
+
+# See the README.md for details of how this script works
+
+set -euo pipefail
+IFS=$'\n\t'
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+export LANG=C LC_ALL=C
+
+generate() {
+  sort "${ROOT_DIR}/.tool-versions" |
+    awk '
+    BEGIN {
+      print "# DO NOT MANUALLY EDIT; Run ./scripts/update-asdf-version-variables.sh to update this";
+      print "variables:"
+    }
+    {
+      if (!/^#/ && $1 != "" && $2 != "system") {
+        gsub("-", "_", $1);
+        print "    GL_ASDF_" toupper($1) "_VERSION: \"" $2 "\""
+      }
+    }
+    '
+}
+
+generate >"${ROOT_DIR}/.gitlab-ci-asdf-versions.yml"

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: gitlab-labkit
 version: !ruby/object:Gem::Version
-  version: 0.37.0
+  version: 0.40.0
 platform: ruby
 authors:
 - Andrew Newdigate
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-12-05 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
@@ -64,6 +63,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '1.62'
+- !ruby/object:Gem::Dependency
+  name: google-protobuf
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3'
 - !ruby/object:Gem::Dependency
   name: jaeger-client
   requirement: !ruby/object:Gem::Requirement
@@ -78,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
@@ -98,7 +125,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 5.1.0
+        version: 6.1.0
     - - "<"
       - !ruby/object:Gem::Version
         version: '7.0'
@@ -108,10 +135,24 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 5.1.0
+        version: 6.1.0
     - - "<"
       - !ruby/object:Gem::Version
         version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: prometheus-client-mmap
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.2.9
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.2.9
 - !ruby/object:Gem::Dependency
   name: redis
   requirement: !ruby/object:Gem::Requirement
@@ -180,14 +221,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 6.2.0
+        version: 13.0.2
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 6.2.0
+        version: 13.0.2
 - !ruby/object:Gem::Dependency
   name: grpc-tools
   requirement: !ruby/object:Gem::Requirement
@@ -208,28 +249,42 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.17.3
+        version: 0.22.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.17.3
+        version: 0.22.0
 - !ruby/object:Gem::Dependency
   name: httpclient
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.8.3
+        version: 2.9.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.8.3
+        version: 2.9.0
+- !ruby/object:Gem::Dependency
+  name: irb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.15.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.15.2
 - !ruby/object:Gem::Dependency
   name: pry
   requirement: !ruby/object:Gem::Requirement
@@ -244,6 +299,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.12'
+- !ruby/object:Gem::Dependency
+  name: pry-byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.11'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.11'
 - !ruby/object:Gem::Dependency
   name: rack
   requirement: !ruby/object:Gem::Requirement
@@ -264,14 +333,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '12.3'
+        version: '13.2'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '12.3'
+        version: '13.2'
 - !ruby/object:Gem::Dependency
   name: rest-client
   requirement: !ruby/object:Gem::Requirement
@@ -314,20 +383,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
-- !ruby/object:Gem::Dependency
-  name: rufo
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - '='
-      - !ruby/object:Gem::Version
-        version: 0.9.0
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - '='
-      - !ruby/object:Gem::Version
-        version: 0.9.0
 - !ruby/object:Gem::Dependency
   name: sidekiq
   requirement: !ruby/object:Gem::Requirement
@@ -362,29 +417,38 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 1.7.0
-description:
 email:
 - andrew@gitlab.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".copier-answers.yml"
+- ".editorconfig"
 - ".env.example.sh"
 - ".gitignore"
+- ".gitlab-ci-asdf-versions.yml"
 - ".gitlab-ci.yml"
 - ".gitlab/CODEOWNERS"
+- ".gitleaks.toml"
+- ".mise.toml"
+- ".pre-commit-config.yaml"
+- ".releaserc.json"
 - ".rspec"
 - ".rubocop.yml"
 - ".rubocop_todo.yml"
-- ".ruby-version"
 - ".rufo"
 - ".tool-versions"
+- ".yamllint.yaml"
+- CODEOWNERS
 - CONTRIBUTING.md
 - Dangerfile
 - Gemfile
 - 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
@@ -394,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
@@ -402,6 +472,12 @@ files:
 - lib/labkit/logging/grpc/server_interceptor.rb
 - lib/labkit/logging/json_logger.rb
 - lib/labkit/logging/sanitizer.rb
+- lib/labkit/metrics.rb
+- lib/labkit/metrics/README.md
+- lib/labkit/metrics/client.rb
+- lib/labkit/metrics/null.rb
+- lib/labkit/metrics/rack_exporter.rb
+- lib/labkit/metrics/registry.rb
 - lib/labkit/middleware.rb
 - lib/labkit/middleware/rack.rb
 - lib/labkit/middleware/sidekiq.rb
@@ -415,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
@@ -448,28 +527,30 @@ files:
 - lib/labkit/tracing/redis/redis_interceptor_helper.rb
 - lib/labkit/tracing/tracing_common.rb
 - lib/labkit/tracing/tracing_utils.rb
+- renovate.json
+- scripts/install-asdf-plugins.sh
+- scripts/prepare-dev-env.sh
+- scripts/update-asdf-version-variables.sh
 homepage: https://gitlab.com/gitlab-org/labkit-ruby
 licenses:
 - MIT
 metadata:
   source_code_uri: https://gitlab.com/gitlab-org/ruby/gems/labkit-ruby
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - "~>"
     - !ruby/object:Gem::Version
-      version: 2.6.0
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.27
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Instrumentation for GitLab
 test_files: []

data/.ruby-version

@@ -1 +0,0 @@
-3.1.4