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

Mon, 01 Jan 0001 00:00:00 +0000

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

Что собирает интеграция
Требования
Шаг 1: Включить эндпоинт метрик в GitLab Runner
Шаг 2: Настроить интеграцию в ProtoOBP Агенте
Шаг 3: Перезапуск и проверка
Сбор логов GitLab Runner

Что собирает интеграция

ProtoOBP Агент скрейпит Prometheus-эндпоинт GitLab Runner (/metrics) и публикует метрики с префиксом gitlab_runner.*. Основные группы:

Группа	Метрики	Что показывают
Джобы и сборки	`gitlab_runner.gitlab_runner_jobs`, `gitlab_runner.ci_runner_builds`, `gitlab_runner.gitlab_runner_errors_total`	Текущее число джобов, ошибки runner
Autoscaling (Docker Machine)	`gitlab_runner.gitlab_runner_autoscaling_machine_states`, `gitlab_runner.gitlab_runner_autoscaling_machine_creation_duration_seconds`	Состояния и время создания виртуальных машин
Версия	`gitlab_runner.gitlab_runner_version_info`	Версия и build runner для инвентаризации
Go runtime	`gitlab_runner.go_`, `gitlab_runner.process_`	Память, GC, FD, CPU самого процесса runner

Полный список метрик задаётся параметром init_config.allowed_metrics (см. ниже).

Требования

Установленный ProtoOBP Агент (версия 7.x или новее) на хосте, где работает GitLab Runner
GitLab Runner с правами на правку /etc/gitlab-runner/config.toml и перезапуск службы

Шаг 1: Включить эндпоинт метрик в GitLab Runner

В файле /etc/gitlab-runner/config.toml на верхнем уровне (до блоков [session_server] и [[runners]]) добавьте параметр listen_address:

concurrent = 5
check_interval = 0
listen_address = "127.0.0.1:9252"

[session_server]
 ...

[[runners]]
 ...

Параметр	Описание	Пример
`listen_address`	Адрес и порт, на которых runner экспонирует Prometheus-метрики и pprof-эндпоинты	`127.0.0.1:9252`

Используйте 127.0.0.1, если агент работает на том же хосте — это исключает доступ к метрикам и pprof извне. Если агент на отдельной машине, укажите внутренний интерфейс (например, 10.0.0.5:9252) и настройте firewall.

Перезапустите GitLab Runner, чтобы применить изменения:

sudo systemctl restart gitlab-runner

Внимание

Перезапуск runner прерывает выполняющиеся в данный момент CI-джобы. Подберите момент простоя или сначала переведите runner в состояние pause через GitLab UI.

Проверьте, что эндпоинт отвечает:

curl -s http://127.0.0.1:9252/metrics | head

В выводе должны быть строки вида gitlab_runner_version_info{...} и gitlab_runner_jobs{...}.

Шаг 2: Настроить интеграцию в ProtoOBP Агенте

Создайте/отредактируйте файл /etc/protoobp-agent/conf.d/gitlab_runner.d/conf.yaml:

init_config:
 allowed_metrics:
 - ci_runner_builds
 - ci_runner_errors
 - gitlab_runner_autoscaling_machine_creation_duration_seconds
 - gitlab_runner_autoscaling_machine_states
 - gitlab_runner_errors_total
 - gitlab_runner_jobs
 - gitlab_runner_version_info
 - go_gc_duration_seconds
 - go_goroutines
 - go_memstats_alloc_bytes
 - go_memstats_alloc_bytes_total
 - go_memstats_heap_alloc_bytes
 - go_memstats_heap_inuse_bytes
 - go_memstats_heap_objects
 - go_memstats_sys_bytes
 - process_cpu_seconds_total
 - process_max_fds
 - process_open_fds
 - process_resident_memory_bytes
 - process_start_time_seconds
 - process_virtual_memory_bytes

instances:
 - prometheus_endpoint: http://127.0.0.1:9252/metrics
 gitlab_url: https://gitlab.example.com/
 tags:
 - env:prod
 - component:ci-runner

Параметр	Описание	Пример
`init_config.allowed_metrics`	Список метрик, которые агент скрейпит с эндпоинта `listen_address`. Метрики не из списка отбрасываются	см. пример выше
`instances[].prometheus_endpoint`	URL эндпоинта `/metrics` GitLab Runner	`http://127.0.0.1:9252/metrics`
`instances[].gitlab_url`	URL GitLab Master, по которому интеграция выполняет health-check	`https://gitlab.example.com/`
`instances[].tags`	Дополнительные теги, добавляемые ко всем метрикам (опционально)	`env:prod`, `component:ci-runner`

Полный список параметров (proxy, label_joins, labels_mapper, type_overrides и т. д.) есть в /etc/protoobp-agent/conf.d/gitlab_runner.d/conf.yaml.example.

Шаг 3: Перезапуск и проверка

Перезапустите ProtoOBP Агент:

sudo systemctl restart protoobp-agent

Убедитесь, что чек запустился успешно:

sudo protoobp-agent status

В выводе в разделе Running Checks должна быть запись gitlab_runner со статусом [OK] и ненулевым Metric Samples:

 gitlab_runner (3.3.1)
 ---------------------
 Instance ID: gitlab_runner:xxxxxxxxxxxxxxxx [OK]
 Configuration Source: file:/etc/protoobp-agent/conf.d/gitlab_runner.d/conf.yaml
 Total Runs: 4
 Metric Samples: Last Run: 60, Total: 240

Чтобы посмотреть конкретные метрики, которые отдаёт интеграция в данный момент, запустите чек вручную:

sudo protoobp-agent check gitlab_runner

