gitlab-labkit 4.6.0 → 5.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 22a38c0fe1a2f28aa538b80348911947c6de64c16d7d870d24835332796faa99
-  data.tar.gz: 6259d696d178f3008aefdf91de71731c81d460cef08259555829f15d8abd462c
+  metadata.gz: 6d2bc5199fdb961286c36547f3c359b9de03bb8dc8c6c260c2074c177d24fc79
+  data.tar.gz: '09d7ddd1b8e64f242ca95c63fce1e7d1a29a8d4d44a3908be2aad99e8df57207'
 SHA512:
-  metadata.gz: dd404f717fe9cee20cb544ad23cd5aa3195683ac0efe8bf8363988fdb8dcacc4fcaa817ac6f4cb3fcdb4f2e3d193c6d93cc13deea0344067e44fac7f3c593fb3
-  data.tar.gz: cc8d6bb5fe6fde8c17f969d4a708bd41901de5f9383f4821e3acf13a2eb35c240a80d18d3853ac5f29b689d7841df254f540233174646204358e698b9e0f643e
+  metadata.gz: 366832f3f6b6a1f76f2c4638c4303c3ad4c1c9065a876c9bb32a049fb3c94f214804f43ded0f5a30a65b87f3a1c9595e1cf05c85152a1eb9c6d8eed7228a1ddc
+  data.tar.gz: 45f429a193fa57913cc61b5fda09356abb2135eb1f596c8d6eb4c0982fe2d4a4012551a5dedd2e2576b27da6017a7632f00cd24991352c15be7716a72abd4957

data/.gitlab/CODEOWNERS

@@ -1 +1 @@
-* @reprazent @andrewn @mkaeppler @ayufan @hmerscher @d.barrett @splattael @sankalp_gl @hardikgala @nindurkar @ashs2
+* @reprazent @andrewn @mkaeppler @ayufan @hmerscher @sankalp_gl @hardikgala @nindurkar @ashs2

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 @e_forbes @M_Alvarez @mwoolf @sankalp_gl @hardikgala @nindurkar @ashs2
+* @reprazent @andrewn @mkaeppler @ayufan @hmerscher @e_forbes @M_Alvarez @mwoolf @sankalp_gl @hardikgala @nindurkar @ashs2

data/lib/labkit/rate_limit/README.md

@@ -121,6 +121,8 @@ different question than `check`. A matched `:skip` rule terminates `peek`
 the same way it terminates `check`: matched, `:allow`, no Redis read, no
 `info`.
 
