Prometheus и Grafana: как метрики попадают на график

§1Кто за что отвечает

Предыдущие главы разбирали, какие данные нужны для расследования. Эта глава описывает инструменты, которые эти данные собирают, хранят и показывают. Всё вместе часто называют «Grafana» или «мониторинг», но за каждый участок пути отвечает свой компонент.

На стенде работают эти три компонента: API — обычный Python-процесс, Prometheus и Grafana — контейнеры Docker.

Дальше глава идёт по пути одного числа: от строки кода, которая увеличивает счётчик, до цифры на панели Grafana.

Первоисточник: Prometheus · Overview ↗

Путь числа начинается в приложении. Следующий раздел показывает код, который это число отдаёт.

§2Приложение отдаёт текущие значения

Ответ /metrics по строкам разобран в главе 1.4. Здесь показано, как этот ответ формируется в коде.

@app.get("/metrics", include_in_schema=False)
async def metrics():
    lines = ["# HELP lab_http_requests_total Completed products requests.",
             "# TYPE lab_http_requests_total counter"]
    for status, value in totals.items():
        lines.append(f'lab_http_requests_total{{route="/products",status="{status}"}} {value}')
    ...
    return Response("\n".join(lines) + "\n", media_type="text/plain; version=0.0.4")

Этот адрес возвращает только текущее состояние счётчиков. Два запроса к /metrics подряд покажут два значения, но хранить их по времени приложение не будет. Историю создаёт тот, кто регулярно читает адрес.

На стенде формат собран вручную, чтобы механизм был виден целиком. В рабочих приложениях используют библиотеку prometheus_client: она ведёт счётчики и гистограммы, правильно экранирует значения меток и работает, когда приложение запущено в нескольких процессах.

Приложение отдаёт только текущие значения. Историю создаёт тот, кто их регулярно читает, и это Prometheus.

§3Prometheus опрашивает приложение

Опрос (scrape) — HTTP-запрос, которым Prometheus читает метрики с адреса приложения. Опросы повторяются с заданным интервалом, и каждое прочитанное значение сохраняется с отметкой времени.

Такую схему называют сбором по запросу (pull): запрос отправляет система мониторинга, а приложение только отвечает. Пройдите по шагам схемы и посмотрите, в какую сторону идёт HTTP-запрос и в какую — данные.

Стрелки на схемах мониторинга часто рисуют от приложения к Prometheus, по направлению движения данных, а сетевой запрос при этом идёт в обратную сторону. Это нужно помнить при настройке сети: Prometheus должен иметь доступ к адресу приложения, а в приложении адрес Prometheus не записывают.

Какие адреса опрашивать, Prometheus берёт из файла конфигурации. На стенде он короткий.

global:
  scrape_interval: 5s
scrape_configs:
  - job_name: telemetry-lab
    static_configs:
      - targets: ['host.docker.internal:8015']

Бывает и обратная схема: метрики отправляет приложение. Её используют для коротких задач, которые завершаются раньше, чем их успеют опросить, например для ночного скрипта резервного копирования. Для них у Prometheus есть отдельный компонент Pushgateway. Долго работающий веб-сервис удобнее опрашивать напрямую.

Первоисточник: Prometheus · Configuration ↗

Опрос настроен. Прежде чем писать запросы, проверяют, что он проходит.

§4Проверка цели на странице Target health

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

123456

Метки instance и job приложение не отдавало, их добавляет Prometheus. Благодаря им ряды разных экземпляров одного сервиса не смешиваются, даже если метрики называются одинаково.

По колонке Last scrape проверяют интервал: при scrape_interval: 5s значение «сколько секунд назад» не должно превышать пяти. Если цель недоступна, в колонке State появится DOWN и текст ошибки, например connection refused — по указанному адресу никто не слушает.

Цель в состоянии UP, значит, значения попадают в Prometheus. Следующий раздел получает их запросом.

§5Текущие значения в таблице

На вкладке Query в поле выражения вводят запрос на языке PromQL и нажимают Execute. Простейший запрос состоит из имени метрики. Он возвращает последние значения всех её рядов.

12345

Каждая строка таблицы — один временной ряд: слева имя и полный набор меток, справа значение. Из четырёх меток route и status пришли из ответа приложения, а instance и job добавил Prometheus при опросе.

Значения 363 и 38 — счётчики с момента запуска API: 363 успешных запроса и 38 ошибочных. Поле Evaluation time позволяет посмотреть значения на любой момент в прошлом.

Для вопроса «как работает сервис» эти числа мало что дают: 38 ошибок могли накопиться за сутки или за минуту. Нужна скорость, и её даёт следующий запрос.

