yabeda-gvl_metrics 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f265172814eb83a804e681355deef2db2dafbc7f37da386273eb7ce220b1b409
-  data.tar.gz: 1cae20c48cf0478512afcd118945f58b9291da91c30014cdc546a0c4ba9b7a7c
+  metadata.gz: c8749669e68bbeda5b52d65280f39b68f008e23f7d043bb35a3cd993acd2ff5a
+  data.tar.gz: a7bb3003b69681c70b99e73be3330a694abd8036168c0a858678b47a8a3bbf95
 SHA512:
-  metadata.gz: 69ab9b4aed9771456be0586d35c8d06430f556ffd272c774df2e3c1b624ed240772196f903224d1049232c045562b5f7d8f13c88f01e23040eee83e4d5731890
-  data.tar.gz: 0b080cf1392f5acd4aa6472a4ecc3e3529be3ba56f5f7699cfbf76d84f14931f88ce0d452ba19c846c0853beb761058a584f24d271190b810a5d019e087e2d34
+  metadata.gz: 9ae994b9f1fdf4a6540024680ebaf90d05f36f5ca74238c853329217cd5184265a1e171d02df43ba975ad7e3e4c0e452013278250553514e7d59d8628c98cc07
+  data.tar.gz: 921f39479601ea69507705d6edfd3d40d2c7386869ca6e380a2a0b0fff034fbfdd06fb23560225eed300dace047dca93e1277e84d87faafd70ef4e7774d2a40b

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 ## [Unreleased]
 
+### Added
+
+- `hostname`, `pid`, `queue`, and `job_class` tags on all GVL metrics. `hostname`/`pid` identify the emitting process (`pid` is read per measurement so it stays correct under forking servers); `queue`/`job_class` segment Sidekiq metrics by the job's queue and class. All values are sourced locally — from within the process and from the data `gvl_metrics_middleware` already passes to the callback — with no `Sidekiq::ProcessSet`/Redis lookup. `queue` and `job_class` are empty for Rack.
+
 ## [0.1.0] - 2026-02-09
 
 - Initial release

data/README.md

@@ -40,16 +40,32 @@ For non-Rails applications, call `configure!` directly after requiring the gem.
 
 ## Metrics
 
-All metrics are registered as Yabeda gauges in the `gvl_metrics` group with a `source` tag, reported in nanoseconds. Each gauge holds the value from the most recent request or job.
+All metrics are registered as Yabeda gauges in the `gvl_metrics` group, reported in nanoseconds. Each gauge holds the value from the most recent request or job for a given set of tags.
 
 For metric definitions, see: https://github.com/speedshop/gvl_metrics_middleware?tab=readme-ov-file#available-metrics
 
-| Metric | Tag | Description |
-|--------|-----|-------------|
-| `gvl_metrics_total` | `source: "rack"` or `source: "sidekiq"` | Total time (running + io_wait + gvl_wait) |
-| `gvl_metrics_running` | `source: "rack"` or `source: "sidekiq"` | Time spent running Ruby code |
-| `gvl_metrics_io_wait` | `source: "rack"` or `source: "sidekiq"` | Time spent waiting on IO |
-| `gvl_metrics_gvl_wait` | `source: "rack"` or `source: "sidekiq"` | Time spent waiting on the GVL |
+| Metric | Description |
+|--------|-------------|
+| `gvl_metrics_total` | Total time (running + io_wait + gvl_wait) |
+| `gvl_metrics_running` | Time spent running Ruby code |
+| `gvl_metrics_io_wait` | Time spent waiting on IO |
+| `gvl_metrics_gvl_wait` | Time spent waiting on the GVL |
+
+### Tags
+
+Every metric carries the following tags, so you can attribute GVL time to a specific process and, for Sidekiq, to the job that ran:
+
+| Tag | Description |
+|-----|-------------|
+| `source` | `"rack"` or `"sidekiq"` |
+| `hostname` | Host the process runs on (`ENV["DYNO"]` if set, otherwise `Socket.gethostname` — the same value Sidekiq reports for itself) |
+| `pid` | Process ID. Read fresh on every measurement, so it stays correct under forking servers (e.g. Puma in cluster mode) |
+| `queue` | Sidekiq only: the queue the job was pulled from. Empty for Rack. |
+| `job_class` | Sidekiq only: the job's class name. Empty for Rack. |
+
+The `hostname`, `pid`, `queue`, and `job_class` values are read locally from within the running process and from the data `gvl_metrics_middleware` already passes to the callback — there is no `Sidekiq::ProcessSet`/Redis lookup involved.
+
+> **Cardinality:** `queue` and especially `job_class` multiply the number of time series per process (one series per `source`/`queue`/`job_class` combination), and `pid` produces a new series for every restart or redeploy. On apps with many job classes this can add up — keep an eye on your metrics backend's cardinality.
 
 ## Contributing
 

