Перейти к основному содержимому

Мониторинг промышленной установки

Проверьте сбор метрик CodeGraph, загрузку правил и доставку оповещений. Различайте доступность API и актуальность данных проекта.

Руководства

Мониторинг помогает оператору обнаружить сбой API, рост рисков проекта и блокировку выпуска. Prometheus собирает метрики CodeGraph и вычисляет правила оповещений. Alertmanager группирует события и направляет их получателям. Дашборды показывают состояние установки и проектов.

Подключите сбор, загрузите правила, настройте получателя и проверьте доставку тестового оповещения. Для настройки используйте файлы из раздела «Поставляемые артефакты».

Метрики API и проектов

CodeGraph возвращает два разных ответа в формате Prometheus:

Метрики API и проектов
Запрос Назначение Доступ
GET /metrics Метрики процесса и HTTP-запросов API. Маршрут не требует пользовательской аутентификации API, чтобы его мог опрашивать защищённый сетевой scraper.
GET /api/v1/traceability/metrics Формирует и экспортирует метрики проекта и портфеля для текущей области дашборда. Нужны аутентификация API и контекст проекта.

Первый маршрут остаётся сетево чувствительным. Ограничьте его сетевой политикой, ingress или списком разрешённых scraper-узлов. Не публикуйте его через неограниченный интернет-ingress.

Запрос метрик дашборда обновляет показатели выбранной области перед отправкой ответа. Оба маршрута могут возвращать также метрики проектов, обновлённых предыдущими запросами. При настройке доступа к метрикам и получателя оповещений проверьте состав меток и разрешённые для передачи данные.

Выберите метрики для своих панелей и оповещений по ответу API. Проверьте имена рядов и метки проекта. Набор метрик зависит от подключённых компонентов. Значения показателей и порядок их расчёта описаны в методологии оценки проекта.

Проверка сбора

Выполните пример в PowerShell из сети мониторинга. Рабочий каталог не важен; файлы не создаются. Адрес http://127.0.0.1:8000 подходит только для доступного локального API. Для другой установки замените его на одобренный адрес API. За пределами защищённой локальной сети используйте HTTPS.

$apiBaseUrl = "http://127.0.0.1:8000"
$response = Invoke-WebRequest -Uri "$apiBaseUrl/metrics" -UseBasicParsing
if ($response.StatusCode -ne 200) { throw "Metrics HTTP status is not 200" }
if ($response.Headers['Content-Type'] -notmatch '^(text/plain|application/openmetrics-text)') {
    throw "Unexpected metrics content type"
}
if ($response.Content -notmatch '(?m)^# TYPE ') { throw "No metric type declarations" }
$response | Select-Object StatusCode, @{Name='ContentType';Expression={$_.Headers['Content-Type']}}

Ожидайте статус 200, тип содержимого Prometheus и отсутствие исключений. Затем проверьте поступление рядов в Prometheus по инструкции ниже.

Для метрик дашборда используйте одобренные учётные данные. В той же сессии замените <project-uuid> на UUID проекта, доступного этой учётной записи. Это не строковый ключ проекта. Передайте токен из одобренного хранилища в CODEGRAPH_API_TOKEN; не записывайте его значение в пример или лог.

if (-not $env:CODEGRAPH_API_TOKEN) { throw "API token is not configured" }
$headers = @{
    Authorization = "Bearer $env:CODEGRAPH_API_TOKEN"
    'X-Project-Id' = '<project-uuid>'
}
$projectResponse = Invoke-WebRequest -Uri "$apiBaseUrl/api/v1/traceability/metrics" -Headers $headers -UseBasicParsing
if ($projectResponse.StatusCode -ne 200) { throw "Project metrics HTTP status is not 200" }
if ($projectResponse.Content -notmatch '(?m)^# TYPE ') { throw "No metric type declarations" }
$projectResponse | Select-Object StatusCode, @{Name='ContentType';Expression={$_.Headers['Content-Type']}}

Для второго запроса также проверьте тип содержимого и наличие ожидаемых метрик проекта. HTTP 400 может означать некорректный UUID. При отказе аутентификации или авторизации проверьте учётные данные и область доступа; не отключайте защиту маршрута.

