gitlab-labkit 1.3.4 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a29bc2351fbe292697c582547316e370a7320826be10ecb9ef26580b1d5d3dce
-  data.tar.gz: f489a1fdd02e6a8ba3750c93bcab4baaa4907983abcaf81544e3ec300234a88e
+  metadata.gz: bf6262472d851bcdfeb96b0ed3b7acf25f462b0b968d2ac2f431ea946b68b33a
+  data.tar.gz: b04bfc82c7ea63848849af40c7940788796b486a16c41416de824b7440f01992
 SHA512:
-  metadata.gz: f5b4397587a97aa9aadb2b8b4606c675337110ab65d410f211d0c33a0e89fc6b4c2b68f8d07d78906ccd680e31612439d4b316ba955b770a7074582d6b7f80e4
-  data.tar.gz: 521c43e11ede3e207218574c00b5644f2907deb19d876213c862818c0e3c12ff65f1eaeaa4c6b9b1afeb0a59f9d20a67552c7a8a7d8dbb48997d9cc7d55d30ac
+  metadata.gz: 7c5a7b9002239cf23e7609fd8c07174bf588c0f2f1f2177616d6f98f4490c8e32f74cb7c8e62c1bf8ae839da24e30023e9bd733f1a6e40bbf75484d614a3d9ad
+  data.tar.gz: e699b4a653c268c7333bdad41006a5c52d0fbdaf0aa4c21ca90bbb396695d6519695243e0548e0f5439f9bd11366c6a3359c013766deadaa6996e31bbbfb7c7a

data/gitlab-labkit.gemspec

@@ -27,8 +27,11 @@ Gem::Specification.new do |spec|
   spec.add_runtime_dependency "grpc", ">= 1.75" # Be sure to update the "grpc-tools" dev_dependency too
   spec.add_runtime_dependency "google-protobuf", ">= 3.25", "< 5.0"
   spec.add_runtime_dependency "jaeger-client", "~> 1.1.0"
-  spec.add_runtime_dependency 'json_schemer', '>= 2.3.0', '< 3.0'
+  spec.add_runtime_dependency "json_schemer", ">= 2.3.0", "< 3.0"
   spec.add_runtime_dependency "openssl", "~> 3.3.2"
+  spec.add_runtime_dependency "opentelemetry-sdk", "~> 1.10"
+  spec.add_runtime_dependency "opentelemetry-instrumentation-all", "~> 0.89.1"
+  spec.add_runtime_dependency "opentelemetry-exporter-otlp", "~> 0.31.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", "< 2.0"
@@ -46,6 +49,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "pry", "~> 0.12"
   spec.add_development_dependency "pry-byebug", "~> 3.11"
   spec.add_development_dependency "rack", "~> 2.0"
+  spec.add_development_dependency "railties", ">= 5.0.0", "< 8.1.0"
   spec.add_development_dependency "rake", "~> 13.2"
   spec.add_development_dependency "rest-client", "~> 2.1.0"
   spec.add_development_dependency "rspec", "~> 3.12.0"

data/lib/gitlab-labkit.rb

@@ -10,6 +10,7 @@ module Labkit
   autoload :Context, "labkit/context"
   autoload :Correlation, "labkit/correlation"
   autoload :CoveredExperience, "labkit/user_experience_sli" # Backward compatibility alias
+  autoload :ApplicationSli, "labkit/application_sli"
   autoload :UserExperienceSli, "labkit/user_experience_sli"
   autoload :FIPS, "labkit/fips"
   autoload :Tracing, "labkit/tracing"
@@ -46,4 +47,6 @@ module Labkit
   autoload :HTTPClientPublisher, "labkit/httpclient_publisher"
 end
 
+Labkit::Tracing::AutoInitialize.initialize! if defined?(Labkit::Tracing)
+
 # rubocop:enable Naming/FileName

data/lib/labkit/application_sli/README.md