+A peek is counted by its own `peeks_total` counter. See [Metrics](#metrics).
+
 ### Clearing state
 
 `Limiter#clear(identifier)` deletes this limiter's counters for one
@@ -267,7 +269,7 @@ flowchart TD
     Return --> Check[Emit checks_total<br/>action, matched, error]
     SkipReturn --> Check
     Return2 --> Check
-    Eval -. StandardError .-> Error[Emit errors_total +<br/>checks_total error=true<br/>log warn]
+    Eval -. StandardError .-> Error[Emit checks_total error=true<br/>log warn]
     Error --> ReturnErr([Return error=true<br/>action=:allow])
 ```
 
@@ -290,12 +292,6 @@ fail-open also emits nothing here — it was never evaluated; that check is
 visible via `checks_total{error="true"}` and the
 `rate_limit_missing_count_distinct` log, which carries the rule name.
 
-During the transition the deprecated `calls_total` counter is additionally
-emitted at every point the diagram emits `rule_evaluations_total` (with its
-historical per-rule semantics, including the `rule="unmatched"` placeholder
-after the loop). It is not shown above to keep the diagram legible; see the
-Metrics table below.
-
 ### Actions
 
 The rule's `action` describes what the rule does; the result's `action`
@@ -361,7 +357,7 @@ window, and it stops counting while that ban holds:
   written with `SET EX`. A callable is checked again each time it resolves, and
   a value under a second raises rather than reaching Redis. Being an error, it
   fails open like any other, so a rule whose `ban_for` cannot resolve stops
-  blocking entirely: watch `errors_total` after changing one.
+  blocking entirely: watch `checks_total{error="true"}` after changing one.
 
   Take care combining `ban_for` with `cost:`. One expensive call can cross the
   limit on its own, and with a ban attached that costs the caller the whole ban
@@ -453,11 +449,13 @@ the most constraining one (see [Evaluation flow](#evaluation-flow)):
 
 ```ruby
 result.matched?           # => true if some rule matched
+result.skipped?           # => true if a matched :skip rule bypassed the check
 result.exceeded?          # => true if the reported rule's counter > limit
 result.action             # => :block | :allow — what the caller should do
 result.block?             # => result.action == :block
 result.rule               # => the reported Rule, or nil
 result.error?             # => true if Redis failed (see Fail-open)
+result.degraded?          # => true if a matched count_distinct rule was skipped
 result.info               # => Result::Info or nil
 result.evaluations        # => every counted Result::Evaluation, in rule order
 result.to_response_headers
@@ -493,12 +491,13 @@ of checks that encountered an error is `checks_total{error="true"}` over
 `count_distinct` key — that check completes (`action` and `matched` describe
 its outcome as usual), so `error="true"` is not exclusively fail-open traffic.
 
-The deprecated `gitlab_labkit_rate_limiter_errors_total` counter is still
-incremented on every fail-open (whole-check and per-rule `count_distinct`),
-and remains the only error metric for `peek`, which emits no `checks_total`
-(peek must not inflate the per-check counter). The follow-up MR that removes
-`errors_total` must first decide where `peek` errors go — a dedicated peek
-metric, or logs only.
+A failed-open `peek` emits `peeks_total{error="true"}`, so the fraction of
+peeks that encountered an error is `peeks_total{error="true"}` over
+`peeks_total`. A `peek` emits no `checks_total`.
+
+`clear` emits no counter at all. A failure there is benign — the counters it
+could not delete expire on their own — so it is only logged, with the limiter
+name in the `name` field.
 
 Metric emission itself is best-effort: a failure in the metrics stack never
 alters the verdict or breaks fail-open, and is logged at WARN with
@@ -514,8 +513,7 @@ flooding).
 |-----------------------------------------------------|---------|----------------------------------------------|----------------------------------------------------------------------|
 | `gitlab_labkit_rate_limiter_checks_total`           | counter | `rate_limiter`, `action`, `matched`, `error` | Exactly one increment per `check` call, including fail-open. `action` is what the caller should do (`"allow"` or `"block"`); `matched` and `error` are `"true"`/`"false"`. |
 | `gitlab_labkit_rate_limiter_rule_evaluations_total` | counter | `rate_limiter`, `rule`, `action`, `result`   | One increment per evaluated rule (plus one per matched `:skip` rule). `action` is the configured rule action (`"limit"`, `"log"`, `"skip"`); `result` is what the evaluation decided (`"allow"`, `"block"`, `"log"`, `"skip"`, `"banned"` — see the Actions table). |
-| `gitlab_labkit_rate_limiter_calls_total`            | counter | `rate_limiter`, `rule`, `action`             | **Deprecated** — superseded by `checks_total` + `rule_evaluations_total`. Historical per-rule counter: one increment per counted rule (plus one per matched `:skip` rule), `rule="unmatched", action="allow"` when no rule matched. Emitted unchanged during the transition. |
-| `gitlab_labkit_rate_limiter_errors_total`           | counter | `rate_limiter`                               | **Deprecated** — use `checks_total{error="true"}`. Fail-open events (any `StandardError` in the labkit path); still the only error metric for `peek`. |
+| `gitlab_labkit_rate_limiter_peeks_total`            | counter | `rate_limiter`, `error`                      | Exactly one increment per `peek` call, including fail-open. `error` is `"true"`/`"false"`. |
 | `gitlab_labkit_rate_limiter_limit`                  | gauge   | `rate_limiter`, `rule`                       | Resolved limit at the last check (useful when `limit:` is callable). |
 | `gitlab_labkit_rate_limiter_period_seconds`         | gauge   | `rate_limiter`, `rule`                       | Resolved period at the last check.                                   |
 
