Add Prometheus metrics endpoint with HTTP Basic Auth by vutratenko · Pull Request #437 · vol1ura/Sat_9am_5km

vutratenko · 2026-07-08T11:43:37Z

Summary

New endpoint GET /metrics with Prometheus Text Exposition Format
HTTP Basic Auth using PROMETHEUS_USERNAME/PROMETHEUS_PASSWORD env vars
Returns 503 if credentials not configured
All metrics cached with 5-minute TTL using Rails.cache
Comprehensive test coverage with RSpec
Documentation added to docs/prometheus_metrics.md

Metrics Implemented

Event Metrics

s95_events_total{country,active}
s95_activities_total{event,country,published}
s95_activity_results_total{event,activity_date}
s95_activity_volunteers_total{event,activity_date}
s95_activity_first_runs_total{event,activity_date}
s95_activity_personal_bests_total{event,activity_date}

Athlete Metrics

s95_athletes_total{event,country}
s95_athletes_with_user_total{event}
s95_athletes_with_gender_total{event,gender}
s95_athletes_with_external_code_total{source}
s95_athletes_going_to_event_total{event}

Result Metrics

s95_activity_average_time_seconds{event,activity_date}
s95_activity_median_time_seconds{event,activity_date}
s95_activity_best_time_seconds{event,activity_date,gender}
s95_activity_pb_ratio{event,activity_date}
s95_activity_first_run_ratio{event,activity_date}
s95_activity_correct{event,activity_date}

Volunteer Metrics

s95_volunteers_total{event,activity_date}
s95_volunteers_by_role_total{event,activity_date,role}
s95_unique_volunteers_total{event,window}
s95_volunteer_roles_covered_total{event,activity_date}
s95_volunteer_position_coverage_ratio{event,activity_date}
s95_volunteer_bus_factor{event}

Location Health Metrics

s95_active_community_total{event,window}
s95_unique_athletes_total{event,window}
s95_returning_athletes_total{event,window}
s95_sleeping_athletes_total{event,window}
s95_location_health_score{event}

Data Quality Metrics

s95_activity_has_results{event,activity_date}
s95_activity_published{event,activity_date}
s95_incorrect_results_total{event}
s95_doubled_results_total{event,activity_date}
s95_uninformed_results_total{event}
s95_uninformed_volunteers_total{event}

Configuration

Set these environment variables to enable the metrics endpoint:

PROMETHEUS_USERNAME
PROMETHEUS_PASSWORD

Testing

Run tests with: bundle exec rspec

Documentation

See docs/prometheus_metrics.md for detailed metric descriptions, labels, and Prometheus configuration examples.

- New endpoint GET /metrics with Prometheus Text Exposition Format - HTTP Basic Auth using PROMETHEUS_USERNAME/PROMETHEUS_PASSWORD env vars - Returns 503 if credentials not configured - All metrics cached with 5-minute TTL using Rails.cache - Implemented services: * Metrics::S95Collector - main metrics aggregator * Metrics::LocationHealthCalculator - health score calculations * Metrics::VolunteerBusFactorCalculator - bus factor calculations - Metrics implemented: * Event metrics (s95_events_total, s95_activities_total, etc.) * Athlete metrics (s95_athletes_total, s95_athletes_with_user_total, etc.) * Result metrics (s95_activity_average_time_seconds, s95_activity_median_time_seconds, etc.) * Volunteer metrics (s95_volunteers_total, s95_volunteer_bus_factor, etc.) * Location health metrics (s95_location_health_score, active_community, etc.) * Data quality metrics (s95_activity_correct, s95_incorrect_results_total, etc.) - Comprehensive test coverage with RSpec - Documentation added to docs/prometheus_metrics.md

vol1ura

А где будет инстанс прометеуса?

Remove the unused prometheus-client gem and initializer so CI no longer fails due to Gemfile/Gemfile.lock mismatch in deployment mode. Co-authored-by: Cursor <cursoragent@cursor.com>

Use nested module style, sum, explicit parentheses, and trailing comma to satisfy CI lint checks. Co-authored-by: Cursor <cursoragent@cursor.com>

vutratenko · 2026-07-09T16:05:29Z

А где будет инстанс прометеуса?

Вариантов масса - пока была мысль забрать своим, построить дашборды и показать как это работает. А там либо рядом поднять в каком-то виде, или на отдельной VDS. В том же клауд.ру бесплатную взять - её хватит

