gitlab-labkit 1.3.3 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fd5d320e1c751f2fea87cb55e57c3353b1255c62a126e97eba24a60642c9e0e0
-  data.tar.gz: 543e2fcd663bf562cb23426f0903acbafcf7f2edb6738e12dcc420fdfd8e26aa
+  metadata.gz: fef9aed12ba67f4628dcddf7273d14a420325935afe77dfad8950a57b2a28bf8
+  data.tar.gz: 4cd67209a2a395f1e0b2e0b866a3df8d266a4bb3390f14de24336265e78d88bd
 SHA512:
-  metadata.gz: af194fc50ac69e6136c8e849b3445ed8f99c53eb555745ef5c03cbc5f42fde12b0a8fa33bb402c1fc80895feb4e9fba4a5c49cf345c77be10cc977f92cb105c4
-  data.tar.gz: e0b1dd39d3002edd45eb722d0aebe86e800688d878ab5e3beb79d060f65d7a3637ef3d5fb6351b9d80d81156542dd25dc0e3c291c4b7ce0485a4114752e69644
+  metadata.gz: d672a393f0491b986882ecedc0d80ebff33bc266a2eb34f407cc1158b1ba3c19e419fcac64ce0b86d59eb039da16cc57fd937f69eb88529deb014dfc4c587566
+  data.tar.gz: bac5642a671b7a86ed7b375273fe9fa3aa76335ac1718ece9104017104e639ad86e16d3361d8721ddb39ddea94628a8d7a990a63adc17ca63263083397c0f815

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.38.0
+_commit: v1.39.0
 _src_path: https://gitlab.com/gitlab-com/gl-infra/common-template-copier.git
 ee_licensed: false
 golang: false

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"

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

@@ -18,6 +18,7 @@ module Labkit
         class << self
           def register_wrapper_pattern(pattern)
             wrapper_patterns << pattern
+            @combined_ignore_pattern = nil
           end
 
           def wrapper_patterns
@@ -26,6 +27,11 @@ module Labkit
 
           def reset_wrapper_patterns!
             @wrapper_patterns = nil
+            @combined_ignore_pattern = nil
+          end
+
+          def combined_ignore_pattern
+            @combined_ignore_pattern ||= Regexp.union(IGNORE_PATHS + wrapper_patterns)
           end
         end
 
@@ -66,13 +72,13 @@ module Labkit
         def determine_callsite
           locations = caller_locations(INTERNAL_FRAMES_TO_SKIP, MAX_FRAMES_TO_INSPECT) || []
           locations = caller_locations(1, MAX_FRAMES_TO_INSPECT) || [] if locations.empty?
+          ignore_pattern = LogInterceptor.combined_ignore_pattern
 
           locations.find do |loc|
             path = loc.path
 
             next if path == __FILE__
-            next if IGNORE_PATHS.any? { |pattern| pattern.match?(path) }
-            next if LogInterceptor.wrapper_patterns.any? { |pattern| pattern.match?(path) }
+            next if ignore_pattern.match?(path)
 
             true
           end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gitlab-labkit
 version: !ruby/object:Gem::Version
-  version: 1.3.3
+  version: 1.4.0
 platform: ruby
 authors:
 - Andrew Newdigate
@@ -487,6 +487,10 @@ files:
 - exe/labkit-logging
 - gitlab-labkit.gemspec
 - lib/gitlab-labkit.rb
+- lib/labkit/application_sli.rb
+- lib/labkit/application_sli/README.md
+- lib/labkit/application_sli/apdex.rb
+- lib/labkit/application_sli/error_rate.rb
 - lib/labkit/context.rb
 - lib/labkit/correlation.rb
 - lib/labkit/correlation/correlation_id.rb