gitlab-exporter 17.0.0 → 17.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3cc0cadf1891c19066f388f384d51f47b9c489e8e0ee7c162565228fb661bada
-  data.tar.gz: 7ae7c0ac398b1832c58c2348297139fd88e3ff02e447669043990312160ed0a8
+  metadata.gz: 0f38401d83375e243787b0f692035d11cc9cc9e5a3bde34ca9d468261be12a41
+  data.tar.gz: 4f8f1dbed6854da6003209745214b6687f405145b79c5dc2a0ee06d0bbedec4f
 SHA512:
-  metadata.gz: 7a358dbc90fe7bed11fc33a179fe2eb726e0d218925a56e7f076cc4c51d14272de4adca57cd5ae084e0a57d51feed0cf331b2dbf3ae67a5c0a2a972c4dba1863
-  data.tar.gz: c937591c8d81ad5296955bd5a55f92bcdd6f2ecb0f1fe7cdd36e9f429e88f5bbf2da8bce8375e8897fec29eda18ea0dd60fcd1bbfc5070c49e9b886a0faf3037
+  metadata.gz: 7c88e061a15dcc9f640c29a910de6d81eedb345c113bce789b08a44a252ddc708bdb082e5aa7ee881eb383dcf51c72d34fd7ec8c00353fe210e0b97915e05ab4
+  data.tar.gz: 9a26c277997d178c65607aadbba2b82b931bc1375a1f732c35665639cfb1a404869409272f85b640df8a5f101cf25eddee985c1f20dbb8d75f6904aaffd1e7c6

data/.gitlab-ci.yml

@@ -32,7 +32,7 @@ default:
      # to avoid https://github.com/rubygems/rubygems/issues/5380 use an
      # older Bundler version.
      case ${RUBY_VERSION} in
-       "3.0"|"3.1")
+       "3.1")
            export BUNDLER_VERSION="2.4.20"
            ;;
      esac
@@ -53,7 +53,7 @@ rspec:
   before_script: *before_scripts
   parallel:
     matrix:
-      - RUBY_VERSION: ["3.0", "3.1", "3.2", "3.3", "3.4"]
+      - RUBY_VERSION: ["3.1", "3.2", "3.3", "3.4", "4.0"]
 
 rspec_integration:
   script:
@@ -88,7 +88,7 @@ rspec_integration:
     REDIS_SENTINEL_PASSWORD: "my-sentinel-password"
   parallel:
     matrix:
-      - RUBY_VERSION: ["3.0", "3.1", "3.2", "3.3", "3.4"]
+      - RUBY_VERSION: ["3.1", "3.2", "3.3", "3.4", "4.0"]
 
 rubocop:
   script:

data/.rubocop.yml

@@ -1,7 +1,7 @@
 inherit_from: .rubocop_todo.yml
 
 AllCops:
-  TargetRubyVersion: 3.0
+  TargetRubyVersion: 3.1
   DisplayCopNames: true
 
 # Just use double quotes please

data/.ruby-version

@@ -1 +1 @@
-3.0.7
+3.1.7

data/AGENTS.md