Switch metrics auth to Authorization header token, remove unnecessary CSRF skip and docs file, and fix LocationHealthCalculator indentation so lint-ruby passes. Co-authored-by: Cursor <cursoragent@cursor.com>

vutratenko · 2026-07-09T16:24:40Z

Поправил по ревью:

убрал skip_before_action :verify_authenticity_token — для GET он не нужен
auth перевёл на заголовок Authorization с токеном из PROMETHEUS_TOKEN (по аналогии с API::Parkzhrun::ApplicationController)
удалил docs/prometheus_metrics.md
починил отступы в LocationHealthCalculator для lint-ruby

По вопросу про инстанс Prometheus: в этом PR только endpoint /metrics в приложении. Сам Prometheus — внешний scraper (например, уже существующий monitoring stack), который ходит на приложение по расписанию. Пример scrape config:

scrape_configs:
  - job_name: sat_9am_5km
    metrics_path: /metrics
    authorization:
      credentials: <PROMETHEUS_TOKEN>
    static_configs:
      - targets: ['app.example.com']

Если нужно, могу отдельным PR добавить deploy-конфиг для Prometheus.

vol1ura

Сейчас возникли очень большие сомнения по поводу производительности, можно положить сайт такими запросами

Особо подробно пока не смотрел, возможно что-то можно оптимизировать

vol1ura · 2026-07-09T18:10:03Z

+    private
+
+    def calculate_activity_frequency_factor
+      six_months_ago = Date.current - 6.months


можно без переменной, сразу 6.months.ago.to_date

vol1ura · 2026-07-09T18:10:52Z

+    def calculate_activity_frequency_factor
+      six_months_ago = Date.current - 6.months
+      recent_activities = Activity.published.where(event: @event, date: six_months_ago..).count
+      (recent_activities.to_f / 26.0 * 100).clamp(0, 100)


26.0 - magic number

vol1ura · 2026-07-09T18:14:49Z

+      factors << calculate_activity_frequency_factor
+      factors << calculate_volunteer_consistency_factor
+      factors << calculate_athlete_retention_factor
+      factors << calculate_results_quality_factor


предлагаю все эти методы называть без префикса calculate_

vol1ura · 2026-07-09T18:17:58Z

+      recent_volunteers = Volunteer.joins(:activity)
+        .where(activity: { event: @event, published: true, date: (Date.current - 6.months).. })
+        .distinct.count(:athlete_id)
+      total_volunteers = Volunteer.joins(:activity)


Тут и выше можно сократить за счёт скоупа
Volunteer.published.where(activity: { event: @event }).distinct.count(:athlete_id)

и аналогично с результатами Result.published...

vol1ura · 2026-07-09T18:24:17Z

+
+    def calculate_athlete_retention_factor
+      six_months_ago = Date.current - 6.months
+      total_athletes = @event.athletes.count


это число участников, поставивших это мероприятие домашним забегом - точно именно это имелось в виду?

vol1ura · 2026-07-09T18:36:40Z

+      total = recent_results.count
+      return 100 if total.zero?
+
+      incorrect = recent_results.count { |result| !result.correct? }


А зачем это? Мне кажется, не особо актуально. Забег не получится опубликовать, если есть некорректный результат. Единственное, кто-то может в опубликованном забеге сделать правку, но это редкость (сейчас в проде ни одного некорректного результата нет).

Тут разве что может оказаться полезен алерт (возможно)... Но тогда наверно нет смысла за 3 месяца смотреть, достаточно 3 недель (или сколько там сейчас разрешено редактировать старые + 1).

vol1ura · 2026-07-09T18:46:53Z

+
+  def metrics_data
+    Rails.cache.fetch('s95_metrics', expires_in: Metrics::S95Collector::TTL) do
+      Metrics::S95Collector.call


Попробовал локально в дев консоли запустить на продовой базе - тут гигантское количество sql запросов, у меня на маке минут 10-15 выполнялось, я не дождался и прервал (с выводом запросов в консоль, т.е. на проде будет конечно быстрее, тем не менее - с ростом базы время будет только расти). Если кеш пустой, серия таких запросов может положить сайт

Ещё было видно, что где-то есть N+1 по атлетам

vol1ura · 2026-07-09T18:53:28Z


  get 'up', to: 'rails/health#show'

+  get '/metrics', to: 'metrics#show'


вроде / не нужен - как в 'up'

vol1ura · 2026-07-09T18:58:56Z