@@ -524,11 +522,6 @@ the request rate through a limiter — no exclusions or dedup needed. A single
 `check` call emits **one** `checks_total` increment and as many
 `rule_evaluations_total` increments as rules it evaluated (possibly zero).
 
-**Transition:** the deprecated `calls_total` and `errors_total` counters keep
-emitting exactly as before this split, so existing dashboards and alerts stay
-correct while consumers migrate to the new counters. Both are removed in a
-follow-up major release once nothing consumes them.
-
 ## Dev/test vs production guards
 
 `Limiter.new` and `Rule.new` validate names and configuration. In

data/lib/labkit/rate_limit/evaluator.rb

@@ -124,7 +124,6 @@ module Labkit
       rescue StandardError => e
         # Intentionally broad: fail-open applies to any unexpected error (network,
         # timeout, OOM) not only Redis protocol errors.
-        report_error_metrics
         log_error(e, identifier, cursor.rule)
         result = Result.error
       ensure
@@ -138,11 +137,12 @@ module Labkit
       # extended. A missing Redis key is treated as count=0 (matched, not exceeded).
       def peek(identifier, rule_context: nil)
         cursor = RuleCursor.new
-        peek_rules(identifier, rule_context, cursor)
+        result = peek_rules(identifier, rule_context, cursor)
       rescue StandardError => e
-        report_error_metrics
         log_error(e, identifier, cursor.rule)
-        Result.error
+        result = Result.error
+      ensure
+        report_peek_metrics(result) if result
       end
 
       # Deletes this limiter's counters, and any bans, for one identifier.
@@ -175,7 +175,6 @@ module Labkit
 
         removed
       rescue StandardError => e
-        report_error_metrics
         log_error(e, identifier, nil)
         removed
       end
@@ -203,14 +202,14 @@ module Labkit
       # most-constraining evaluation (ranking lives in Result::Evaluation#<=>).
       # cost is therefore debited from every matching rule, not just the first.
       #
-      # Metrics: each evaluated rule emits rule_evaluations_total (plus the
-      # deprecated per-rule calls_total); the per-check checks_total is
-      # emitted once in #check. Full contract in the README's Metrics section.
+      # Metrics: each evaluated rule emits rule_evaluations_total; the per-check
+      # checks_total is emitted once in #check. Full contract in the README's
+      # Metrics section.
       #
       # SET-mode rules (rule.count_distinct set) that match but whose identifier
-      # is missing the count_distinct key fail open + log + bump errors_total +
-      # flag the Result, and the loop continues to the next rule (the rule is
-      # treated as not applicable rather than aborting the whole evaluation).
+      # is missing the count_distinct key fail open + log + flag the Result, and
+      # the loop continues to the next rule (the rule is treated as not
+      # applicable rather than aborting the whole evaluation).
       #
       # Error handling stays whole-check (see #check): a raise part-way through
       # discards the results of the rules already evaluated, even though their
@@ -234,7 +233,6 @@ module Labkit
 
           if rule.count_distinct && missing_count_distinct_value?(rule, identifier)
             log_missing_count_distinct(rule, identifier)
-            report_error_metrics
             result.degraded!
             next
           end
@@ -248,7 +246,6 @@ module Labkit
         # The loop is done, so anything raised from here on belongs to no rule.
         cursor.rule = nil
 
-        report_unmatched_metrics unless result.matched?
         result
       rescue StandardError => e # binds e for the ensure
         raise
@@ -393,11 +390,10 @@ module Labkit
         Result::Evaluation.new(rule: rule, exceeded: count > resolved_limit, info: info)
       end
 