@@ -0,0 +1,75 @@
+# gitlab-exporter — AI agent guidelines
+
+gitlab-exporter is a Prometheus web exporter (a Ruby gem) that collects GitLab
+production metrics via custom probes and exposes them over HTTP for a Prometheus
+scraper. See `README.md` for the probe catalog.
+
+## Project layout
+
+- `lib/gitlab_exporter/` — probes and the exporter runtime
+- `lib/gitlab_exporter/version.rb` — the gem version; bumping this on `master`
+  triggers a release (see below)
+- `bin/gitlab-exporter` — executable entry point
+- `spec/` — RSpec tests (`-t integration` marks integration specs that need Redis/PG)
+
+## Development commands
+
+```sh
+bundle install
+bundle exec rspec spec           # unit tests
+bundle exec rspec spec -t integration   # integration tests (needs Redis/Postgres)
+bundle exec rubocop              # lint
+```
+
+## Commit messages
+
+Follow the [GitLab commit message guidelines](https://docs.gitlab.com/development/contributing/merge_request_workflow/#commit-messages-guidelines).
+
+- Subject: imperative mood, capitalized, no trailing period, ≤ 72 chars
+  ("Add Zoekt probe", not "Added Zoekt probe").
+- Body: explain *why*, wrap at 72 chars. Reference issues/MRs with full URLs,
+  not short references (`#123`).
+
+## Changelog trailer (required for user-facing changes)
+
+Releases are cut by the `gem-release` CI component, which builds the release
+notes from GitLab's changelog generator. That generator **only includes commits
+that carry a `Changelog:` git trailer** — commits without one are dropped, which
+is why a release can end up saying "No changes." and produce an empty changelog
+in downstream projects (e.g. omnibus-gitlab's Renovate MRs).
+
+Add the trailer as a **separate block at the end of the commit message**,
+preceded by a blank line (the blank line is required for git to parse it as a
+trailer; without it the changelog generator silently drops the commit):
+
+```
+Changelog: <type>
+```
+
+Valid types: `added`, `fixed`, `changed`, `deprecated`, `removed`, `security`,
+`performance`, `other`.
+
+**Include a trailer for:** new or changed probes/metrics, behavior changes,
+bug fixes, dependency bumps that affect users, security fixes.
+
+**Skip the trailer for:** test-only changes, documentation-only changes, CI/
+tooling-only changes, and pure internal refactors with no user-visible effect.
+
+Example:
+
+```
+Add remote mirror staleness metric
+
+Exposes project_remote_mirror_last_successful_update_time_seconds so
+operators can alert on mirrors that have stopped syncing.
+
+Changelog: added
+```
+
+## Releasing
+
+A release happens when `lib/gitlab_exporter/version.rb` changes on `master`.
+The CI pipeline then generates the changelog from the `Changelog:` trailers
+since the previous tag, creates the GitLab Release, and publishes the gem to
+RubyGems. Keeping trailers accurate on every merged commit is what makes those
+release notes meaningful.

data/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

data/Gemfile.lock

@@ -1,8 +1,8 @@
 PATH
   remote: .
   specs:
-    gitlab-exporter (17.0.0)
-      base64 (= 0.2.0)
+    gitlab-exporter (17.0.2)
+      base64 (= 0.3.0)
       connection_pool (= 2.5.5)
       deep_merge (~> 1.2.2)
       faraday (= 2.14.3)
@@ -17,7 +17,7 @@ GEM
   remote: https://rubygems.org/
   specs:
     ast (2.4.3)
-    base64 (0.2.0)
+    base64 (0.3.0)
     connection_pool (2.5.5)
     deep_merge (1.2.2)
     diff-lcs (1.5.0)
@@ -57,11 +57,11 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.12.0)
     rspec-support (3.12.0)
-    rubocop (1.84.2)
+    rubocop (1.89.0)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
-      parallel (~> 1.10)
+      parallel (>= 1.10)
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 2.9.3, < 3.0)
@@ -78,7 +78,7 @@ GEM
       redis (>= 4.5.0, < 5)
     unicode-display_width (3.1.4)
       unicode-emoji (~> 4.0, >= 4.0.4)
-    unicode-emoji (4.0.4)
+    unicode-emoji (4.2.0)
     webrick (1.9.1)
 
 PLATFORMS
@@ -91,4 +91,4 @@ DEPENDENCIES
   rubocop (~> 1.0)
 
 BUNDLED WITH
-   2.7.1
+  4.0.10

data/README.md

@@ -23,9 +23,10 @@ metrics.
      `gitlab_pg_sequences_min_value`, `gitlab_pg_sequences_max_value`, `gitlab_pg_sequences_current_value`
     * [Row count queries](lib/gitlab_exporter/database/row_count.rb) --
       `gitlab_database_rows`
-    * [CI builds](lib/gitlab_exporter/database/ci_builds.rb) --
+    * [CI builds](lib/gitlab_exporter/database/ci_builds.rb) (**deprecated**) --
       `ci_pending_builds`, `ci_created_builds`, `ci_stale_builds`,
