Мониторинг GitLab с помощью Proto Observability

На этой странице:

• Сбор метрик GitLab
  • Конфигурация GitLab
  • Конфигурация ProtoOBP агента
    • Если агент запускается в виде службы на хосте
    • Если агент запускается в виде Docker контейнера
  • Проверка
  • Собираемые метрики
    • Лейблы
      • Общие (на всех метриках)
      • Специфичные для Sidekiq / Ruby
    • Метрики Sidekiq
    • Метрики Ruby процесса и GC
    • Метрики БД и Redis
    • Метрики CI / Pipelines
    • Транзакционные события
    • Service checks
  • Ключевые метрики для дашбордов и алертов
• Сбор логов GitLab
  • Права на каталоги логов
  • Конфигурация ProtoOBP агента
    • Если агент запускается в виде службы на хосте
    • Если агент запускается в виде Docker контейнера
  • Проверка

Сбор метрик GitLab

Интеграция gitlab собирает метрики через Prometheus exporter’ы, встроенные в GitLab Omnibus. Каждый компонент GitLab имеет свой exporter и слушает по умолчанию на 127.0.0.1:

В этом гайде описана базовая интеграция с Sidekiq Exporter — это рекомендуемый минимум, покрывающий ~80 % полезных метрик GitLab (Sidekiq, Ruby/GC, доступ к БД и Redis, события CI). Добавление остальных exporter’ов делается отдельным instances:-блоком в той же конфигурации либо через универсальную интеграцию openmetrics.

Конфигурация GitLab

В стандартной установке GitLab Omnibus sidekiq_exporter включён и слушает на 127.0.0.1:8082. Проверить:

sudo gitlab-ctl status | grep -E "exporter|prometheus"
sudo ss -ltnp | grep -E ":(8082|9090|9100|9168|9229|9236)"

Если порт 8082 не слушает — включите в /etc/gitlab/gitlab.rb:

sidekiq['metrics_enabled']   = true
sidekiq['exporter_enabled']  = true
sidekiq['exporter_address']  = '127.0.0.1'
sidekiq['exporter_port']     = 8082

И примените: sudo gitlab-ctl reconfigure.

gitlab_rails['monitoring_whitelist'] = ['127.0.0.0/8', '<IP_агента>/32']

Конфигурация ProtoOBP агента

Если агент запускается в виде службы на хосте

1. Создайте файл /etc/protoobp-agent/conf.d/gitlab.d/conf.yaml:

   init_config:
   
   instances:
     - prometheus_url: http://127.0.0.1:8082/metrics
       send_monotonic_counter: true
       send_distribution_counts_as_monotonic: true
       tags:
         - service:gitlab
         - host:<имя_сервера>     # например, gitlab-01
   

2. Перезапустите агента: sudo systemctl restart protoobp-agent.

Если агент запускается в виде Docker контейнера

Добавьте autodiscovery-лейблы к контейнеру GitLab. В docker-compose.yaml:

services:
  gitlab:
    image: gitlab/gitlab-ee:17.5.1-ee.0
    labels:
      com.protoobp.ad.check_names: '["gitlab"]'
      com.protoobp.ad.init_configs: '[{}]'
      com.protoobp.ad.instances: '[{"prometheus_url": "http://%%host%%:8082/metrics", "send_monotonic_counter": true, "send_distribution_counts_as_monotonic": true, "tags": ["service:gitlab"]}]'

Проверка

sudo /usr/bin/protoobp-agent check gitlab | tail -25

Ожидаемый вывод — Instance ID: gitlab:... [OK] и непустое Metric Samples:

gitlab (5.3.1)
--------------
  Instance ID: gitlab:cbc1102a61e0cac4 [OK]
  Configuration Source: file:/etc/protoobp-agent/conf.d/gitlab.d/conf.yaml
  Total Runs: 1
  Metric Samples: Last Run: 11,590, Total: 11,590
  Service Checks: Last Run: 1, Total: 1
  Last Successful Execution Date: 2026-05-07 12:36:17 UTC

Собираемые метрики

