gitlab-labkit 1.3.4 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a29bc2351fbe292697c582547316e370a7320826be10ecb9ef26580b1d5d3dce
-  data.tar.gz: f489a1fdd02e6a8ba3750c93bcab4baaa4907983abcaf81544e3ec300234a88e
+  metadata.gz: fef9aed12ba67f4628dcddf7273d14a420325935afe77dfad8950a57b2a28bf8
+  data.tar.gz: 4cd67209a2a395f1e0b2e0b866a3df8d266a4bb3390f14de24336265e78d88bd
 SHA512:
-  metadata.gz: f5b4397587a97aa9aadb2b8b4606c675337110ab65d410f211d0c33a0e89fc6b4c2b68f8d07d78906ccd680e31612439d4b316ba955b770a7074582d6b7f80e4
-  data.tar.gz: 521c43e11ede3e207218574c00b5644f2907deb19d876213c862818c0e3c12ff65f1eaeaa4c6b9b1afeb0a59f9d20a67552c7a8a7d8dbb48997d9cc7d55d30ac
+  metadata.gz: d672a393f0491b986882ecedc0d80ebff33bc266a2eb34f407cc1158b1ba3c19e419fcac64ce0b86d59eb039da16cc57fd937f69eb88529deb014dfc4c587566
+  data.tar.gz: bac5642a671b7a86ed7b375273fe9fa3aa76335ac1718ece9104017104e639ad86e16d3361d8721ddb39ddea94628a8d7a990a63adc17ca63263083397c0f815

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gitlab-labkit
 version: !ruby/object:Gem::Version
-  version: 1.3.4
+  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