-      `ci_running_builds`
+      `ci_running_builds`, `ci_unarchived_traces`
+      (see [Deprecated: CI builds metrics](#deprecated-ci-builds-metrics))
     * [Bloat](lib/gitlab_exporter/database/bloat.rb) --
       `gitlab_database_bloat_$type_$key` with type `btree` (index bloat) or `table`
       (table bloat) and keys `bloat_ratio bloat_size extra_size real_size` (see below)
@@ -133,6 +134,57 @@ Also see the [original documentation](https://github.com/ioguix/pgsql-bloat-esti
 Note that all metrics returned are estimates without an upper bound for
 the error.
 
+### Deprecated: CI builds metrics
+
+The [CI builds probe](lib/gitlab_exporter/database/ci_builds.rb) is deprecated and
+will be removed in a future major version. It collects its metrics by querying
+`p_ci_builds` directly, which puts avoidable load on tables that job scheduling
+already loads heavily, and it has had almost no maintenance since 2021. GitLab
+Rails and GitLab Runner instrument most of the same information by counting
+events as they happen; GitLab.com stopped using this probe for CI state years
+ago.
+
+The probe prints a deprecation notice on every run, and each of its metrics
+carries `(deprecated, ...)` in its `# HELP` line, so the warning reaches
+Prometheus and Grafana and not only the exporter's log.
+
+Replacements, where one exists:
+
+| Deprecated metric | Replacement |
+| --- | --- |
+| `ci_pending_builds` | `gitlab_ci_current_queue_size` (Rails, gauge, by `runner_type`) |
+| `ci_running_builds` | `gitlab_runner_jobs` (Runner, gauge, by `runner`, `state`, `stage`) |
+| `ci_created_builds` | None. A `created` build is not queued yet, so nothing counts it. |
+| `ci_stale_builds` | None. The nearest signal is `gitlab_ci_queue_operations_total{operation="build_status_stale"}` (Rails, counter), which counts stale rows met while queueing rather than how many are stale now. |
+| `ci_unarchived_traces` | None. |
+
+The replacements are not a like-for-like relabel: the Rails queue metrics are
+keyed by `runner_type` and the Runner metrics by runner, so neither carries the
+`namespace` label this probe reports. Queue health is better served by the Rails
+metrics that have no exporter equivalent at all -- `job_queue_duration_seconds`
+(how long jobs wait), `job_register_attempts_total` and
+`job_register_attempts_failed_total`, and `gitlab_ci_queue_operations_total`.
+Those four are always instrumented.
+
+**`gitlab_ci_current_queue_size`, and every other `gitlab_ci_queue_*` metric, is
+behind the `gitlab_ci_builds_queuing_metrics` ops feature flag, which is disabled
+by default.** Enable it before pointing a dashboard at them, or the replacement
+panels stay empty:
+
+```ruby
+Feature.enable(:gitlab_ci_builds_queuing_metrics)
+```
+
+Metric definitions live in
+[`lib/gitlab/ci/queue/metrics.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/queue/metrics.rb)
+(Rails) and
+[`commands/builds_helper.go`](https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/commands/builds_helper.go)
+(Runner). See
+[GitLab Prometheus metrics](https://docs.gitlab.com/administration/monitoring/prometheus/gitlab_metrics/)
+for enabling the Rails exporter, and
+[Monitoring runners](https://docs.gitlab.com/runner/monitoring/) for the
+Runner's.
+
 ## Contributing
 
 gitlab-exporter is an open source project and we are very happy to accept community contributions. Please refer to [CONTRIBUTING.md](/CONTRIBUTING.md) for details.

data/gitlab-exporter.gemspec

@@ -20,12 +20,12 @@ Gem::Specification.new do |s|
   s.homepage      = "https://gitlab.com/gitlab-org/ruby/gems/gitlab-exporter"
   s.license       = "MIT"
 
-  s.required_ruby_version = Gem::Requirement.new(">= 3.0")
+  s.required_ruby_version = Gem::Requirement.new(">= 3.1")
 
   # base64 is required by sidekiq but not declared by it, and is no longer a
   # default gem as of Ruby 3.4. It used to be pulled in transitively via
   # sinatra -> rack-protection; declare it directly now that those are gone.
-  s.add_runtime_dependency "base64", "0.2.0"
+  s.add_runtime_dependency "base64", "0.3.0"
   s.add_runtime_dependency "connection_pool", "2.5.5"
   s.add_runtime_dependency "deep_merge", "~> 1.2.2"
   s.add_runtime_dependency "faraday", "2.14.3"

data/lib/gitlab_exporter/database/ci_builds.rb

@@ -294,12 +294,53 @@ module GitLab
 
       # The prober which is called when gathering metrics
       class CiBuildsProber
+        # The stdout notice in #probe_db reaches whoever reads the exporter's log,
+        # which is not who reads the metrics. HELP is the one channel that travels
+        # with the sample to the scraper, so the deprecation rides there too: it
+        # survives into Prometheus and shows up in Grafana's metric browser.
+        DEPRECATED = "(deprecated, to be removed in a future major version)".freeze
+        REPLACEMENT = "See the CI builds entry in README.md for replacements.".freeze
+
+        PrometheusMetrics.describe(
+          "ci_created_builds",
+          "#{DEPRECATED} Number of CI builds in the created state, by namespace. #{REPLACEMENT}",
+          "gauge"
+        )
+
+        PrometheusMetrics.describe(
+          "ci_pending_builds",
+          "#{DEPRECATED} Number of CI builds in the pending state, by namespace. #{REPLACEMENT}",
+          "gauge"
+        )
+
+        PrometheusMetrics.describe(
+          "ci_stale_builds",
+          "#{DEPRECATED} Number of running CI builds not updated for over an hour. #{REPLACEMENT}",
+          "gauge"
+        )
+
+        PrometheusMetrics.describe(
+          "ci_running_builds",
+          "#{DEPRECATED} Number of running CI builds, by runner and namespace. #{REPLACEMENT}",
+          "gauge"
+        )
+
+        PrometheusMetrics.describe(
+          "ci_unarchived_traces",
+          "#{DEPRECATED} Number of finished CI builds whose trace is not archived. #{REPLACEMENT}",
+          "gauge"
+        )
+
         def initialize(metrics: PrometheusMetrics.new, **opts)
           @metrics = metrics
           @collector = CiBuildsCollector.new(**opts)
         end
 
         def probe_db
+          puts "[DEPRECATED] probe_db and CiBuildsProber are now considered obsolete"\
+            " and will be removed in a future major version,"\
+            " please use the CI/CD queuing metrics emitted by GitLab Rails instead"
+
           @results = @collector.run
 
           ci_builds_metrics(@results[:created_builds], "ci_created_builds") if @results[:created_builds]

data/lib/gitlab_exporter/database/tuple_stats.rb

@@ -35,8 +35,6 @@ module GitLab
 
           result.each do |table_name, tuple_stats|
             tuple_stats.each do |column_name, value|
-              next if value.is_a?(Numeric)
-
               @metrics.add("gitlab_database_stat_table_#{column_name}",
                            value.to_f,
                            table_name: table_name)

data/lib/gitlab_exporter/version.rb

@@ -1,5 +1,5 @@
 module GitLab
   module Exporter
-    VERSION = "17.0.0".freeze
+    VERSION = "17.0.2".freeze
   end
 end

data/spec/database/ci_builds_spec.rb

@@ -361,3 +361,55 @@ describe GitLab::Exporter::Database do
     end
   end
 end
+
+# Asserting on the notice keeps a later refactor of #probe_db from dropping it
+# silently, which would leave operators unwarned before the probe goes (issue #119).
+describe GitLab::Exporter::Database::CiBuildsProber do
+  let(:prober) do
+    described_class.new(connection_string: "host=localhost",
+                        metrics: GitLab::Exporter::PrometheusMetrics.new(include_timestamp: false))
+  end
+
+  let(:metric_names) do
+    %w[ci_created_builds ci_pending_builds ci_stale_builds ci_running_builds ci_unarchived_traces]
+  end
+
+  it "warns that the probe is deprecated and names the replacement" do
+    allow_any_instance_of(GitLab::Exporter::Database::CiBuildsCollector).to receive(:run)
+      .and_return(pending_builds: [], stale_builds: 0, per_runner: [], unarchived_traces: 0)
+
+    expect { prober.probe_db }.to output(/\[DEPRECATED\].*CiBuildsProber.*GitLab Rails/m).to_stdout
+  end
+
+  # The stdout notice never reaches the scraper. HELP does, so every metric the
+  # probe can emit has to carry the deprecation, not just the ones with a
+  # replacement.
+  it "describes every metric it can emit as deprecated" do
+    metric_names.each do |name|
+      expect(GitLab::Exporter::PrometheusMetrics.description(name))
+        .to start_with("(deprecated"), "#{name} is emitted without a deprecated HELP line"
+      expect(GitLab::Exporter::PrometheusMetrics.metric_type(name)).to eq("gauge")
+    end
+  end
+
+  it "renders the deprecation into the scrape output" do
+    allow_any_instance_of(GitLab::Exporter::Database::CiBuildsCollector).to receive(:run)
+      .and_return(pending_builds: [{ namespace: "1", shared_runners: "yes", value: 12 }],
+                  stale_builds: 3, per_runner: [], unarchived_traces: 0)
+
+    output = StringIO.new
+    capture_stdout do prober.probe_db.write_to(output) end
+
+    expect(output.string).to include("# HELP ci_pending_builds (deprecated")
+    expect(output.string).to include("# TYPE ci_pending_builds gauge")
+    expect(output.string).to include(%(ci_pending_builds{namespace="1",shared_runners="yes"} 12.0))
+  end
+
+  def capture_stdout
+    original = $stdout
+    $stdout = StringIO.new
+    yield
+  ensure
+    $stdout = original
+  end
+end

data/spec/database/tuple_stats_spec.rb

@@ -0,0 +1,40 @@
+require "spec_helper"
+require "gitlab_exporter/database/tuple_stats"
+
+describe GitLab::Exporter::Database::TuplesProber do
+  let(:opts) { { connection_string: "" } }
+  let(:metrics) { double("PrometheusMetrics", add: nil) }
+  let(:collector) { double("TupleStatsCollector", run: data) }
+
+  before do
+    allow(GitLab::Exporter::Database::TupleStatsCollector).to receive(:new).and_return(collector)
+  end
+
+  describe "#probe_db" do
+    subject { described_class.new(metrics: metrics, **opts).probe_db }
+
+    context "when the connection casts columns to native Integer (PG::BasicTypeMapForResults)" do
+      let(:data) { { "projects" => { "seq_tup_read" => 42, "n_dead_tup" => 0 } } }
+
+      it "still records a metric for every column" do
+        expect(metrics).to receive(:add)
+          .with("gitlab_database_stat_table_seq_tup_read", 42.0, table_name: "projects")
+        expect(metrics).to receive(:add)
+          .with("gitlab_database_stat_table_n_dead_tup", 0.0, table_name: "projects")
+
+        subject
+      end
+    end
+
+    context "when the connection returns unmapped string values" do
+      let(:data) { { "projects" => { "seq_tup_read" => "42" } } }
+
+      it "records a metric" do
+        expect(metrics).to receive(:add)
+          .with("gitlab_database_stat_table_seq_tup_read", 42.0, table_name: "projects")
+
+        subject
+      end
+    end
+  end
+end

data/spec/prometheus_metrics_spec.rb

@@ -29,15 +29,29 @@ describe GitLab::Exporter::PrometheusMetrics do
 
     allow(Time).to receive(:now).and_return(time)
 
-    described_class.describe("mymetric", "description")
-    described_class.describe("missingmetric", "otherdescription")
-    subject.add("mymetric", 1.3, mylabel: "x", myotherlabel: "y")
-
-    expect(subject.to_s).to eq(<<~METRICS)
+    # Descriptions are class-level state, and probes register theirs when their
+    # file loads, which happens once. Describing on a subclass keeps this example
+    # out of the shared registry: clearing it here would drop those registrations
+    # for every later example, and nothing can put them back.
+    metrics_class = Class.new(described_class)
+    metrics = metrics_class.new
+
+    metrics_class.describe("mymetric", "description")
+    metrics_class.describe("missingmetric", "otherdescription")
+    metrics.add("mymetric", 1.3, mylabel: "x", myotherlabel: "y")
+
+    expect(metrics.to_s).to eq(<<~METRICS)
       # HELP mymetric description
       mymetric{mylabel="x",myotherlabel="y"} 1.3 #{(time.to_f * 1000).to_i}
     METRICS
+  end
+
+  it "clears descriptions" do
+    metrics_class = Class.new(described_class)
+    metrics_class.describe("mymetric", "description", "gauge")
 
-    described_class.clear_descriptions
+    expect { metrics_class.clear_descriptions }
+      .to change { metrics_class.description("mymetric") }.from("description").to(nil)
+    expect(metrics_class.metric_type("mymetric")).to be_nil
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gitlab-exporter
 version: !ruby/object:Gem::Version
-  version: 17.0.0
+  version: 17.0.2
 platform: ruby
 authors:
 - Pablo Carranza
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.2.0
+        version: 0.3.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.2.0
+        version: 0.3.0
 - !ruby/object:Gem::Dependency
   name: connection_pool
   requirement: !ruby/object:Gem::Requirement
@@ -191,6 +191,8 @@ files:
 - ".rubocop.yml"
 - ".rubocop_todo.yml"
 - ".ruby-version"
+- AGENTS.md
+- CLAUDE.md
 - CONTRIBUTING.md
 - Gemfile
 - Gemfile.lock
@@ -230,6 +232,7 @@ files:
 - spec/database/ci_builds_spec.rb
 - spec/database/pg_sequences_spec.rb
 - spec/database/row_count_spec.rb
+- spec/database/tuple_stats_spec.rb
 - spec/database/zoekt_spec.rb
 - spec/elasticsearch_spec.rb
 - spec/fixtures/config.yml
@@ -256,7 +259,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.0'
+      version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -273,6 +276,7 @@ test_files:
 - spec/database/ci_builds_spec.rb
 - spec/database/pg_sequences_spec.rb
 - spec/database/row_count_spec.rb
+- spec/database/tuple_stats_spec.rb
 - spec/database/zoekt_spec.rb
 - spec/elasticsearch_spec.rb
 - spec/fixtures/config.yml