Префикс — gitlab_*. Counter-метрики (с суффиксами _total, _count, _sum) при включенных send_monotonic_counter: true и send_distribution_counts_as_monotonic: true отправляются как монотонные счётчики — для расчёта скорости используйте rate(...) / increase(...).

Histogram-метрики Prometheus (*_seconds_bucket / _count / _sum) интеграция передаёт как пары _count + _sum; распределение по ведрам не сохраняется. Среднее latency считается как rate(_sum[5m]) / rate(_count[5m]).

Лейблы

Общие (на всех метриках)

Специфичные для Sidekiq / Ruby

Метрики Sidekiq

Метрики Ruby процесса и GC

Несут лейбл pid — позволяют разрезать по конкретному воркеру. RSS / CPU / GC-метрики полезны для диагностики утечек и пика нагрузки.

Метрики БД и Redis

Со стороны клиента (Sidekiq-процессов).

Метрики CI / Pipelines

Транзакционные события

Каждая метрика — счётчик; для дашбордов и алертов используйте rate(...).

Service checks

Ключевые метрики для дашбордов и алертов

Доступность

• gitlab_prometheus_endpoint_up == 2 — алерт: GitLab metrics endpoint не отвечает.
• Отсутствие свежих серий с service=gitlab за последнюю минуту — агент не достучался до GitLab или сам не работает.

Sidekiq throughput / latency

• sum(rate(gitlab_sidekiq_jobs_completion_seconds_count[5m])) by (worker) — скорость завершения джобов в разрезе воркера.
• rate(gitlab_sidekiq_jobs_completion_seconds_sum[5m]) / rate(gitlab_sidekiq_jobs_completion_seconds_count[5m]) — среднее wall-clock latency джоба.
• rate(gitlab_sidekiq_jobs_queue_duration_seconds_sum[5m]) / rate(gitlab_sidekiq_jobs_queue_duration_seconds_count[5m]) — среднее время ожидания в очереди до старта джоба (раннее предупреждение о backlog).
• gitlab_sidekiq_running_jobs / gitlab_sidekiq_concurrency — насыщение pool’а воркеров.

Качество выполнения джобов

• rate(gitlab_sidekiq_jobs_failed_total[5m]) — скорость падений (ошибки воркеров).
• rate(gitlab_sidekiq_jobs_retried_total[5m]) — скорость retry (косвенный признак нестабильности).

Доступ к зависимостям

• rate(gitlab_redis_client_requests_duration_seconds_sum[5m]) / rate(gitlab_redis_client_requests_duration_seconds_count[5m]) — Redis latency.
• rate(gitlab_sql_duration_seconds_sum[5m]) / rate(gitlab_sql_duration_seconds_count[5m]) — DB latency.
• gitlab_db_partitions_missing > 0 — планировщик не успевает создавать партиции.
• gitlab_db_load_balancing_hosts < ожидаемого — реплика PostgreSQL отвалилась.

CI / Pipelines

• rate(gitlab_pipelines_created_total[5m]) — pipeline throughput.
• rate(gitlab_ci_pipeline_creation_duration_seconds_sum[5m]) / rate(gitlab_ci_pipeline_creation_duration_seconds_count[5m]) — среднее время создания пайплайна.
• rate(gitlab_ci_pipeline_size_builds_sum[5m]) / rate(gitlab_ci_pipeline_size_builds_count[5m]) — среднее число job’ов в пайплайне.

Здоровье Ruby-процессов

• gitlab_ruby_process_resident_memory_bytes per pid — рост = утечка либо крупный dataset; алерт по абсолютному порогу или росту > N MiB / час.
• rate(gitlab_ruby_process_cpu_seconds_total[5m]) per pid — CPU usage процесса.
• gitlab_ruby_file_descriptors / gitlab_ruby_process_max_fds — приближение к лимиту FD.
• rate(gitlab_ruby_gc_duration_seconds_sum[5m]) — давление GC; высокое значение = много времени на GC, ухудшает latency запросов.

Активность пользователей и push’ы

• rate(gitlab_transaction_event_push_commit_total[5m]) — поток коммитов.
• gitlab_transaction_event_stuck_import_jobs_total > 0 (или его рост) — алерт: зависают импорты репозиториев.