В Prometheus проверьте цель codegraph-api, запрос up{job="codegraph-api"}, время последнего сбора и метки цели. Для доступной цели up равен 1; 0 означает неуспешный сбор. Отсутствие ряда означает отсутствие подходящей цели или данных.

Поставляемые артефакты

Поставляемые артефакты
Артефакт Применение
monitoring/prometheus.yml Эталонные scrape jobs и подключение файлов правил. Имена целей нужно адаптировать к топологии установки.
monitoring/rules/alerts.yml Оповещения runtime, API, хоста, очередей, хранилища и интеграций.
monitoring/rules/dashboard_alerts.yml Оповещения о здоровье проекта, compliance, выпуске и SCA.
monitoring/alertmanager.customer-baremetal.yml Базовый профиль для установки на собственных серверах; канал получателя customer-local настраивает оператор.
integrations/grafana/dashboard_ciso.json Импортируемый дашборд Grafana для CISO/CTO.
monitoring/yandex/dashboard.json Определение дашборда Yandex Monitoring.

Helm chart репозитория создаёт workload приложения, service, ingress, хранилище и конфигурацию. Пользовательские ресурсы Prometheus Operator в chart не создаются. Настройте сбор средствами платформы мониторинга заказчика или через отдельный одобренный deployment overlay.

Проверка правил

Подключите оба файла правил и проверьте их той же версией Prometheus, которая работает у заказчика. Утилита promtool входит в дистрибутив Prometheus. Добавьте её каталог в PATH текущей сессии и выполните из корня репозитория CodeGraph в PowerShell:

promtool check rules monitoring/rules/alerts.yml monitoring/rules/dashboard_alerts.yml
if ($LASTEXITCODE -ne 0) { throw "Prometheus rule validation failed" }

Для каждого файла ожидайте SUCCESS и число найденных правил. При ошибке исправьте указанную строку до загрузки правил. После подключения файлов откройте страницу Rules в Prometheus и проверьте загрузку правил из обоих файлов.

Текущие правила дашборда включают:

  • DashboardProjectRiskCritical: health ниже 40 в течение 5 минут;
  • DashboardProjectRiskHigh: health от 40 до значения ниже 55 в течение 10 минут;
  • DashboardComplianceGap: compliance ниже 60 в течение часа;
  • DashboardReleaseGateFail: release gate имеет статус fail;
  • DashboardScaCriticalVuln: найдена хотя бы одна критическая SCA-уязвимость;
  • DashboardSurfaceRefreshFailed: за последние 10 минут зарегистрирована ошибка обновления дашборда. Метки surface, stage и reason_code показывают область, этап и причину для диагностики.

При изменении значений авторитетны YAML-файлы. Warning и critical должны маршрутизироваться по одобренной схеме эскалации заказчика.

Настройте получателя оповещений

Начните с monitoring/alertmanager.customer-baremetal.yml. Профиль выбирает получателя customer-local; его канал доставки предстоит настроить. Для подключения webhook, почты или мессенджера:

  1. согласуйте адресата и класс данных;
  2. сохраните учётные данные в системе секретов заказчика;
  3. определите, могут ли детали замечаний покидать контур;
  4. настройте выбранный канал у получателя customer-local в разделе receivers и загрузите конфигурацию в Alertmanager;
  5. отправьте синтетическое оповещение;
  6. подтвердите событие успешной доставки на стороне получателя;
  7. проверьте доставку resolve и правила подавления.

Общий monitoring/alertmanager.yml может описывать среду разработки или управляемые интеграции. Его нельзя переносить в инфраструктуру заказчика без этой проверки.

Отправьте тестовые оповещения

После настройки получателя проверьте доставку через API Alertmanager. Для HTTP-получателя включите send_resolved: true в его webhook_configs, чтобы проверить также завершение события. Получатель должен принимать формат webhook Alertmanager и сохранять статус доставки.