data/lib/yabeda/gvl_metrics/version.rb

@@ -2,6 +2,6 @@
 
 module Yabeda
   module GvlMetrics
-    VERSION = "0.1.0"
+    VERSION = "0.2.0"
   end
 end

data/lib/yabeda/gvl_metrics.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "socket"
+
 require "yabeda"
 require "gvl_metrics_middleware"
 
@@ -10,7 +12,7 @@ module Yabeda
     class Error < StandardError; end
 
     METRIC_GROUP = :gvl_metrics
-    METRIC_TAGS = [:source].freeze
+    METRIC_TAGS = %i[source hostname pid queue job_class].freeze
 
     class << self
       def configure!(rack: defined?(::Rack), sidekiq: defined?(::Sidekiq))
@@ -39,26 +41,60 @@ module Yabeda
         GvlMetricsMiddleware.configure do |config|
           if rack
             config.rack do |total, running, io_wait, gvl_wait|
-              record("rack", total, running, io_wait, gvl_wait)
+              record_rack(total, running, io_wait, gvl_wait)
             end
           end
 
           if sidekiq
-            config.sidekiq do |total, running, io_wait, gvl_wait|
-              record("sidekiq", total, running, io_wait, gvl_wait)
+            # gvl_metrics_middleware already hands the current job's queue and
+            # class to the callback as keyword arguments, so we can segment by
+            # them without any Sidekiq::ProcessSet/Redis lookup. They are given
+            # defaults so this stays compatible with any middleware version that
+            # does not send them.
+            config.sidekiq do |total, running, io_wait, gvl_wait, queue: nil, job_class: nil|
+              record_sidekiq(total, running, io_wait, gvl_wait, queue: queue, job_class: job_class)
             end
           end
         end
       end
 
-      def record(source, total, running, io_wait, gvl_wait)
-        tags = { source: source }
+      def record_rack(total, running, io_wait, gvl_wait)
+        write_metrics({ source: "rack", hostname: hostname, pid: ::Process.pid }, total, running, io_wait, gvl_wait)
+      end
+
+      def record_sidekiq(total, running, io_wait, gvl_wait, queue: nil, job_class: nil)
+        tags = {
+          source: "sidekiq",
+          hostname: hostname,
+          pid: ::Process.pid,
+          queue: queue.to_s,
+          job_class: job_class.to_s,
+        }
+
+        write_metrics(tags, total, running, io_wait, gvl_wait)
+      end
+
+      def write_metrics(tags, total, running, io_wait, gvl_wait)
+        # Every gauge is declared with the full METRIC_TAGS set, and exporters such
+        # as yabeda-prometheus reject a write that omits any declared tag. Default
+        # the tags a source does not set (queue/job_class for Rack) to an empty
+        # string so callers don't have to spell them out.
+        tags = { queue: "", job_class: "" }.merge(tags)
 
         Yabeda.gvl_metrics.total.set(tags, total)
         Yabeda.gvl_metrics.running.set(tags, running)
         Yabeda.gvl_metrics.io_wait.set(tags, io_wait)
         Yabeda.gvl_metrics.gvl_wait.set(tags, gvl_wait)
       end
+
+      # The host name does not change across a fork, so memoizing it (even if the
+      # value is inherited by a forked worker) is safe. The pid, which does change
+      # on fork, is read fresh on every call instead, so it stays correct under
+      # forking servers such as Puma in cluster mode. This mirrors how Sidekiq
+      # itself derives its hostname.
+      def hostname
+        @hostname ||= ENV["DYNO"] || Socket.gethostname
+      end
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yabeda-gvl_metrics
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Nate Berkopec
@@ -77,7 +77,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.12
 specification_version: 4
 summary: Yabeda plugin for exporting GVL metrics collected by gvl_metrics_middleware.
 test_files: []