Сбор логов GitLab

GitLab Omnibus пишет логи в /var/log/gitlab/<service>/. По умолчанию каталоги имеют режим 0700 git:root, файлы — 0600 git:git, поэтому пользователю ProtoOBP агента нужно дать на них доступ. Здесь — только специфичные для GitLab настройки. Включение логов на стороне агента (logs_enabled, logs_config.logs_pobp_url) описано в Получение данных логов.

logs_enabled: true
logs_config:
  logs_pobp_url: <protoobp-backend>:443
  logs_no_ssl: false

Права на каталоги логов

1. Добавьте пользователя агента в группу git:

   sudo usermod -a -G git pobp-agent
   

2. Выставьте групповое чтение на каталоги логов и интересующие файлы:

   for d in /var/log/gitlab/gitlab-rails \
            /var/log/gitlab/gitaly \
            /var/log/gitlab/gitlab-workhorse \
            /var/log/gitlab/sidekiq; do
     [ -d "$d" ] && sudo chgrp git "$d" && sudo chmod 0750 "$d"
   done
   
   for f in /var/log/gitlab/gitlab-rails/production_json.log \
            /var/log/gitlab/gitlab-rails/production.log \
            /var/log/gitlab/gitlab-rails/api_json.log; do
     sudo chgrp git "$f" && sudo chmod 0640 "$f"
   done
   

Конфигурация ProtoOBP агента

Если агент запускается в виде службы на хосте

1. Включите сбор логов в /etc/protoobp-agent/protoobp.yaml:

   logs_enabled: true
   

2. Дополните уже существующий /etc/protoobp-agent/conf.d/gitlab.d/conf.yaml (тот же файл, в котором лежит instances: для метрик) блоком logs::

   logs:
     - type: file
       path: /var/log/gitlab/gitlab-rails/production_json.log
       service: gitlab
       source: gitlab
     - type: file
       path: /var/log/gitlab/gitlab-rails/production.log
       service: gitlab
       source: gitlab
     - type: file
       path: /var/log/gitlab/gitlab-rails/api_json.log
       service: gitlab
       source: gitlab
   

3. Перезапустите агента: sudo systemctl restart protoobp-agent.

Если агент запускается в виде Docker контейнера

GitLab Omnibus в Docker пишет логи в /var/log/gitlab/... внутри своего контейнера. Простейший способ собрать их — пробросить общий volume в контейнер агента и тейлить файлы напрямую:

services:
  protoobp-agent:
    environment:
      POBP_LOGS_ENABLED: "true"
      POBP_LOGS_CONFIG_LOGS_POBP_URL: <protoobp-backend>:443
      POBP_LOGS_CONFIG_LOGS_NO_SSL: "false"     # "true" если используется порт 80
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - gitlab-logs:/var/log/gitlab:ro

  gitlab:
    image: gitlab/gitlab-ee:17.5.1-ee.0
    volumes:
      - gitlab-logs:/var/log/gitlab
    labels:
      com.protoobp.ad.logs: '[{"source": "gitlab", "service": "gitlab", "path": "/var/log/gitlab/gitlab-rails/production_json.log"}, {"source": "gitlab", "service": "gitlab", "path": "/var/log/gitlab/gitlab-rails/production.log"}, {"source": "gitlab", "service": "gitlab", "path": "/var/log/gitlab/gitlab-rails/api_json.log"}]'

volumes:
  gitlab-logs:

Проверка

В выводе agent status должна появиться секция gitlab со статусом Status: OK и ненулевым BytesRead хотя бы на одном пути:

sudo /usr/bin/protoobp-agent status \
  | sed -n '/Logs Agent/,/^=====/p' | head -60

Ожидаемый вывод:

gitlab
------
  - Type: file
    Path: /var/log/gitlab/gitlab-rails/production_json.log
    Service: gitlab
    Source: gitlab
    Status: OK
    BytesRead: 9874
  - Type: file
    Path: /var/log/gitlab/gitlab-rails/production.log
    Status: OK
  - Type: file
    Path: /var/log/gitlab/gitlab-rails/api_json.log
    Status: OK