@@ -0,0 +1,69 @@
+# Application SLIs
+
+This module provides [Application Service Level Indicators(SLIs)](https://docs.gitlab.com/development/application_slis/)
+for monitoring and observability. It allows defining SLIs directly in Ruby code, keeping the definition of operations and their success close to the implementation.
+
+Two SLI types are available:
+
+- **`Labkit::ApplicationSli::Apdex`** - Measures the performance of successful operations using a success rate.
+- **`Labkit::ApplicationSli::ErrorRate`** - Measures the rate of unsuccessful operations using an error rate.
+
+## Defining a new SLI
+
+When you define an SLI, two [Prometheus counters](https://prometheus.io/docs/concepts/metric_types/#counter) are emitted. Both contain a total operation count, and a numerator counter for the success or error rate.
+
+`Labkit::ApplicationSli::Apdex` defines:
+
+- `gitlab_sli_<name>_apdex_total` - total number of measurements
+- `gitlab_sli_<name>_apdex_success_total` - number of successful measurements
+
+`Labkit::ApplicationSli::ErrorRate` defines:
+
+- `gitlab_sli_<name>_total` - total number of measurements
+- `gitlab_sli_<name>_error_total` - number of error measurements
+
+## Initializing an SLI
+
+Before the first Prometheus scrape, initialize the SLI with all possible label combinations to [avoid missing metrics](https://prometheus.io/docs/practices/instrumentation/#avoid-missing-metrics):
+
+```ruby
+Labkit::ApplicationSli::Apdex.initialize_sli(:received_email, [
+  {
+    feature_category: :team_planning,
+    email_type: :create_issue
+  },
+  {
+    feature_category: :service_desk,
+    email_type: :service_desk
+  }
+])
+```
+
+## Tracking operations
+
+Increment the SLI counters using the `#increment` method with the appropriate labels.
+
+For `Apdex`, pass `success:` to indicate whether the operation met the performance target:
+
+```ruby
+Labkit::ApplicationSli::Apdex[:received_email].increment(
+  labels: {
+    feature_category: :service_desk,
+    email_type: :service_desk
+  },
+  success: issue_created?
+)
+```
+
+For `ErrorRate`, pass `error:` to indicate whether the operation failed:
+
+```ruby
+Labkit::ApplicationSli::ErrorRate[:merge].increment(
+  labels: {
+    merge_type: :fast_forward
+  },
+  error: !merge_success?
+)
+```
+
+When `success:` (or `error:`) is truthy, both the total and numerator counters are incremented. When falsy, only the total counter is incremented.

data/lib/labkit/application_sli/apdex.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Labkit
+  module ApplicationSli
+    class Apdex
+      include Labkit::ApplicationSli
+
+      def increment(labels:, success:)
+        super(labels: labels, increment_numerator: success)
+      end
+
+      private
+
+      def counter_name(suffix)
+        :"#{COUNTER_PREFIX}_#{name}_apdex_#{suffix}"
+      end
+
+      def numerator_counter
+        prometheus.counter(counter_name('success_total'), "Number of successful measurements for #{name}")
+      end
+    end
+  end
+end

data/lib/labkit/application_sli/error_rate.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Labkit
+  module ApplicationSli
+    class ErrorRate
+      include Labkit::ApplicationSli
+
+      def increment(labels:, error:)
+        super(labels: labels, increment_numerator: error)
+      end
+
+      private
+
+      def counter_name(suffix)
+        :"#{COUNTER_PREFIX}_#{name}_#{suffix}"
+      end
+
+      def numerator_counter
+        prometheus.counter(counter_name('error_total'), "Number of error measurements for #{name}")
+      end
+    end
+  end
+end

data/lib/labkit/application_sli.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Labkit
+  module ApplicationSli
+    COUNTER_PREFIX = 'gitlab_sli'
+
+    module ClassMethods
+      INITIALIZATION_MUTEX = Mutex.new
+
+      def [](name)
+        known_slis[name] || initialize_sli(name, [])
+      end
+
+      def initialize_sli(name, possible_label_combinations)
+        INITIALIZATION_MUTEX.synchronize do
+          next known_slis[name] if initialized?(name)
+
+          sli = new(name)
+          sli.initialize_counters(possible_label_combinations)
+          known_slis[name] = sli
+        end
+      end
+
+      def initialized?(name)
+        known_slis.key?(name) && known_slis[name].initialized?
+      end
+
+      private
+
+      def known_slis
+        @known_slis ||= {}
+      end
+    end
+
+    def self.included(mod)
+      mod.extend(ClassMethods)
+    end
+
+    attr_reader :name
+
+    def initialize(name)
+      @name = name
+      @initialized_with_combinations = false
+    end
+
+    def initialize_counters(possible_label_combinations)
+      @initialized_with_combinations = possible_label_combinations.any?
+      possible_label_combinations.each do |label_combination|
+        total_counter.get(label_combination)
+        numerator_counter.get(label_combination)
+      end
+    end
+
+    def increment(labels:, increment_numerator:)
+      total_counter.increment(labels)
+      numerator_counter.increment(labels) if increment_numerator
+    end
+
+    def initialized?
+      @initialized_with_combinations
+    end
+
+    private
+
+    def total_counter
+      prometheus.counter(counter_name('total'), "Total number of measurements for #{name}")
+    end
+
+    def prometheus
+      Labkit::Metrics::Client
+    end
+
+    autoload :Apdex, "labkit/application_sli/apdex"
+    autoload :ErrorRate, "labkit/application_sli/error_rate"
+  end
+end

data/lib/labkit/logging/field_validator.rb

@@ -1,12 +1,11 @@
 # frozen_string_literal: true
 
-require 'set'
-require 'json'
-require 'yaml'
+require "json"
+require "yaml"
 
-require_relative 'field_validator/config'
-require_relative 'field_validator/log_interceptor'
-require_relative 'field_validator/registry'
+require_relative "field_validator/config"
+require_relative "field_validator/log_interceptor"
+require_relative "field_validator/registry"
 
 module Labkit
   module Logging
@@ -46,14 +45,14 @@ module Labkit
 
           return if detected_offenses.empty? && new_offenses.empty? && removed_offenses.empty?
 
-          in_ci = ENV['CI'] == 'true'
+          in_ci = ENV["CI"] == "true"
 
           output_ndjson(detected_offenses) if in_ci
 
           # Auto-remove fixed offenses (not in CI to avoid race conditions)
           handle_removed_offenses(removed_offenses) if removed_offenses.any? && !in_ci
 
-          if ENV['LABKIT_LOGGING_TODO_UPDATE'] == 'true'
+          if ENV["LABKIT_LOGGING_TODO_UPDATE"] == "true"
             handle_update(new_offenses)
           elsif new_offenses.any?
             handle_new_offenses(new_offenses)
@@ -98,7 +97,7 @@ module Labkit
         end
 
         def handle_new_offenses(new_offenses)
-          if ENV['CI'] == 'true' && Config.skip_ci_failure?
+          if ENV["CI"] == "true" && Config.skip_ci_failure?
             warn baseline_generation_message(new_offenses)
           else
             warn report_new_offenses(new_offenses)
@@ -120,7 +119,7 @@ module Labkit
             "Documentation: https://gitlab.com/gitlab-org/ruby/gems/labkit-ruby/-/blob/master/doc/FIELD_STANDARDIZATION.md",
             "",
             "--- Offenses Summary ---",
-            "Total offenses: #{offenses.size} across #{offenses.map { |o| o['callsite'] }.uniq.size} file(s)",
+            "Total offenses: #{offenses.size} across #{offenses.map { |o| o['callsite'] }.uniq.size} file(s)", # rubocop:disable Rails/Pluck
             ""
           ]
           lines.join("\n")
@@ -157,7 +156,7 @@ module Labkit
 
           lines << ""
           lines << ("=" * 80)
-          lines << "Total: #{new_offenses.size} new offense(s) in #{new_offenses.map { |o| o['callsite'] }.uniq.size} file(s)"
+          lines << "Total: #{new_offenses.size} new offense(s) in #{new_offenses.map { |o| o['callsite'] }.uniq.size} file(s)" # rubocop:disable Rails/Pluck
           lines << ""
           lines << "See https://gitlab.com/gitlab-org/ruby/gems/labkit-ruby/-/blob/master/doc/FIELD_STANDARDIZATION.md"
           lines << ("=" * 80)

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

@@ -17,7 +17,7 @@ module Labkit
           def call(_worker_class, job, _queue, _redis_pool)
             Labkit::Tracing::TracingUtils.with_tracing(operation_name: "sidekiq:#{job_class(job)}", tags: tags_from_job(job, SPAN_KIND)) do |span|
               # Inject the details directly into the job
-              Labkit::Tracing::TracingUtils.tracer.inject(span.context, OpenTracing::FORMAT_TEXT_MAP, job)
+              Labkit::Tracing::TracingUtils.tracer.inject_context(span, job)
 
               yield
             end

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

@@ -15,7 +15,7 @@ module Labkit
           SPAN_KIND = "server"
 
           def call(_worker, job, _queue)
-            context = Labkit::Tracing::TracingUtils.tracer.extract(OpenTracing::FORMAT_TEXT_MAP, job)
+            context = Labkit::Tracing::TracingUtils.tracer.extract_context(job)
 
             Labkit::Tracing::TracingUtils.with_tracing(operation_name: "sidekiq:#{job_class(job)}", child_of: context, tags: tags_from_job(job, SPAN_KIND)) { |_span| yield }
           end