-      # The limiter, rule and characteristics sit inside a Redis hash tag, so a
-      # counter and its ban always hash to the same cluster slot. BAN_SCRIPT
-      # touches both in one call, and Redis Cluster rejects a script whose keys
-      # span slots. +suffix+ is appended outside the tag, so it cannot change
-      # the slot and cannot collide with a characteristic value.
+      # The braces are the cluster hash tag: a counter and its ban must share a
+      # slot because BAN_SCRIPT touches both in one call. The rule name stays
+      # inside it so one identifier's keys spread across nodes instead of piling
+      # onto one. +suffix+ sits outside, so it cannot change the slot.
       def build_redis_key(rule, identifier, suffix = nil)
         key = "#{REDIS_KEY_PREFIX}:{#{@name}:#{rule.name}"
         rule.characteristics.each do |char|
@@ -566,12 +562,6 @@ module Labkit
           rule_labels.merge(action: evaluation.rule.action.to_s, result: evaluation_result(evaluation)),
           logger: @logger
         )
-        # Deprecated dual emission - remove together with Metrics.calls_total.
-        Metrics.safe_increment(
-          :calls_total,
-          rule_labels.merge(action: (evaluation.exceeded? ? evaluation.rule.action : :allow).to_s),
-          logger: @logger
-        )
         Metrics.safe_set(:limit_gauge, rule_labels, evaluation.info.resolved_limit, logger: @logger)
         Metrics.safe_set(:period_gauge, rule_labels, evaluation.info.resolved_period, logger: @logger)
       end
@@ -595,13 +585,6 @@ module Labkit
           { rate_limiter: @name, rule: rule.name, action: "skip", result: "skip" },
           logger: @logger
         )
-        # Deprecated dual emission - remove together with Metrics.calls_total.
-        Metrics.safe_increment(:calls_total, { rate_limiter: @name, rule: rule.name, action: "skip" }, logger: @logger)
-      end
-
-      # Deprecated dual emission - remove together with Metrics.calls_total.
-      def report_unmatched_metrics
-        Metrics.safe_increment(:calls_total, { rate_limiter: @name, rule: "unmatched", action: "allow" }, logger: @logger)
       end
 
       def report_check_metrics(result)
@@ -617,8 +600,12 @@ module Labkit
         )
       end
 
-      def report_error_metrics
-        Metrics.safe_increment(:errors_total, { rate_limiter: @name }, logger: @logger)
+      def report_peek_metrics(result)
+        Metrics.safe_increment(
+          :peeks_total,
+          { rate_limiter: @name, error: (result.error? || result.degraded?).to_s },
+          logger: @logger
+        )
       end
     end
   end

data/lib/labkit/rate_limit/metrics.rb

@@ -52,14 +52,12 @@ module Labkit
         )
       end
 
-      # Deprecated: superseded by checks_total and rule_evaluations_total.
-      # Emitted unchanged (once per matched rule, rule="unmatched" when none
-      # matched) until consumers migrate; will get removed in a follow-up release.
-      def calls_total
+      # Emitted exactly once per #peek call, including calls that fail open.
+      def peeks_total
         Labkit::Metrics::Client.counter(
-          :gitlab_labkit_rate_limiter_calls_total,
-          'Total number of successful rate limit checks',
-          { rate_limiter: nil, rule: nil, action: nil }
+          :gitlab_labkit_rate_limiter_peeks_total,
+          'Total number of rate limit peeks',
+          { rate_limiter: nil, error: nil }
         )
       end
 
@@ -73,16 +71,6 @@ module Labkit
         )
       end
 
-      # Deprecated: superseded by checks_total{error="true"}. Still emitted
-      # because it remains the only error metric for #peek.
-      def errors_total
-        Labkit::Metrics::Client.counter(
-          :gitlab_labkit_rate_limiter_errors_total,
-          'Total number of rate limit check errors',
-          { rate_limiter: nil }
-        )
-      end
-
       def limit_gauge
         Labkit::Metrics::Client.gauge(
           :gitlab_labkit_rate_limiter_limit,

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gitlab-labkit
 version: !ruby/object:Gem::Version
-  version: 4.6.0
+  version: 5.0.0
 platform: ruby
 authors:
 - Andrew Newdigate