+
+module Metrics
+  class VolunteerBusFactorCalculator < ApplicationService
+    ROLES = %w[


тут имя у константы я бы сделал более говорящим, тут же не все возможные роли Volunteer.roles.keys - только те из них,которые имеют значение для проведения

vol1ura · 2026-07-09T18:59:46Z

+
+        next if volunteers.zero?
+
+        volunteers * 1.5


1.5 - magic value

vol1ura · 2026-07-09T19:10:21Z

+        ENV['PROMETHEUS_TOKEN'] = 'test-token'
+      end
+
+      it 'returns 503 Service Unavailable' do


кмк правильнее отдавать 4xx код, например, 401, 403 или 404(типа не существует такого для внешнего мира)

vutratenko · 2026-07-10T10:03:36Z

@vol1ura cпасибо за ревью и разумные замечания по перфомансу)

Что поменял:

/metrics больше не собирает метрики на cache miss и не ходит в БД при scrape, а только отдаёт последний snapshot из Rails.cache.
Если snapshot ещё не собран, endpoint всё равно отвечает 200 и отдаёт служебные метрики snapshot_ready/generated_at/age.
Добавил отдельный metrics:refresh для обновления snapshot.
Убрал тяжёлые и спорные метрики: location health, bus factor, median/best time, active community и глобальные athlete scans.
В collector оставил только лёгкие aggregate/group/count запросы; для results/volunteers ограничил окно последними 12 неделями.
Auth теперь принимает Authorization: Bearer , совместимо с Prometheus и vmagent/VictoriaMetrics. Raw token тоже оставил для обратной совместимости.
Поправил route на get 'metrics' и 404 при отсутствующем PROMETHEUS_TOKEN.
Исправил CodeQL warning по escaping label values.

github-advanced-security AI found potential problems Jul 8, 2026

View reviewed changes

Comment thread app/controllers/metrics_controller.rb Fixed

vol1ura reviewed Jul 8, 2026

View reviewed changes

Comment thread docs/prometheus_metrics.md Outdated

vol1ura reviewed Jul 8, 2026

View reviewed changes

Comment thread app/controllers/metrics_controller.rb Outdated

vol1ura reviewed Jul 8, 2026

View reviewed changes

Comment thread Gemfile Outdated

vol1ura requested changes Jul 8, 2026

View reviewed changes

vutratenko and others added 2 commits July 9, 2026 13:15

fix CI deployment-mode bundle install for metrics PR

230874d

Remove the unused prometheus-client gem and initializer so CI no longer fails due to Gemfile/Gemfile.lock mismatch in deployment mode. Co-authored-by: Cursor <cursoragent@cursor.com>

Fix RuboCop offenses in location health calculator.

985a90f

Use nested module style, sum, explicit parentheses, and trailing comma to satisfy CI lint checks. Co-authored-by: Cursor <cursoragent@cursor.com>

Address PR review feedback for Prometheus metrics endpoint

89a99f5

Switch metrics auth to Authorization header token, remove unnecessary CSRF skip and docs file, and fix LocationHealthCalculator indentation so lint-ruby passes. Co-authored-by: Cursor <cursoragent@cursor.com>

Fix Prometheus metrics lint and specs

91c241c

vutratenko force-pushed the feature/prometheus-metrics branch from 3ccb1af to 91c241c Compare July 9, 2026 17:16

vol1ura requested changes Jul 9, 2026

View reviewed changes

vol1ura reviewed Jul 9, 2026

View reviewed changes

vol1ura added the enhancement New feature or request label Jul 9, 2026

Use snapshot cache for Prometheus metrics

4dba97c

github-advanced-security AI found potential problems Jul 9, 2026

View reviewed changes

Comment thread app/services/metrics/s95_collector.rb Fixed

Fix Prometheus label escaping

f57d153

vol1ura force-pushed the master branch 5 times, most recently from 47b9265 to 0f18e53 Compare August 1, 2026 04:50


		get 'up', to: 'rails/health#show'

		get '/metrics', to: 'metrics#show'

Conversation

vutratenko commented Jul 8, 2026

Summary

Metrics Implemented

Event Metrics

Athlete Metrics

Result Metrics

Volunteer Metrics

Location Health Metrics

Data Quality Metrics

Configuration

Testing

Documentation

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

vol1ura left a comment

Choose a reason for hiding this comment

Uh oh!

vutratenko commented Jul 9, 2026

Uh oh!

vutratenko commented Jul 9, 2026

Uh oh!

vol1ura left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

vutratenko commented Jul 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

vol1ura left a comment •

edited

Loading