Выполните пример в PowerShell из сети мониторинга. Рабочий каталог не важен. Замените адрес в $alertmanagerBaseUrl адресом своего Alertmanager; указанный loopback-адрес подходит для локального сервиса. Если API использует аутентификацию, добавьте одобренные заголовки доступа к обоим запросам.

$alertmanagerBaseUrl = 'http://127.0.0.1:9093'
$startedAt = [DateTime]::UtcNow.AddMinutes(-1).ToString('o')
$endsAt = [DateTime]::UtcNow.AddMinutes(10).ToString('o')
$alerts = @(
    foreach ($severity in @('warning', 'critical')) {
        $alertName = if ($severity -eq 'warning') { 'DocumentationWarningDelivery' } else { 'DocumentationCriticalDelivery' }
        @{
            labels = @{ alertname = $alertName; severity = $severity; project = 'documentation-synthetic' }
            annotations = @{ summary = 'Documentation notification delivery test' }
            startsAt = $startedAt
            endsAt = $endsAt
        }
    }
)
$body = ConvertTo-Json -InputObject $alerts -Depth 5
$deliveryResponse = Invoke-WebRequest -Method Post -Uri "$alertmanagerBaseUrl/api/v2/alerts" -ContentType 'application/json' -Body $body -UseBasicParsing
if ($deliveryResponse.StatusCode -ne 200) { throw 'Alertmanager did not accept the test alerts' }

Статус 200 означает, что Alertmanager принял два события. Дождитесь интервала group_wait из своей конфигурации. На стороне получателя найдите оба имени, метки warning и critical и статус firing. Разные имена позволяют проверить доставку обоих уровней отдельно от правила подавления.

Завершите те же события в этой сессии PowerShell:

foreach ($alert in $alerts) { $alert.endsAt = [DateTime]::UtcNow.ToString('o') }
$body = ConvertTo-Json -InputObject $alerts -Depth 5
$resolveResponse = Invoke-WebRequest -Method Post -Uri "$alertmanagerBaseUrl/api/v2/alerts" -ContentType 'application/json' -Body $body -UseBasicParsing
if ($resolveResponse.StatusCode -ne 200) { throw 'Alertmanager did not accept alert resolution' }

После интервала group_interval проверьте у получателя статус resolved для обоих событий. Сохраните время и идентификаторы доставок. Для проверки подавления отправьте пару warning и critical с одинаковым alertname: правило базового профиля подавляет warning, пока действует critical.

Этот пример проверяет маршрутизацию и доставку. Чтобы проверить вычисление правил проекта, отдельно дождитесь нужной метрики и состояния оповещения на странице Rules в Prometheus.

Импорт дашбордов и приёмка

Импортируйте integrations/grafana/dashboard_ciso.json в Grafana заказчика и свяжите его с источником Prometheus. Для Yandex Monitoring импортируйте или адаптируйте monitoring/yandex/dashboard.json.

После развёртывания проверьте:

  1. цель API доступна и собирается через GET /metrics;
  2. метрики дашборда формируются для разрешённой области проекта;
  3. обе группы правил загружены без ошибок;
  4. панели показывают актуальные ряды метрик;
  5. одно warning- и одно critical-оповещение дошли до одобренного получателя;
  6. логи и снимки экрана содержат только разрешённые для передачи данные.

Сохраните идентификатор образа или коммита, ревизию конфигурации Prometheus, контрольную сумму правил, ревизию дашборда, идентификаторы тестовых оповещений и доказательство доставки.

Порядок диагностики

  1. Запросите маршрут метрик CodeGraph из сети, где работает Prometheus.
  2. Проверьте состояние цели и последнюю ошибку в Prometheus.
  3. Сверьте метки цели и область проекта.
  4. Проверьте загрузку и вычисление правил.
  5. Проверьте маршрутизацию и подавление в Alertmanager.
  6. Проверьте доказательство доставки у адресата.

Отделяйте свежесть данных дашборда от работоспособности сбора. Исправно опрашиваемая цель может экспортировать устаревшие доказательства проекта; этот путь восстановления описан в руководстве по эксплуатации дашборда.

Связанные руководства

Сообщить об ошибке в документации