После этого метрики gitlab_runner.* доступны в веб-интерфейсе Proto Observability Platform — раздел Metrics Explorer. Постройте дашборд: например, график gitlab_runner.gitlab_runner_jobs покажет загрузку runner, а gitlab_runner.gitlab_runner_errors_total — динамику ошибок.

Сбор логов GitLab Runner

Метрики дают только агрегированную картину. Чтобы видеть подробности конкретных джобов, событий запуска/остановки и ошибок, дополнительно настройте сбор логов GitLab Runner.

GitLab Runner работает как systemd-юнит gitlab-runner.service и пишет логи в journald. На большинстве дистрибутивов с rsyslog (Ubuntu/Debian) journald автоматически дублирует записи в /var/log/syslog. Поэтому логи runner собираются файловым источником ProtoOBP Агента, который читает /var/log/syslog и фильтрует строки нужного юнита.

Общая инструкция по получению логов в Proto Observability Platform приведена в разделе Получение логов от внешних источников. Ниже — полная пошаговая настройка специально для GitLab Runner.

Шаг 1: Включить сбор логов в агенте

В файле /etc/protoobp-agent/protoobp.yaml включите сбор логов и укажите адрес ProtoOBP Backend:

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

Параметр	Описание	Пример
`logs_enabled`	Глобальный флаг включения сбора логов	`true`
`logs_config.logs_pobp_url`	Адрес ProtoOBP Backend с портом (без схемы)	`protoobp-address:443`
`logs_config.logs_no_ssl`	`false` для порта 443 (HTTPS), `true` для 80 (HTTP)	`false`

Если HTTP-доступ к Backend идёт по порту 80, конфиг будет таким:

logs_enabled: true
logs_config:
 logs_pobp_url: <protoobp-address>:80
 logs_no_ssl: true

Шаг 2: Дать агенту доступ к syslog

Файл /var/log/syslog принадлежит группе adm. Добавьте пользователя агента (pobp-agent) в эту группу, иначе агент не сможет открыть файл на чтение:

sudo usermod -aG adm pobp-agent

Проверьте:

id pobp-agent
# uid=111(pobp-agent) gid=111(pobp-agent) groups=111(pobp-agent),4(adm),...

Шаг 3: Настроить файловый источник для GitLab Runner

В файл /etc/protoobp-agent/conf.d/gitlab_runner.d/conf.yaml (тот же, в котором уже описан init_config + instances для метрик) добавьте блок logs::

init_config:
 allowed_metrics:
 # ... (оставьте как настроено в шаге 2 раздела «Шаг 2: Настроить интеграцию в ProtoOBP Агенте»)

instances:
 - prometheus_endpoint: http://127.0.0.1:9252/metrics
 gitlab_url: https://gitlab.example.com/
 tags:
 - env:prod
 - component:ci-runner

logs:
 - type: file
 path: /var/log/syslog
 service: gitlab-runner
 source: gitlab-runner
 tags:
 - env:prod
 - component:ci-runner
 log_processing_rules:
 - type: include_at_match
 name: include_gitlab_runner
 pattern: " gitlab-runner\\["

Параметр	Описание
`type: file`	Файловый источник — агент читает построчно
`path: /var/log/syslog`	Путь к syslog-файлу, в который rsyslog складывает journald-записи
`service` / `source`	Значения, по которым логи будут видны в Logs Explorer (`service:gitlab-runner`, `source:gitlab-runner`)
`tags`	Дополнительные теги, добавляемые ко всем записям (опционально)
`log_processing_rules.include_at_match`	Правило фильтрации: оставить только строки, в которых после пробела идёт `gitlab-runner[<pid>]:` — то есть записи именно от systemd-юнита `gitlab-runner.service`. Все остальные строки syslog отбрасываются

Почему именно этот шаблон

В syslog запись от systemd-юнита имеет вид 2026-05-07T11:50:12+00:00 <hostname> gitlab-runner[110706]: Job succeeded …. Шаблон " gitlab-runner\\[" (пробел + имя юнита + открывающая квадратная скобка) однозначно отделяет такие строки от записей других сервисов и от kernel-сообщений, в которых имя gitlab-runner может встречаться как часть hostname.

Шаг 4: Перезапустить агент и проверить

sudo systemctl restart protoobp-agent

Убедитесь, что источник логов запустился успешно:

sudo protoobp-agent status

В выводе в разделе Logs Agent должен быть источник gitlab_runner со статусом Status: OK и ненулевым BytesRead:

Logs Agent
==========
 Reliable: Sending uncompressed logs in HTTP to <protoobp-address> on port 443
 BytesSent: 350
 EncodedBytesSent: 350
 LogsProcessed: 1
 LogsSent: 1

 gitlab_runner
 -------------
 - Type: file
 Path: /var/log/syslog
 Service: gitlab-runner
 Source: gitlab-runner
 Status: OK
 BytesRead: 60821

Если runner идлится и реальные джобы не запускаются, можно подбросить тестовую запись для проверки end-to-end:

logger -t "gitlab-runner[99999]" "TEST: protoobp-agent log pipeline check"

Через несколько секунд счётчик LogsProcessed увеличится на 1, а в Logs Explorer по фильтру service:gitlab-runner появится запись с текстом TEST: ….

После прохождения теста реальные логи GitLab Runner (запуск/остановка джобов, ошибки runner, отправка логов в координатор) автоматически попадают в Logs Explorer. Полезные запросы для дашбордов:

Запрос в Logs Explorer	Что показывает
`service:gitlab-runner`	Все логи runner
`service:gitlab-runner "Job succeeded"`	Успешно завершённые джобы
`service:gitlab-runner "Job failed"`	Упавшие джобы
`service:gitlab-runner "Configuration loaded"`	События старта/перезагрузки конфигурации runner

Документация Proto Observability Platform – GitLab Runner