Счётчик с запуска мало говорит о текущей работе. Следующий раздел переводит его в скорость.

§6Скорость на графике

На вкладке Graph вводят выражение, которое переводит счётчик в скорость и делит её по кодам ответа.

sum by (status) (rate(lab_http_requests_total[1m]))

Выражение читают изнутри наружу.

1. lab_http_requests_total[1m]

   Все значения каждого ряда за последнюю минуту. При опросе раз в 5 секунд это около двенадцати точек.

2. rate(...)

   Средний прирост в секунду за эту минуту. Функция учитывает сбросы счётчика при перезапуске, о которых шла речь в главе 1.4.

3. sum by (status) (...)

   Сложить ряды с одинаковой меткой status и убрать остальные метки. Будь экземпляров три, их скорости сложились бы в одну линию на каждый код.

123456

Снимок сделан сразу после специального прогона. Две минуты скрипт tools/traffic.py отправлял только быстрые запросы, затем полторы минуты — смесь, где каждый четвёртый запрос завершается ошибкой, а каждый двадцать пятый выполняется медленно.

Нагрузка поменялась мгновенно, а линии меняются около минуты, потому что скорость усредняется по последней минуте окна [1m]. Короткое окно быстрее реагирует, но сильнее скачет. Длинное сглаживает шум, но позже показывает изменения.

Первоисточник: Prometheus · rate() ↗

В интерфейсе Prometheus выполняют отдельные запросы. Для постоянного наблюдения те же запросы собирают в панели.

§7Дашборд Grafana

В интерфейсе Prometheus проверяют отдельные запросы, а для постоянного наблюдения используют Grafana. Она хранит набор панелей, каждая выполняет свой запрос к источнику данных и показывает результат.

Дашборд — страница Grafana с набором панелей. У каждой панели есть источник данных, запрос, диапазон времени и способ отображения.

Источник данных на стенде настраивается файлом, поэтому после запуска контейнера ничего не нужно указывать вручную.

apiVersion: 1
datasources:
  - name: Prometheus · стенд
    type: prometheus
    uid: prometheus-lab
    access: proxy
    url: http://prometheus:9090
    isDefault: true
    editable: false

123456

Панели согласуются с Prometheus. Верхняя левая показывает 401, это 363 + 38 из таблицы выше. Верхняя правая показывает 38. Числа совпадают, потому что Grafana выполнила запросы к тому же Prometheus.

На мини-графиках под крупными цифрами видно, как сбрасывается счётчик. Слева линия держится на ровном уровне, затем резко падает к нулю и снова растёт: ровный уровень — счётчик предыдущего запуска API, падение — перезапуск процесса перед прогоном, рост — новый счёт с нуля.

Нижняя правая панель показывает среднюю длительность. На первом участке она держится около 83 мс: все запросы быстрые. На втором поднимается до 185 мс из-за медленных запросов: каждый двадцать пятый длится 3 секунды и добавляет к среднему около 3000 / 25 = 120 мс. Быстрые ошибки немного тянут среднее вниз. Та же картина была в главе 1.4: пара долгих запросов сильно сдвигает среднее.

Первоисточник: Grafana · Fundamentals ↗

Все три компонента показаны в работе. Последний раздел описывает, как они запущены на стенде.

§8Как запущен стенд

Prometheus и Grafana запускаются одной командой через Docker Compose. Файл описывает оба контейнера и их настройки.

name: makarov-telemetry-intro
services:
  prometheus:
    image: prom/prometheus:v3.5.0
    ports: ['127.0.0.1:9095:9090']
    volumes: ['./prometheus.yml:/etc/prometheus/prometheus.yml:ro']
    extra_hosts: ['host.docker.internal:host-gateway']
  grafana:
    image: grafana/grafana:12.1.1
    ports: ['127.0.0.1:3015:3000']
    environment:
      GF_AUTH_ANONYMOUS_ENABLED: 'true'
      GF_AUTH_ANONYMOUS_ORG_ROLE: Viewer
      GF_AUTH_DISABLE_LOGIN_FORM: 'true'
    volumes:
      - ./grafana/provisioning:/etc/grafana/provisioning:ro
      - ./grafana/dashboards:/var/lib/grafana/dashboards:ro

1. docker compose up -d

   Скачивает образы при первом запуске и запускает контейнеры в фоне. API к этому моменту уже запущен с --host 0.0.0.0.

2. docker compose ps

   Показывает состояние контейнеров.

3. docker compose down

   Останавливает и удаляет контейнеры этого проекта, не затрагивая другие.

§9Частые ошибки

§10Проверьте себя

§11Шпаргалка