gitlab-labkit 2.4.0 → 2.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9feee9c8b400e6d23dae0a6b743f9e3a6f3074e005d8961686c8440d814a4b2f
-  data.tar.gz: 971fc652faca19f0a57e151db5d776c75f64be9b04d7ffccd4a4d4dd7b6a3d2a
+  metadata.gz: 15a3589c7770e0c9368d19d4acb2365fb627f40a7a2c3dd65c03057399585036
+  data.tar.gz: 2f45f67fd34c8031306f1cf7197e69f82d19215dc3fdb6fcb38ff1ff0b5fd804
 SHA512:
-  metadata.gz: 432a9a9842ca1e17cd1b25fa25303cb219c20a0f4cdd4201ac79a998fc8a72848f4a5dda0a9d3e31e3a0e312d88f97b9760915324892d7c5d2d607f18021e40e
-  data.tar.gz: 995aa133640851db2a9d649bd877705853cdfdce69959dd578f437d1d6e589193966202ffa83707f887ee28745d26bbcc2f96c4f87c3a68e951d3e3aeeb83cab
+  metadata.gz: c6858aecff6a32e4ca9b3b9c4b512b43de320b9f7b838348bb83de3d878a910b20169f64634c41bea4bdfa9f67db94ee2bf84864353e453296f8d40fd8d1934a
+  data.tar.gz: e4a9d5ac76d5e4b43220a469d7557c1bbfffb4fe9abb171978ee427981623ef4b1f1a20cde3c9b8c818b83e268eb0b509201a53f4aa47b74e924127ae03186b5

data/config/user_experience_slis/schema.json

@@ -21,15 +21,44 @@
         "sync_fast",
         "sync_slow",
         "async_fast",
-        "async_slow"
+        "async_slow",
+        "custom"
       ],
       "description": "Urgency level for this user experience"
+    },
+    "apdex_threshold_s": {
+      "type": "number",
+      "exclusiveMinimum": 0,
+      "maximum": 600,
+      "description": "Custom Apdex threshold duration in seconds. Required when urgency is custom."
     }
   },
   "required": [
     "description",
     "feature_category",
     "urgency"
+  ],
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "urgency": {
+            "const": "custom"
+          }
+        }
+      },
+      "then": {
+        "required": [
+          "apdex_threshold_s"
+        ]
+      },
+      "else": {
+        "not": {
+          "required": [
+            "apdex_threshold_s"
+          ]
+        }
+      }
+    }
   ]
 }
-

data/lib/labkit/fields.rb

@@ -90,6 +90,12 @@ module Labkit
     # GitLab pipeline numeric ID.
     GL_PIPELINE_ID = "gl_pipeline_id"
 
+    # GitLab namespace numeric ID.
+    GL_NAMESPACE_ID = "gl_namespace_id"
+
+    # GitLab root (top-level) namespace numeric ID.
+    GL_ROOT_NAMESPACE_ID = "gl_root_namespace_id"
+
     # Log event timestamp in ISO 8601 format (e.g. "2026-04-02T12:00:00.000Z").
     TIMESTAMP = "timestamp"
 
@@ -122,6 +128,10 @@ module Labkit
     # The endpoint_id of the original caller at the root of the call chain.
     ROOT_CALLER_ID = "root_caller_id"
 
+    # GitLab SentNotification record numeric ID associated with an incoming
+    # email reply.
+    GL_SENT_NOTIFICATION_ID = "gl_sent_notification_id"
+
     # Maps each field constant to its logging field variant version.
     # A version of 0 means the field is not yet assigned to any variant.
     VARIANT_VERSION = {
@@ -149,6 +159,8 @@ module Labkit
       TTFB_S => 0,
       GL_PROJECT_ID => 1,
       GL_PIPELINE_ID => 1,
+      GL_NAMESPACE_ID => 0,
+      GL_ROOT_NAMESPACE_ID => 0,
       TIMESTAMP => 0,
       SEVERITY => 0,
       LOG_MESSAGE => 1,
@@ -159,6 +171,7 @@ module Labkit
       ENDPOINT_ID => 0,
       CALLER_ID => 1,
       ROOT_CALLER_ID => 0,
+      GL_SENT_NOTIFICATION_ID => 0,
     }.freeze
 
     # Get the constant name for a field value

data/lib/labkit/user_experience_sli/README.md

@@ -107,6 +107,22 @@ https://docs.gitlab.com/development/feature_categorization/#feature-categorizati
 | `sync_slow`  | A user is awaiting a synchronous response which needs to be returned before they can continue with their action, but which the user may accept a slower response | Displaying a full-text search response while displaying an amusement animation | 5s    |
 | `async_fast` | An async process which may block a user from continuing with their user journey                                                                                  | MR diff update after git push                                                  | 15s   |
 | `async_slow` | An async process which will not block a user and will not be immediately noticed as being slow                                                                   | Notification following an assignment                                           | 5m    |
+| `custom`     | A user experience whose acceptable duration does not match the predefined urgency buckets                                                                        | Creating a merge request with an accepted threshold of 90s                     | Set by `apdex_threshold_s` |
+
+**Custom Apdex thresholds**
+
+Use `urgency: "custom"` when none of the predefined thresholds accurately represents the expected user experience. Custom urgency requires `apdex_threshold_s`.
+
+```yaml
+description: "Creating a new merge request in a project"
+feature_category: "code_review_workflow"
+urgency: "custom"
+apdex_threshold_s: 90
+```
+
+`apdex_threshold_s` is measured in seconds, must be greater than `0`, and cannot exceed `600`.
+
+Prefer the predefined urgency values unless the SLI would otherwise be permanently red or permanently green because the predefined thresholds do not match the experience.
 
 ## Usage
 

data/lib/labkit/user_experience_sli/experience.rb

@@ -209,7 +209,9 @@ module Labkit
       end
 
       def urgency_threshold
-        URGENCY_THRESHOLDS_IN_SECONDS[@definition.urgency.to_sym]
+        # Definitions are loaded through the registry, which validates the schema before instantiating them.
+        # The schema guarantees experience with custom urgency provide apdex_threshold_s.
+        @definition.apdex_threshold_s || URGENCY_THRESHOLDS_IN_SECONDS[@definition.urgency.to_sym]
       end
 
       def elapsed_time

data/lib/labkit/user_experience_sli/registry.rb

@@ -8,7 +8,11 @@ require 'labkit/json_schema/ref_resolver'
 
 module Labkit
   module UserExperienceSli
-    Definition = Data.define(:user_experience_id, :description, :feature_category, :urgency)
+    Definition = Data.define(:user_experience_id, :description, :feature_category, :urgency, :apdex_threshold_s) do
+      def initialize(user_experience_id:, description:, feature_category:, urgency:, apdex_threshold_s: nil)
+        super
+      end
+    end
 
     class Registry
       extend Forwardable
@@ -78,15 +82,16 @@ module Labkit
         content = YAML.safe_load(file_path.read)
         return nil unless content.is_a?(Hash)
 
-        return Definition.new(user_experience_id: experience_id, **content) if schema.valid?(content)
+        return Definition.new(user_experience_id: experience_id, **content.transform_keys(&:to_sym)) if schema.valid?(content)
 
         warn("Invalid schema for #{file_path}")
-
         nil
       rescue Psych::SyntaxError => e
         warn("Invalid definition file #{file_path}: #{e.message}")
+        nil
       rescue StandardError => e
         warn("Unexpected error processing #{file_path}: #{e.message}")
+        nil
       end
 
       def schema

metadata

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