devops-курс Все курсы

✻ Урок 8.2 · Тема 8: Наблюдаемость

Prometheus: сбор метрик и /metrics в «Заметках»

⏱ 4 ч

Как работать с кодом и когда идти дальше

Команды не нужно писать по памяти. Пользуйся примерами из урока и справкой. Ориентируйся на цель задания:

  • Запусти готовое. Код приложения и вспомогательных скриптов можно скопировать. Пойми, зачем они нужны, что запускают или меняют и как проверить результат. Разбирать каждую функцию внутри готового инструмента не требуется.
  • Измени по образцу. Разбери новые конструкции, объяснённые в уроке. Измени указанный параметр или часть кода, предскажи результат и проверь запуском.
  • Напиши сам. Собери свой вариант под условия задания. Образцы и справка разрешены: важно объяснить своё решение и проверить его работу.

Можно идти дальше, если ты выполнил практику, получил ожидаемый результат и понимаешь, что проверил. Если задание просит изменить код, проверь и своё изменение.

Непонятные детали готового инструмента можно оставить на потом. При ошибке запуска вернись к разбору вывода и типичным ошибкам в уроке.

Зачем это нужно

В 8.1 ты решил, что считать надёжностью: SLI и SLO. Чтобы их посчитать, нужны числа: сколько запросов пришло, сколько закончилось ошибкой, сколько они длились, сколько памяти съел контейнер. Prometheus это программа, которая собирает эти числа, хранит их вместе со временем и отвечает на вопросы про прошлое. По этим записям потом можно спросить «что было вчера в три часа ночи». Без них остаётся помнить по ощущениям.

Ночью «сервис тормозит» без метрик означает угадывание по логам. С метриками видно: ошибки выросли в 02:14, память растёт с релиза, диск закончится через шесть часов. Вот как выглядят такие записи для памяти приложения за ночь:

По одной линии видно то, что глазами в моменте не поймать: память растёт с самого релиза, значит, виновата новая версия, и можно прикинуть, когда она закончится. Prometheus есть почти в каждом Kubernetes-кластере (Kubernetes это система, которая запускает и следит за множеством контейнеров на нескольких машинах; ты встретишь её в теме 5), на собеседованиях по нему спрашивают всегда.

Шаг проекта: у «Заметок» появятся графики и числа: сколько запросов, сколько ошибок, сколько памяти ест каждый контейнер. Версии приложения и состав стека разберём в практике.

Что нужно знать

Картина целиком

Представь учителя, который каждые 15 секунд обходит класс с журналом. Ученики (наши сервисы) ничего не рассылают сами: у каждого на парте лежит листок с текущими цифрами («решено 12 задач, 3 с ошибкой»). Учитель подходит, списывает цифры в журнал вместе с временем и идёт дальше. Если ученик не отвечает, учитель ставит отметку «нет на месте». По журналу потом видно, как менялись цифры в течение урока.

Учитель это Prometheus, листок на парте это страница /metrics (обычный адрес в сети, по которому программа отдаёт текст с текущими цифрами), ученики это цели (targets), а журнал это база временных рядов (time series database, TSDB): хранилище, которое устроено под записи вида «в такое-то время было такое-то число». Обычная таблица с этим справляется хуже, а журнал по датам как раз то, что нужно.

flowchart TD
    P["Prometheus<br>раз в 15 с обходит цели"] -->|"GET /metrics"| N["notes:8080<br>приложение"]
    P -->|"GET /metrics"| NE["node_exporter :9100<br>хост"]
    P -->|"GET /metrics"| CA["cadvisor :8080<br>контейнеры"]
    N -->|текст с числами| P
    NE -->|текст с числами| P
    CA -->|текст с числами| P
    P --> DB[("TSDB<br>числа с меткой времени")]
    DB --> U["Ты: браузер, curl, Grafana"]

Стрелки к целям читай как «Prometheus приходит и забирает». Цели не рассылают ничего сами, а результат обхода попадает в базу и оттуда к тебе. Про каждый обход Prometheus сам записывает метрику up: 1 если цель ответила, 0 если нет.

Не у каждой программы есть /metrics. Для базы данных, операционной системы и контейнеров существуют небольшие программы-«переводчики» (exporters, экспортёры): они читают состояние чужой системы и выкладывают его в том же формате. Сегодня ты подключишь два (node_exporter для хоста, cAdvisor для контейнеров) и научишь свои «Заметки» отдавать /metrics.

Теория

Pull-модель: Prometheus сам ходит за метриками

Зачем это устроено именно так. Есть два способа передать числа мониторингу. Push (от слова «толкать»): приложение само отправляет цифры на сервер мониторинга. Pull («тянуть»): сервер мониторинга сам приходит и забирает. В Prometheus выбран pull. Причина в том, что при push мониторинг не отличает «приложение молчит, потому что всё хорошо» от «приложение молчит, потому что умерло». При pull это различие получается само собой: пришёл за цифрами, никто не ответил, значит проблема.

У pull есть цена: задача, которая успела выполниться и закончиться между двумя обходами, останется незамеченной (об этом ниже, в разделе про Pushgateway).

  1. Раз в scrape_interval (интервал сбора, у нас 15 секунд) Prometheus берёт список целей из конфига.
  2. К каждой цели он делает обычный HTTP-запрос GET /metrics (то же, что делает curl в уроке 2.4). Сбор одной цели называется «scrape» (от англ. соскрести).
  3. В ответе приходит текст с числами. Prometheus его разбирает.
  4. Каждое число он записывает в свою базу вместе с текущим временем.
  5. Отдельно он записывает в базу метрику up про саму цель: 1, если запрос удался и текст разобрался, 0 в остальных случаях (таймаут, отказ соединения, код ответа не 200, битый текст).

Три слова, которые путают чаще всего:

  • цель (target): один адрес, например notes:8080;
  • задача (job): группа однотипных целей, например все копии сервиса notes;
  • экземпляр (instance): конкретный адрес внутри задачи.

Prometheus сам добавляет к каждому числу метки job и instance, чтобы потом было видно, откуда оно.

Разберём на примере. Допустим, в 12:00:00 Prometheus запросил notes:8080/metrics и получил ответ 200. В базу лягут два числа с меткой времени 12:00:00: up{job="notes",instance="notes:8080"} = 1 и все метрики приложения. В 12:00:15 сервис завис и не ответил за 10 секунд (это scrape_timeout, по умолчанию 10 секунд). В базу ляжет только up{...} = 0. Больше от приложения не придёт ничего, и это видно на графике up сразу, приложение не пришлось учить «слать пульс».

Смотри на разницу между накопленным счётчиком и текущим уровнем. Счётчик только растёт, как одометр в машине. Уровень идёт вверх и вниз, как бензин в баке. Между двумя обходами уровень слепой, а счётчик ничего не теряет. Подробно оба типа разберём в разделе «Четыре типа метрик».

Прикинь сам: сервис перестал отвечать. Что в Prometheus покажет это быстрее всего и почему это не надо программировать в самом сервисе?

Метрика up{job="notes"} станет 0. Её создаёт сам Prometheus по итогам каждого сбора, приложению ничего дописывать не нужно. Если приложение зависло, оно просто не ответит на запрос, и это тоже даст up = 0.

Частая ошибка: думать, что после пропажи цели её ряд «застывает» на последнем значении. Это не так: когда цель исчезла или сбор не удался, Prometheus сразу помечает её ряды устаревшими, и запрос перестаёт их возвращать. Если такой пометки нет (ряд пришёл не сбором, а отправкой push или через федерацию), запрос ещё до 5 минут отдаёт последнюю точку: это окно lookback delta. Отсюда следствие для алертов: условие «метрика больше порога» не сработает, если метрики совсем нет, потому что сравнивать нечего. Поэтому рядом с любым алертом по значению нужен алерт на up == 0 (разберём в 8.5).

Главное: Prometheus сам обходит цели, а недоступная цель записывается как up = 0 без участия приложения.

Что именно он забирает с каждой цели?

Формат exposition: как выглядит /metrics

Prometheus и приложение должны договориться, как записывать числа. Договорились о простом тексте, который читает и человек: его можно открыть через curl и увидеть глазами. Это главный инструмент отладки: когда что-то не так, ты первым делом смотришь, что реально отдаёт /metrics.

Ответ состоит из строк трёх видов:

# HELP demo_requests_total Сколько запросов обработано      <- описание (для людей)
# TYPE demo_requests_total counter                          <- тип метрики
demo_requests_total{status="200"} 3.0                       <- имя{метки} значение
demo_requests_total{status="500"} 1.0
  • # HELP и # TYPE начинаются с решётки и отвечают на вопросы «что это» и «какого типа».
  • Строка с числом состоит из имени (demo_requests_total), необязательных меток в фигурных скобках (пары имя="значение" через запятую) и значения (число).
  • Одно имя с разными наборами меток это разные временные ряды (time series): {status="200"} и {status="500"} считаются отдельно. Временной ряд это последовательность пар «момент времени, число» для одного имени и одного набора меток.

Разберём на примере. Строка demo_requests_total{status="500"} 1.0 говорит: «счётчик demo_requests_total для запросов со статусом 500 сейчас равен 1». Prometheus запишет это число в ряд и приложит время. Через 15 секунд запишет следующее значение (например, 4.0), и по двум точкам можно будет посчитать скорость роста: 3 запроса за 15 секунд.

Вот как это выглядит на настоящих «Заметках» (curl -s скачивает страницу без служебного шума, grep notes_http оставляет только строки со словом notes_http). Два снимка с разницей в 15 секунд:

$ curl -s http://localhost:8080/metrics | grep notes_http
# 10:00:00  снимок №1
notes_http_requests_total{path="/notes",status="200"} 48213
notes_http_requests_total{path="/notes",status="500"} 17
# 10:00:15  снимок №2 (через 15 секунд)
notes_http_requests_total{path="/notes",status="200"} 48400
notes_http_requests_total{path="/notes",status="500"} 17

Приложение само показывает только текущие итоги. Из двух снимков видно: за 15 секунд пришло 187 запросов, ошибок не добавилось.

Частая ошибка: думать, что в /metrics лежит история. Это не так: там только текущее состояние. Историю строит Prometheus, записывая эти текущие числа раз в 15 секунд. Поэтому если Prometheus не работал час, часа данных не будет, даже когда приложение всё это время исправно считало.

Главное: /metrics это обычный текст с текущими значениями, а историю строит Prometheus.

Проверь понимание: в /metrics две строки: notes_http_requests_total{path="/notes",status="200"} 10 и notes_http_requests_total{path="/notes",status="500"} 2. Сколько тут временных рядов?

Ответ

Два: имя одно, но наборы меток разные (status="200" и status="500"), а ряд определяется именем и всеми метками вместе.

У чисел бывают разные типы. Какие?

Четыре типа метрик

«Число» бывает разным по смыслу. Число запросов только растёт. Число заметок сейчас может и уменьшиться. Время ответа это не одно число, а целое распределение. Prometheus хочет знать тип, чтобы правильно с ним работать.

Счётчик (counter) только растёт. Датчик (gauge) идёт вверх и вниз, важно текущее значение. Гистограмма (histogram) считает, сколько наблюдений попало в каждый диапазон: она не хранит точное время каждого запроса, но показывает распределение. Все четыре типа в таблице ниже.

Тип Что это Пример
counter (счётчик) только растёт; при перезапуске процесса сбрасывается в 0 notes_http_requests_total
gauge (датчик) значение идёт вверх и вниз notes_notes_total, память процесса
histogram (гистограмма) считает наблюдения по корзинам (bucket) с верхней границей le notes_http_request_duration_seconds
summary (сводка) квантили (p95 и подобные, см. 8.1) считаются в самом приложении; их нельзя складывать между копиями сервиса редко, в новом коде обычно histogram

По счётчику интересно не само число, а скорость роста. «Всего запросов 1 000 000» ничего не говорит: это за день или за год? «Сейчас 12 запросов в секунду» говорит. Скорость считает функция rate(), она в уроке 8.3. Ей же не страшен сброс счётчика после перезапуска процесса: она замечает, что число упало, и понимает, что это начало нового отсчёта, а не «-1000 запросов».

Гистограмма подробно. Она нужна, чтобы считать задержки (p95 из 8.1). Ты заранее выбираешь границы корзин, например 0.1, 0.5 и 1 секунда. Каждый ответ приложения «кладётся» в корзины. Гистограмма даёт три вида рядов:

  • имя_bucket{le="0.5"}: сколько наблюдений были не больше 0.5 секунды (le значит «less or equal», меньше или равно);
  • имя_sum: сумма всех значений;
  • имя_count: сколько было наблюдений.

Корзины кумулятивные: в le="0.5" входит всё, что уже попало в le="0.1". Последняя корзина le="+Inf" (бесконечность) вмещает вообще всё и потому равна _count.

Разберём на примере. Мы записали четыре времени ответа: 0.05, 0.3, 0.3 и 2.0 секунды, границы корзин 0.1, 0.5 и 1.

Значение Попало в le="0.1" le="0.5" le="1" le="+Inf"
0.05 да да да да
0.3 нет да да да
0.3 нет да да да
2.0 нет нет нет да
Итого 1 3 3 4

_count = 4, _sum = 0.05 + 0.3 + 0.3 + 2.0 = 2.65. Среднее время = _sum / _count = 2.65 / 4 = 0.6625 секунды. Ты увидишь ровно эти числа в задании 1.

Столбики только растут слева направо: так устроены корзины. Разность соседних столбиков и есть число запросов в своём диапазоне.

Прикинь сам: в гистограмме _bucket{le="0.5"} 30, _bucket{le="1"} 30, _count 34. Что можно сказать о четырёх запросах?

30 запросов уложились в 0.5 секунды, а четыре оказались медленнее секунды (34 минус 30, они попали только в корзину +Inf). Корзины кумулятивные, поэтому le="1" не отличается от le="0.5": между 0.5 и 1 секундой запросов не было.

Частая ошибка: путать counter и gauge. Правило простое: если число может уменьшиться при нормальной работе (заметок стало меньше, память освободилась), это gauge. Если оно только накапливается («всего случилось»), это counter. Ещё путают гистограмму с готовыми квантилями: гистограмма хранит корзины, а p95 из них оценивают позже. Из-за этого корзины надо выбирать под свои задержки: если первая корзина 100 мс, а все ответы по 20 мс, то p95 окажется «где-то внутри первой корзины», то есть оценка будет грубой.

Главное: counter только растёт, gauge ходит вверх и вниз, histogram считает наблюдения по накопительным корзинам.

Метки делят метрику на ряды. Сколько их допустимо?

Метки и кардинальность

Одной цифры «запросов всего 1000» мало: нужно уметь разрезать по путям, методам и статусам. Метки (labels) как раз делят одну метрику на группы.

Каждая уникальная комбинация значений всех меток это отдельный ряд в памяти и на диске. Число рядов называется кардинальностью (cardinality, «мощность множества»). Если метка принимает 5 значений, а вторая 3, а третья 4, то рядов до 5 * 3 * 4 = 60. Это безопасно. Если положить в метку что-то неограниченное (номер пользователя, номер заметки, сырой URL), рядов станет миллионы, память Prometheus раздуется, и он упадёт по OOM (нехватка памяти, процесс убивает система, урок 1.5).

Разберём на примере. В «Заметках» метрика notes_http_requests_total имеет метки method (GET, POST…), path (11 известных маршрутов плюс other) и status (несколько кодов). Рядов не больше нескольких сотен. Теперь представь, что вместо path="/notes" в метку попадает сырой адрес запроса: /notes/17, /notes/18… Каждая заметка добавит новые ряды для каждой пары method и status. После 10 000 заметок это десятки тысяч рядов, а если кто-то просканирует сайт случайными URL, то миллионы. Поэтому в приложении есть функция route_label: всё, что не входит в список известных маршрутов, превращается в other.

Частая ошибка: считать, что подробности в метках всегда хороши. Для метрик подробности вредны, для логов (8.7) и трейсов (8.8) полезны. Метки метрик должны быть скучными: короткий конечный список значений.

Главное: каждая комбинация меток это отдельный ряд, поэтому в метках держат короткий конечный список значений.

Проверь понимание: разработчик хочет добавить в notes_http_requests_total метку note_id, чтобы видеть популярные заметки. Что ответишь?

Ответ

Нельзя: значений столько же, сколько заметок, и каждое даёт новый ряд для каждой комбинации method/status. Это взрыв кардинальности. Популярные заметки смотрят в логах или трейсах, а метрика остаётся с ограниченным набором меток.

Где всё это хранится?

Хранение: TSDB, retention, том

Числа надо где-то держать, и быстро находить по имени, меткам и времени. Обычная база данных с таблицами для этого плохо подходит, поэтому в Prometheus своя база временных рядов (TSDB, time series database).

Prometheus пишет данные в каталог, который задаёт флаг --storage.tsdb.path. Сначала свежие числа лежат в памяти (и в журнале на диске на случай перезапуска), потом порциями по два часа сбрасываются в блоки на диске. Блоки старше срока хранения удаляются. Срок хранения (retention) задаёт --storage.tsdb.retention.time, по умолчанию 15 дней. Каталог мы выносим в том Docker (prom-data), иначе при удалении контейнера пропадёт вся история.

Разберём на примере. У нас 15 секунд между сборами. В сутках 86 400 секунд, значит один ряд получает 86 400 / 15 = 5 760 значений в сутки. Если рядов 2 000, то за сутки записей 11 520 000. Prometheus сжимает их до 1-2 байт на значение, так что сутки занимают порядка 20 МБ. Поэтому начинают с одного Prometheus с разумным retention.

Прикинь сам: почему каталог с данными Prometheus кладём в том, а не оставляем внутри контейнера?

Файловая система контейнера исчезает вместе с контейнером (урок 4.1). При пересоздании контейнера без тома пропала бы вся история метрик. Том живёт отдельно и переживает пересоздание.

Частая ошибка: считать Prometheus долговременным хранилищем и кластером. Это не так: данные лежат на одном узле. Для долгого хранения и нескольких кластеров есть Thanos, Mimir и VictoriaMetrics, но это надстройки, до которых надо дорасти.

Главное: данные лежат в TSDB на одном узле, срок хранения 15 дней, а каталог выносят в том.

Не всё умеет отдавать /metrics само. Кто помогает?

Экспортёры, Pushgateway и откуда берутся цели

Не всё умеет отдавать /metrics само: у Linux, PostgreSQL, nginx его нет. И не всё живёт достаточно долго, чтобы его успели опросить.

Экспортёр (exporter) это небольшая программа, которая читает состояние чужой системы и выдаёт его в формате /metrics. Мы подключаем два:

  • node_exporter (порт 9100) отдаёт метрики хоста: процессор, память, диски, сеть. Он читает их из каталогов /proc и /sys (урок 1.5).
  • cAdvisor (порт 8080 внутри сети, у нас проброшен как 8081) отдаёт метрики контейнеров: сколько памяти и процессора съел каждый.

Остальные экспортёры (PostgreSQL, nginx, проверки снаружи через blackbox) разберём в 8.4.

Pushgateway (шлюз для «пуша») нужен для задач, которые живут секунды: CronJob, скрипт бэкапа. Такая задача в конце работы отправляет итог в Pushgateway, а Prometheus забирает его оттуда как с обычной цели. Это исключение, а не основной путь.

Как Prometheus узнаёт, куда ходить. У нас список статический: адреса записаны в prometheus.yml. В Kubernetes цели находятся автоматически через service discovery (обнаружение служб), разберём в 8.9.

Разберём на примере. Скрипт бэкапа работает 40 секунд раз в сутки. Prometheus ходит раз в 15 секунд, но почти всё время процесса нет. Скрипт в конце вызывает Pushgateway и записывает gauge с временем успеха (например, backup_last_success_timestamp_seconds 1790000000). Шлюз живёт всегда, Prometheus снимает эту цифру каждые 15 секунд. Алерт строят на возрасте: «сейчас минус время последнего успеха больше 25 часов» (период 24 часа плюс час запаса на задержку задачи).

Частая ошибка: считать Pushgateway заменой pull для всего. Это не так, и у него подводный камень: он хранит последнее значение вечно, даже если задача давно не запускалась, а up показывает живость шлюза, а не задачи.

Главное: экспортёр переводит чужую систему в формат Prometheus, а Pushgateway нужен только для коротких задач.

Проверь понимание: скрипт бэкапа работает 40 секунд раз в сутки. Как получить по нему метрику «время последнего успешного бэкапа»?

Ответ

Скрипт в конце отправляет gauge (например, Unix-время успеха) в Pushgateway, а Prometheus собирает Pushgateway как обычную цель. Прямой pull бесполезен: 15 секунд опроса почти всегда попадут в момент, когда процесса нет.

Как понять, что цель вообще видна?

Состояния цели: как читать страницу Targets

Первый вопрос при любой проблеме с метриками: «Prometheus вообще видит эту цель?». Ответ даёт страница /targets в его веб-интерфейсе. Без умения её читать ты будешь гадать, почему график пустой.

У каждой цели два главных поля. Состояние (health): up, если последний сбор удался, и down, если нет. Последняя ошибка (lastError): текст, который Prometheus получил при неудаче. Состояние говорит, что плохо, а текст ошибки почти всегда сразу указывает, где искать.

Что написано в lastError Что это значит Что проверить
connection refused по адресу есть машина, но порт никто не слушает запущено ли приложение, верный ли порт
no such host имя не превратилось в адрес есть ли контейнер в той же сети, нет ли опечатки
context deadline exceeded цель не успела ответить за scrape_timeout не завис ли процесс, не слишком ли тяжёлая страница
server returned HTTP status 404 сервер ответил, но такого пути нет верен ли metrics_path, есть ли в приложении /metrics

Разберём на примере. Представь строку «notes down, Get "http://notes:8081/metrics": dial tcp 172.18.0.4:8081: connect: connection refused». Читаем слева направо. Get и адрес: Prometheus пытался сделать обычный запрос. notes:8081: порт 8081, хотя приложение слушает 8080. 172.18.0.4 это адрес контейнера: имя notes найдено успешно, значит проблема не в имени. connection refused: на этом адресе порт закрыт. Вывод: в конфиге опечатка в порту. Подсказка уже в тексте.

Прикинь сам: цель down, ошибка server returned HTTP status 404 Not Found. Приложение упало?

Нет. Сервер отвечает, иначе была бы connection refused или таймаут. Но по пути /metrics ничего нет: либо в приложении ещё не добавили этот адрес, либо в конфиге Prometheus указан другой metrics_path.

Частая ошибка: читать down как «приложение упало». Это не так: оно может быть живо и обслуживать пользователей, но /metrics недоступен (404, закрыт порт, блокирует firewall). Поэтому после down сначала читай текст ошибки, а потом решай, куда идти.

Главное: down не значит «приложение упало»: смотри текст ошибки и решай по нему.

Давай разберёмся со словами «метрика», «ряд» и «сэмпл».

Сэмпл, ряд и метрика: три слова про одни данные

В документации и в разговорах эти слова используют вперемешку, и новичок думает, что речь о разных вещах. Разберись один раз, и дальше текст читается легче.

Метрика (metric) это имя показателя: notes_http_requests_total. Ряд (series) это метрика вместе с конкретными метками: notes_http_requests_total{status="500"}. Сэмпл (sample, «проба») это одна точка ряда: пара «момент времени, число». Раз в 15 секунд Prometheus добавляет в каждый ряд по одному сэмплу.

Разберём на примере. Метрика notes_http_requests_total с метками status (200 и 500) даёт два ряда. За минуту в каждом ряду накопится четыре сэмпла (15 секунд между ними), всего восемь. Сэмпл (sample) это одно значение в один момент, ряд (series) это вся линия таких значений. Метрика scrape_samples_scraped (её разберём в разделе «Метрики, которые Prometheus пишет сам») считает именно сэмплы, которые вернула цель за один сбор: по одному новому сэмплу на каждый ряд, то есть здесь 2.

Частая ошибка: связывать сэмпл с запросом пользователя. Они не связаны: один сэмпл мог появиться из миллиона запросов, потому что это всего лишь число «на сейчас».

Главное: метрика это имя, ряд это имя с метками, сэмпл это одна точка ряда.

Проверь понимание: метрика с двумя метками: method (3 значения) и status (4 значения). Сколько сэмплов добавится за один сбор, если встречались все комбинации?

Ответ

3 * 4 = 12 рядов, в каждый добавляется по одному сэмплу, значит 12 сэмплов за сбор.

А как часто делать обход?

Интервал сбора: почему 15 секунд

Интервал нельзя выбрать наугад: от него зависит, насколько быстро ты заметишь поломку, сколько места займёт база и насколько нагрузишь сами цели.

Редкий сбор (раз в час) пропустит скачок, слишком частый (каждую секунду) завалит цель запросами и диск записями. Для сервисов обычный ритм это 10-60 секунд.

Чем меньше интервал, тем точнее график и тем быстрее срабатывает алерт, но тем больше сэмплов, места и нагрузки на цель. Второе число, scrape_timeout, это сколько Prometheus ждёт ответа. Оно обязано быть не больше интервала (иначе новый сбор начнётся, пока старый не закончился). У нас 15 секунд и 10 секунд таймаут.

Разберём на примере. Если поломка случилась сразу после сбора, Prometheus заметит её только на следующем: в худшем случае через 15 секунд. К этому прибавляется время условия алерта (например, «5 минут подряд», см. 8.5). Интервал в минуту сделает реакцию в худшем случае вдвое-вчетверо медленнее и сократит объём данных в четыре раза, а для краткого всплеска в 20 секунд он вообще сделает картину неточной: всплеск может не попасть ни в один сбор.

Прикинь сам: всплеск ошибок длился 10 секунд, интервал сбора 60 секунд. Гарантирует ли Prometheus, что он его увидит?

Нет. Всплеск мог целиком оказаться между двумя сборами. Счётчики ошибок в этом случае всё равно покажут разницу между сборами (они накопительные), но точную форму всплеска ты не восстановишь: видно будет «ошибок стало больше», а не «когда и как резко».

Частая ошибка: думать, что интервал «чем меньше, тем лучше». Мелкий интервал нужен не везде: для метрики «свободно диска» хватит минуты. Начинай с 15-30 секунд и меняй по необходимости, а не по привычке.

Главное: интервал это компромисс между точностью, местом и нагрузкой, а scrape_timeout не больше интервала.

Откуда берутся метрики хоста и контейнеров?

Что именно читают node_exporter и cAdvisor

Метрики приложения отвечают на вопрос «что делает программа». Но когда приложение тормозит, причина часто под ним: не хватает памяти, диск забит, контейнер упёрся в лимит процессора. Без метрик хоста и контейнеров ты видишь симптом, но не причину.

Приложение рассказывает о себе само, а экспортёры снимают показатели независимо, не спрашивая программу.

Linux сам ведёт учёт ресурсов и выкладывает его как обычные файлы в каталогах /proc и /sys (урок 1.5). node_exporter каждый раз при запросе /metrics читает эти файлы и переводит цифры в формат Prometheus. Например, node_memory_MemAvailable_bytes это байты памяти, которые можно ещё использовать. cAdvisor делает то же, но для каждого контейнера отдельно: читает учёт расхода ресурсов, который ведёт ядро для каждой группы процессов, и отдаёт метрики с префиксом container_ (например, container_memory_usage_bytes).

Разберём на примере. У node_exporter метрика node_load1 это средняя нагрузка за последнюю минуту (число процессов, которые хотят процессор). На машине с двумя ядрами значение 2 означает «заняты оба ядра, очереди нет», а 6 означает «в очереди стоят ещё четыре». Важное отличие от приложения: экспортёр ничего не считает сам, он только переводит. Поэтому его страница /metrics всегда свежая, а при его остановке пропадёт только картина хоста, приложение останется видимым.

Частая ошибка: думать, что экспортёр «собирает» метрики и хранит их. Это не так: он отвечает только в момент запроса, хранит и собирает историю по-прежнему Prometheus.

Главное: экспортёры переводят состояние /proc и /sys и ничего не хранят, история остаётся у Prometheus.

Проверь понимание: node_exporter остановили, приложение работает. Какие метрики пропадут из Prometheus?

Ответ

Пропадут метрики хоста (память, диск, процессор), цель node станет down. Метрики приложения продолжат собираться, потому что это отдельная цель.

А как считает метрики само приложение?

Как приложение считает метрики: путь одного запроса

Метрики сами не появятся: кто-то должен в нужный момент прибавить единицу к счётчику и записать длительность. Этим занимается библиотека-клиент внутри приложения. В Python это prometheus_client.

Библиотека хранит все метрики в одном месте, реестре (registry), в памяти процесса. Когда приходит запрос:

  1. Приложение запоминает время начала.
  2. Обрабатывает запрос и отправляет ответ.
  3. В момент отправки статуса вызывается наш код: он прибавляет 1 к нужному ряду счётчика (по метке метода, пути и статуса) и кладёт длительность в гистограмму.
  4. Когда Prometheus приходит на /metrics, функция generate_latest() просто печатает весь реестр текстом. Ничего не считается заново: страница это снимок текущих чисел.
sequenceDiagram
    participant К as Клиент
    participant А as app.py
    participant Р as Реестр метрик
    participant П as Prometheus
    К->>А: GET /notes
    Note over А: запомнил время начала
    А-->>К: ответ 200
    А->>Р: +1 к requests_total{GET,/notes,200}
    А->>Р: длительность в корзины гистограммы
    П->>А: GET /metrics
    А-->>П: generate_latest(): текст всего реестра

Счёт ведётся в момент ответа, а при запросе /metrics реестр просто печатается как есть.

Разберём на примере. Пришли три запроса: GET /notes за 0.03 с, GET /notes за 0.4 с и GET /nope. После них в реестре: requests_total{GET,/notes,200} = 2, requests_total{GET,other,404} = 1 (неизвестный путь стал other, см. предыдущий раздел). В гистограмме для /notes две записи: 0.03 попало в корзины от le="0.05" и выше, 0.4 попало в корзины от le="0.5" и выше. Счётчики лежат в памяти процесса, поэтому после перезапуска app.py всё начнётся с нуля (теория про сброс выше).

Прикинь сам: сервис обработал 1 000 000 запросов на /notes со статусом 200. Сколько рядов у счётчика запросов из-за этого?

Один: {method="GET",path="/notes",status="200"}. Число запросов это значение ряда, а не количество рядов. Растёт число рядов только с новыми комбинациями меток.

Частая ошибка: думать, что метрики «весят» столько же, сколько запросов. Это не так: память занимает число рядов, а не число запросов. Миллион запросов в один и тот же ряд стоит те же байты, что один.

Главное: приложение прибавляет счётчики в момент ответа, а /metrics печатает реестр как снимок.

Как называть то, что считаем?

Как называть метрики

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

  • Имя начинается с префикса проекта: notes_.... Так видно, чья это метрика.
  • Счётчики заканчиваются на _total: notes_http_requests_total.
  • Единицу измерения пишут в имени и берут базовую: секунды (не миллисекунды), байты (не мегабайты): notes_http_request_duration_seconds.
  • Имя описывает, что измеряют, а не как это будут считать. Храни исходные счётчики, а производные считай запросом. Пример: приложение отдаёт «всего запросов» и «ошибок», а «долю ошибок» не отдаёт, потому что долю нельзя сложить между серверами. Её считает запрос; при необходимости результат сохраняют правилом записи (урок 8.3).
  • Доли выражают числом от 0 до 1 (суффикс _ratio), а не процентами.

Разберём на примере. Метрика request_time_ms нарушает два правила: нет префикса проекта и единица не базовая (миллисекунды). Правильно: notes_http_request_duration_seconds. Разработчик, который увидит в Grafana значение 0.25 и не знает единицы, всё равно поймёт, что это секунды, а не миллисекунды.

Частая ошибка: считать, что название не важно, «главное, чтобы работало». Смешанные единицы (где-то секунды, где-то миллисекунды) приводят к ошибкам в расчётах на порядок, и заметить их трудно.

Главное: префикс проекта, _total у счётчиков и базовые единицы (секунды, байты) спасают от ошибок на порядок.

Проверь понимание: как назвать счётчик числа отправленных писем?

Ответ

notes_emails_sent_total: префикс проекта, что считаем, суффикс _total для счётчика.

Какие ряды появляются у каждой цели без нашей помощи?

Метрики, которые Prometheus пишет сам

Кроме метрик приложения, Prometheus сам записывает несколько служебных рядов про каждый сбор. Они показывают, здорова ли сама система сбора.

К каждой цели автоматически добавляются:

Метрика Что означает
up 1 если сбор удался, 0 если нет
scrape_duration_seconds сколько секунд занял сбор
scrape_samples_scraped сколько значений вернула цель за один сбор
scrape_samples_post_metric_relabeling сколько значений осталось после фильтрации

Разберём на примере. У «Заметок» scrape_samples_scraped будет в районе нескольких сотен: наши метрики плюс стандартные метрики процесса Python (использование памяти, число сборок мусора), которые prometheus_client добавляет сам. Если завтра это число выросло до 20 000, значит, у цели появились лишние ряды. Это самый быстрый способ заметить взрыв кардинальности, ещё до того как Prometheus упадёт.

Прикинь сам: up{job="notes"} = 1, а пользователи получают 500. Противоречие?

Нет. up относится только к сбору метрик: /metrics отвечает, значит up = 1. Ошибки пользователей видны в счётчике notes_http_requests_total со статусом 500, а не в up.

Частая ошибка: читать up = 1 как «сервис здоров». Это не так: он значит только «/metrics ответил корректно». Приложение может отвечать на /metrics и при этом падать на реальных запросах. Здоровье для пользователя измеряют ошибками и задержкой (RED из 8.1), а внешняя проверка, ходит ли реальный клиент, это тема 8.4.

Главное: up = 1 значит только «/metrics ответил», а здоровье для пользователя измеряют ошибками и задержкой.

Как всё это связано с целями из урока 8.1?

Как метрики связаны с SLI из урока 8.1

Мы собираем метрики не ради метрик, а чтобы посчитать SLI и SLO из 8.1. Полезно сразу увидеть, какие ряды для чего нужны.

  • Доступность: «хорошие запросы делить на все». Все запросы это сумма notes_http_requests_total, плохие это те, у которых status начинается с 5. Метка status в счётчике нужна именно для этого.
  • Задержка: доля запросов быстрее порога. Её даёт гистограмма: корзина le="0.5" делится на _count. Порог в SLI должен совпадать с границей корзины: в нашем списке 0.25 и 0.5, поэтому порог 300 мс из 8.1 мы в 8.3 заменим ближайшей границей.

Разберём на примере. За час: всего запросов на /notes 1 000, из них со статусом 5xx 12. Доступность = (1 000 - 12) / 1 000 = 98.8%. В гистограмме _count = 1 000, _bucket{le="0.5"} = 950. Доля быстрее 0.5 секунды = 950 / 1 000 = 95%.

Частая ошибка: выбирать порог SLI любой. Раз квантили и доли считаются по корзинам, порог, не совпадающий с границей, даст приблизительный ответ. Корзины планируют вместе с SLO.

Главное: доступность считают по счётчику со статусом, задержку по корзине гистограммы, а порог SLI совпадает с границей корзины.

Проверь понимание: в гистограмме _count = 2 000, _bucket{le="0.25"} = 1 700. Какая доля запросов быстрее 250 мс?

Ответ

1 700 / 2 000 = 0.85, то есть 85%.

Осталось прочитать конфиг, который всё это запускает.

Конфиг prometheus.yml: из чего он состоит

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

YAML-файл (см. урок 4.5: отступы пробелами значат вложенность). Два главных блока:

global:
  scrape_interval: 15s       # как часто ходить за метриками по умолчанию
scrape_configs:              # список задач сбора
  - job_name: notes          # имя задачи: станет меткой job="notes"
    metrics_path: /metrics   # путь, по умолчанию именно он (можно не писать)
    static_configs:          # статический список целей
      - targets: ["notes:8080"]   # host:port; имя резолвит сеть Docker

Разберём на примере. Адрес цели notes:8080 использует имя контейнера в сети Docker (урок 4.5), поэтому Prometheus, живущий в той же сети notes-net, находит его по имени. localhost:8080 не подошёл бы: для Prometheus localhost это он сам, а не соседний контейнер.

Прикинь сам: почему в targets нельзя написать localhost:8080 для приложения, которое работает в соседнем контейнере?

Внутри контейнера Prometheus localhost указывает на сам контейнер Prometheus, а порт 8080 в нём никто не слушает. Соседний контейнер доступен по имени сервиса в общей сети: notes:8080.

Частая ошибка: ждать, что Prometheus сразу увидит правку файла. Он читает конфиг при старте и по сигналу перечитывания (в нашем стенде проще перезапустить контейнер). Перед этим конфиг проверяют утилитой promtool check config: она находит опечатки в отступах и ключах до запуска.

Главное: в конфиге глобальный интервал и список задач с целями, а адреса соседей пишут по имени контейнера, не localhost.

Практика

Все команды в заданиях 1 и 2 запускай на машине, где стоит Docker и есть ~/notes из темы 4; в /etc/hosts должна быть строка 127.0.0.1 notes.lab, к приложению ходим через прокси: curl -sk https://notes.lab/.... Вывод в заданиях ниже не снят с живого стенда: если у тебя он чуть отличается, это нормально, смотри на смысл. Понадобится jq (программа для разбора JSON, урок 1.2); если её нет: sudo apt install jq.

Задание 1. Прочитай /metrics глазами на игрушечном примере

Цель: увидеть формат exposition и понять, как гистограмма превращается в корзины, до того как это станет частью «Заметок».

Предскажи: мы запишем в гистограмму четыре значения: 0.05, 0.3, 0.3 и 2.0 секунды, с корзинами 0.1, 0.5 и 1. Какое число будет в le="0.5"? А в le="+Inf"?

Ответ

В le="0.5" будет 3 (0.05 и два по 0.3, корзины кумулятивные), в le="+Inf" будет 4 (все наблюдения).

Шаги:

  1. Создай отдельный каталог и виртуальное окружение (не в ~/notes):

    mkdir -p ~/metrics-demo && cd ~/metrics-demo
    python3 -m venv .venv
    .venv/bin/pip install prometheus_client
    

    Что здесь происходит: python3 -m venv .venv создаёт «личную коробку» для Python-пакетов в каталоге .venv (урок 1.6 и тема 4 использовали то же самое), а .venv/bin/pip install ставит библиотеку prometheus_client только в неё, не трогая системный Python.

  2. Создай demo.py:

    import time
    from prometheus_client import Counter, Gauge, Histogram, start_http_server
    
    # счётчик с меткой status: два ряда
    REQS = Counter("demo_requests", "Сколько запросов обработано", ["status"])
    # гистограмма с тремя корзинами (плюс автоматическая +Inf)
    LAT = Histogram("demo_latency_seconds", "Время обработки", buckets=(0.1, 0.5, 1))
    # датчик: значение можно ставить любое
    QUEUE = Gauge("demo_queue_size", "Размер очереди")
    
    start_http_server(8000)  # /metrics на порту 8000
    
    REQS.labels("200").inc(3)
    REQS.labels("500").inc()
    for value in (0.05, 0.3, 0.3, 2.0):
        LAT.observe(value)
    QUEUE.set(7)
    
    time.sleep(3600)
    
  3. Запусти в фоне и прочитай метрики:

    .venv/bin/python demo.py &
    sleep 1
    curl -s localhost:8000/metrics | grep '^demo_' | grep -v _created
    

    Разбор: & в конце первой строки запускает программу в фоне, чтобы терминал остался твоим; sleep 1 даёт ей секунду стартовать; curl -s скачивает страницу молча (урок 2.4); первый grep '^demo_' оставляет строки, начинающиеся с demo_ (знак ^ значит «в начале строки»), а grep -v _created выбрасывает строки со словом _created (клиент добавляет время создания каждой метрики, нам оно сейчас не нужно).

    В demo.py сначала объявлены три метрики: Counter, Histogram (с корзинами 0.1, 0.5, 1), Gauge. Метод .inc() увеличивает счётчик, .observe(x) кладёт значение в гистограмму, .set(7) ставит датчик. start_http_server(8000) запускает встроенный веб-сервер, который отдаёт /metrics.

Что должно получиться:

demo_requests_total{status="200"} 3.0
demo_requests_total{status="500"} 1.0
demo_latency_seconds_bucket{le="0.1"} 1.0
demo_latency_seconds_bucket{le="0.5"} 3.0
demo_latency_seconds_bucket{le="1.0"} 3.0
demo_latency_seconds_bucket{le="+Inf"} 4.0
demo_latency_seconds_count 4.0
demo_latency_seconds_sum 2.65
demo_queue_size 7.0

Последние знаки _sum могут отличаться из-за чисел с плавающей точкой. Убери фоновый процесс: kill %1.

Как читать вывод: каждая строка это один временной ряд. demo_requests_total два ряда (по статусам 200 и 500), у гистограммы четыре корзины и два служебных ряда _count и _sum. Клиент дописал _total к имени счётчика сам. Корзина le="0.5" равна 3: 0.05 и два по 0.3, ровно как в таблице теории. _sum 2.65 это 0.05 + 0.3 + 0.3 + 2.0. Все значения выведены как 3.0, потому что Prometheus хранит числа с плавающей точкой.

Объясни себе:

  • Почему счётчик назван demo_requests, а в выводе он demo_requests_total?
  • Как из этих строк узнать среднее время запроса? (подсказка: _sum и _count)
  • Что изменится в выводе, если сделать LAT.observe(0.1): в какую корзину попадёт значение ровно на границе?

Типичные ошибки:

  • OSError: [Errno 98] Address already in use: порт 8000 занят прошлым запуском демо. Найди процесс ss -ltnp | grep 8000 и останови его (kill), либо смени порт.
  • ModuleNotFoundError: No module named 'prometheus_client': запустил системным python3, а не .venv/bin/python. Пакеты в venv видит только его интерпретатор.
  • error: externally-managed-environment при pip install: ставишь в системный Python. Используй venv, как в шаге 1.
  • The virtual environment was not created successfully because ensurepip is not available: в Ubuntu модуль venv ставится отдельно. Выполни sudo apt install python3-venv и повтори шаг 1.

Задание 2. Подними стек мониторинга и увидь первый target DOWN

Цель: запустить Prometheus, node_exporter и cAdvisor в Compose, подключить их к сети «Заметок» и прочитать состояние целей.

Предскажи: основной стек «Заметок» работает на образе 0.4.1, там ещё нет /metrics. Какой будет статус цели notes и что напишет Prometheus в поле ошибки? Как отреагирует up?

Ответ

Цель notes будет down, а up{job="notes"} равен 0. Приложение живо и отвечает, но на /metrics возвращает 404 (в версии v4 «Заметок» такого пути нет, он появится в задании 3), поэтому текст ошибки: server returned HTTP status 404 Not Found. Prometheus считает успехом только ответ 200 с корректным телом.

Шаги:

  1. Убедись, что основной стек запущен (без него сеть notes-net не существует), из каталога ~/notes:

    cd ~/notes
    docker compose ps
    

    docker compose ps показывает контейнеры проекта; в колонке STATUS должно быть Up или healthy.

  2. Создай каталоги и файл monitoring/compose.yml:

    mkdir -p monitoring/prometheus
    
    # Стек мониторинга. Основной compose.yml должен быть запущен раньше:
    # сеть notes-net создаёт он, здесь мы к ней только подключаемся.
    services:
      prometheus:
        image: prom/prometheus:v3.15.0
        command:
          - --config.file=/etc/prometheus/prometheus.yml
          - --storage.tsdb.path=/prometheus
          - --storage.tsdb.retention.time=15d
        ports:
          - "127.0.0.1:9090:9090"
        volumes:
          - ./prometheus:/etc/prometheus:ro
          - prom-data:/prometheus
        restart: unless-stopped
    
      node_exporter:
        image: prom/node-exporter:v1.12.1
        command:
          - --path.rootfs=/host
        pid: host
        ports:
          - "127.0.0.1:9100:9100"
        volumes:
          - /:/host:ro,rslave
        restart: unless-stopped
    
      cadvisor:
        image: ghcr.io/google/cadvisor:v0.60.6
        ports:
          - "127.0.0.1:8081:8080"  # наружу 8081, внутри сети cAdvisor слушает 8080
        volumes:
          - /:/rootfs:ro
          - /var/run/docker.sock:/var/run/docker.sock:ro
          - /sys:/sys:ro
          - /var/lib/docker/:/var/lib/docker:ro
          - /dev/disk/:/dev/disk:ro
        devices:
          - /dev/kmsg
        restart: unless-stopped
    
    networks:
      default:
        name: notes-net
        external: true
    
    volumes:
      prom-data:
    
  3. Создай monitoring/prometheus/prometheus.yml:

    global:
      scrape_interval: 15s
    
    scrape_configs:
      # само приложение: /metrics по умолчанию
      - job_name: notes
        static_configs:
          - targets: ["notes:8080"]
    
      # метрики хоста
      - job_name: node
        static_configs:
          - targets: ["node_exporter:9100"]
    
      # метрики контейнеров (внутри сети порт 8080)
      - job_name: cadvisor
        static_configs:
          - targets: ["cadvisor:8080"]
    

Разберём compose.yml по частям (комментарии в самом файле объясняют остальное). image: prom/prometheus:v3.15.0 фиксирует версию образа. В command: перечислены флаги Prometheus: где конфиг, где база и срок хранения. ports: "127.0.0.1:9090:9090" открывает интерфейс на порту хоста, но только для самой машины (урок 4.3): у Prometheus, node_exporter и cAdvisor нет аутентификации, и с адресом 0.0.0.0 любой в сети читал бы метрики и мог нагрузить Prometheus тяжёлыми запросами. В volumes: строка ./prometheus:/etc/prometheus:ro подключает твой каталог с конфигом внутрь контейнера только для чтения (ro), а prom-data:/prometheus это именованный том для базы. У node_exporter pid: host даёт ему видеть процессы хоста, а /:/host:ro,rslave подключает корень хоста только для чтения: без этого он мерил бы пустую файловую систему своего контейнера, а не диски машины (--path.rootfs=/host подсказывает, где искать «настоящий» корень). Сетевые метрики (node_network_*) при такой схеме относятся к сетевому пространству самого контейнера, а не хоста: чтобы мерить сеть хоста, у node_exporter нужен network_mode: host, в учебном стенде это не делаем. cAdvisor монтирует каталоги хоста и Docker, потому что читает данные о контейнерах прямо оттуда. Сокет docker.sock мы подключаем отдельным файлом, а не весь /var/run: даже на чтение доступ к нему раскрывает много, а на деле близок к root на хосте, поэтому в проде его никому лишнему не дают. В конце блок networks говорит: «не создавай свою сеть, подключись к уже существующей notes-net» (external: true).

  1. Проверь конфиг до запуска, затем подними стек и через 20 секунд посмотри цели:

    # Разбор: docker run --rm запускает временный контейнер и удаляет его после;
    # -v подключает наш каталог с конфигом; --entrypoint promtool запускает
    # проверяющую утилиту вместо самого Prometheus.
    docker run --rm -v "$PWD/monitoring/prometheus:/etc/prometheus:ro" \
      --entrypoint promtool prom/prometheus:v3.15.0 \
      check config /etc/prometheus/prometheus.yml
    docker compose -f monitoring/compose.yml up -d
    sleep 20
    curl -s localhost:9090/api/v1/targets | jq -r '.data.activeTargets[] | "\(.labels.job)\t\(.health)\t\(.lastError)"'
    

    Разбор последней команды: curl -s localhost:9090/api/v1/targets спрашивает у Prometheus список целей в формате JSON. jq -r печатает без кавычек; .data.activeTargets[] берёт каждую цель; в строке "\(.labels.job)\t\(.health)\t\(.lastError)" подставляются имя задачи, состояние и последняя ошибка, а \t это табуляция между колонками.

Что должно получиться:

Checking /etc/prometheus/prometheus.yml
  SUCCESS: /etc/prometheus/prometheus.yml is valid prometheus config file syntax

cadvisor	up	
node	up	
notes	down	server returned HTTP status 404 Not Found

Порядок строк может отличаться.

Как читать вывод: первые две строки от promtool: SUCCESS значит конфиг правильный. Дальше три цели: up у cadvisor и node значит, что Prometheus получил и разобрал их /metrics. У notes состояние down, а в последней колонке причина server returned HTTP status 404 Not Found: приложение живо, но пути /metrics в версии 0.4.1 нет. Это ожидаемо, починим в задании 3. Пустая последняя колонка у здоровых целей значит «ошибок нет». Заодно загляни в экспортёры: curl -s localhost:9100/metrics | grep -E '^node_load1 ' и curl -s localhost:8081/metrics | grep -c '^container_'. Открой в браузере http://localhost:9090/targets и найди ту же ошибку. Если браузера нет на сервере, пробрось порт: ssh -L 9090:localhost:9090 <сервер>.

Объясни себе:

  • Почему в prometheus.yml адрес notes:8080, а не localhost:8080?
  • Почему cAdvisor опрашивается на порту 8080, хотя снаружи он на 8081?
  • Зачем монтировать / хоста в node_exporter и что бы он показывал без этого?

Типичные ошибки:

  • network notes-net declared as external, but could not be found: основной стек не запущен, сети нет. Запусти docker compose up -d в ~/notes, затем стек мониторинга.
  • Bind for 127.0.0.1:9090 failed: port is already allocated: порт занят другим контейнером или процессом. Найди ss -ltnp | grep 9090.
  • parsing YAML file /etc/prometheus/prometheus.yml: yaml: line 9: did not find expected key: сбился отступ в prometheus.yml. Проверь promtool check config (шаг 4).
  • docker compose up -d падает с ошибкой про устройство /dev/kmsg: на хосте нет этого устройства. Убери секцию devices из cadvisor: без неё cAdvisor работает, в логе будет только предупреждение, что события OOM отключены.

Задание 3. Шаг проекта: /metrics в «Заметках», образ 0.5.0

Инструментирование приложения возьми из примера. Найди, где увеличивается счётчик запросов, где измеряется длительность и какие метки попадают в /metrics; свяжи это с результатом своих HTTP-запросов. Реализовывать библиотеку метрик или разбирать весь сервер на Python сейчас не требуется.

Цель: добавить в app.py метрики (v5), пересобрать образ 0.5.0, увидеть up = 1 и зафиксировать состояние тегом v0.5.0.

Предскажи: мы отправим несколько запросов, включая /error и несуществующий путь /nope. Под какой меткой path будет виден /nope и почему?

Ответ

Под path="other". Метка берётся только из фиксированного списка маршрутов, всё остальное схлопывается в other, чтобы посторонние URL не размножали ряды. Статус при этом настоящий: 404.

Шаги:

  1. Добавь зависимость. Установи пакет в виртуальное окружение проекта с закреплённой версией и допиши её в requirements.txt, откуда её берёт сборка образа (урок 4.4):

    cd ~/notes
    echo 'prometheus_client==0.26.0' >> requirements.txt
    .venv/bin/pip install -r requirements.txt
    .venv/bin/pip freeze | grep -i prometheus
    

    Вывод последней команды: prometheus_client==0.26.0. Закреплённая версия (==) нужна, чтобы образ через полгода собрался с тем же клиентом, а не с новым, где что-то могло поменяться.

  2. В app.py добавь импорт и объявления метрик выше класса Handler. Остальные импорты (time, threading, urlparse) в файле уже есть:

    from prometheus_client import (CONTENT_TYPE_LATEST, Counter, Gauge,
                                   Histogram, generate_latest)
    
    # маршруты, которые допустимы в метке path; всё остальное станет "other"
    KNOWN_ROUTES = {"/", "/notes", "/healthz", "/readyz", "/headers", "/slow",
                    "/error", "/leak", "/burn", "/slowsql", "/metrics"}
    
    HTTP_REQUESTS = Counter(
        "notes_http_requests_total", "Число HTTP-запросов",
        ["method", "path", "status"])
    HTTP_DURATION = Histogram(
        "notes_http_request_duration_seconds", "Длительность запроса, секунды",
        ["method", "path"],
        buckets=(0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10))
    NOTES_TOTAL = Gauge("notes_notes_total", "Сколько заметок сохранено")
    BUILD_INFO = Gauge("notes_build_info", "Версия сборки", ["version"])
    NOTES_TOTAL_LOCK = threading.Lock()
    
    
    def route_label(path):
        # сырой URL в метку не попадает никогда: только известные маршруты
        return path if path in KNOWN_ROUTES else "other"
    
    
    def update_notes_total():
        # чтение и обновление идут по очереди: старый результат не затрёт новый
        with NOTES_TOTAL_LOCK:
            NOTES_TOTAL.set(len(list_notes()))
    

    Что здесь: Counter, Gauge, Histogram из теории. Первый параметр это имя метрики, второй описание для # HELP, третий список имён меток. buckets=(...) это границы корзин в секундах: от 5 мс до 10 с, чтобы покрыть и быстрые ответы, и /slow. BUILD_INFO хранит версию сборки в метке, значение всегда 1: так принято показывать «строковые» данные. KNOWN_ROUTES и route_label реализуют защиту от взрыва кардинальности из теории. update_notes_total() пересчитывает число заметок в датчике. Для учебного приложения этого достаточно; на проде значения, которые зависят от внешнего состояния, вычисляют в момент запроса /metrics, а не хранят в датчике.

  3. В классе Handler (тот же, что и в прошлых версиях) добавь два метода. parse_request вызывается после разбора строки запроса и запоминает время старта, а log_request вызывается стандартной библиотекой при отправке статуса ответа, там мы записываем метрики и передаём управление прежнему access-логу:

        def parse_request(self):
            self._t0 = time.monotonic()
            return super().parse_request()
    
        def log_request(self, code="-", size="-"):
            path = route_label(urlparse(self.path).path)
            HTTP_REQUESTS.labels(self.command, path, str(code)).inc()
            HTTP_DURATION.labels(self.command, path).observe(
                time.monotonic() - self._t0)
            super().log_request(code, size)
    
  4. В методе _handle добавь путь /metrics в множество известных routes (иначе он вернёт 404) и обработку рядом с остальными маршрутами. Метод _send уже сам ставит Content-Length:

            if path == "/metrics":
                # generate_latest() отдаёт весь реестр метрик текстом
                return self._send(200, generate_latest(), CONTENT_TYPE_LATEST)
    
  5. Обнови датчики. В main() после initialize_storage() добавь BUILD_INFO.labels(VERSION).set(1) и update_notes_total() (оберни его в try/except STORAGE_ERRORS, чтобы недоступная база не мешала старту), а в _create_note после save_note(text) вызови update_notes_total(). Полный вариант файла: versions/v5.py в эталоне.

  6. Пересобери образ и перезапусти сервис. В compose.yml у сервиса notes укажи image: notes:0.5.0 рядом с build: ., в .env поставь APP_VERSION=0.5.0. Разбор команд: docker build -t notes:0.5.0 . собирает образ из текущего каталога и даёт ему имя и версию; docker compose up -d notes пересоздаёт только сервис notes; grep -E '^(a|b)' печатает строки, начинающиеся на a или b; -k у curl не проверяет самоподписанный сертификат notes.lab (урок 4.6):

    docker build -t notes:0.5.0 .
    docker compose up -d notes
    docker compose -f monitoring/compose.yml exec prometheus wget -qO- http://notes:8080/metrics | grep -E '^(notes_build_info|notes_notes_total)'
    
  7. Дай Prometheus что посчитать и проверь цель. for i in $(seq 10); do ...; done повторяет команду 10 раз (урок 1.6), -X POST -d ... отправляет заметку, >/dev/null выбрасывает ответ. Запрос к Prometheus --data-urlencode 'query=...' передаёт выражение на языке запросов (PromQL, подробно в 8.3): path=~"/notes|/error|other" значит «путь подходит под одно из трёх значений».

    for i in $(seq 10); do curl -sk -X POST https://notes.lab/notes -d '{"text":"метрика"}' >/dev/null; done
    for i in $(seq 3); do curl -sk https://notes.lab/error >/dev/null; done
    for i in $(seq 2); do curl -sk https://notes.lab/nope >/dev/null; done
    sleep 20
    curl -s localhost:9090/api/v1/query \
      --data-urlencode 'query=notes_http_requests_total{path=~"/notes|/error|other"}' \
      | jq -r '.data.result[] | "\(.metric.method) \(.metric.path) \(.metric.status) \(.value[1])"'
    
  8. Проверь up и поведение при остановке сервиса, затем зафиксируй результат:

    docker compose stop notes
    sleep 30
    curl -s localhost:9090/api/v1/query --data-urlencode 'query=up{job="notes"}' | jq -r '.data.result[0].value[1]'
    docker compose start notes
    git add app.py requirements.txt compose.yml monitoring
    git commit -m "Метрики Prometheus: /metrics, monitoring/ (v0.5.0)"
    git tag v0.5.0
    

Что должно получиться:

notes_build_info{version="0.5.0"} 1.0
notes_notes_total 0.0
POST /notes 201 10
GET /error 500 3
GET other 404 2
0

Как читать вывод: первая строка показывает версию сборки в метке. Вторая: число заметок в датчике. Дальше по строке на ряд: метод, путь, статус, счётчик: 10 успешных POST /notes (201), 3 вызова /error со статусом 500, 2 вызова /nope, которые стали other со статусом 404. Последнее значение 0: после stop цель не отвечает и up равен 0.

Значение notes_notes_total зависит от того, сколько заметок уже записано. После docker compose start notes через 15-30 секунд up{job="notes"} вернётся в 1, а счётчики notes_http_requests_total начнут с нуля: процесс перезапустился. Состояние эталона: app.py v5, образ 0.5.0, тег v0.5.0. Метрики доступны и через https://notes.lab/metrics (nginx проксирует всё подряд). Это лишнее: добавь в server с listen 443 файла deploy/nginx/compose.conf блок location = /metrics { deny all; } и примени его пересозданием: docker compose up -d --force-recreate proxy (это надёжнее nginx -s reload: файл смонтирован одиночным bind mount, и после правки редактором контейнер мог остаться со старой копией, урок 4.6). Проверь curl -sk -o /dev/null -w '%{http_code}\n' https://notes.lab/metrics: должно быть 403. Prometheus при этом продолжит ходить на notes:8080 напрямую по сети notes-net, nginx ему не нужен.

Объясни себе:

  • Почему время старта запоминается в parse_request, а не в handle_one_request? (подсказка: keep-alive из HTTP/1.1, урок 2.4)
  • Почему после stop значение up стало 0 не сразу, а через один-два интервала сбора?
  • Что случилось со счётчиками после рестарта и почему на графике это не должно выглядеть провалом скорости?

Типичные ошибки:

  • ModuleNotFoundError: No module named 'prometheus_client' в логах контейнера: пакет не попал в requirements.txt или образ не пересобран. Проверь файл, выполни docker build заново.
  • Duplicated timeseries in CollectorRegistry: {'notes_http_requests_total'}: метрика объявлена дважды (например, объявление попало внутрь метода или файл импортируется повторно). Объявляй метрики один раз на уровне модуля.
  • ValueError: Incorrect label count: labels() вызван с другим числом значений, чем в объявлении. У Counter три метки, у Histogram две.
  • Цель notes остаётся down с server returned HTTP status 404 Not Found: контейнер всё ещё на старом образе. Проверь docker compose ps и тег образа, выполни docker compose up -d notes.

Сломай и почини

В этом разделе ты тренируешь главный навык дежурного: по симптому найти причину. Скрипт сам ломает конфиг стека мониторинга или добавляет лишний источник, не заглядывай в него: диагностика и есть упражнение. Скрипт правит только ~/notes/monitoring/prometheus/prometheus.yml и создаёт один контейнер с меткой break=8.2. Запускай его без sudo, от пользователя, который работает с Docker.

Скачай скрипт. У curl флаг -f означает «при ошибке сервера не сохраняй страницу с ошибкой», -L разрешает переходить по перенаправлениям, -o задаёт имя файла:

curl -fsSL -o /tmp/break-8.2.sh https://raw.githubusercontent.com/distinguished-sre/learning/main/devops/project/notes/break/8.2/break.sh
bash /tmp/break-8.2.sh 1

Сценарии: 1, 2 и 3. Проходи по одному: запусти, найди причину, почини сам или командой bash /tmp/break-8.2.sh fix, потом бери следующий. В конце выполни fix и удали скрипт: rm /tmp/break-8.2.sh. Если стек мониторинга лежит не в ~/notes, задай путь: NOTES_DIR=/путь/к/notes bash /tmp/break-8.2.sh 1.

Симптом

  • Сценарий 1. На странице http://localhost:9090/targets цель notes красная (down), хотя docker compose ps показывает, что приложение работает.
  • Сценарий 2. Цель notes тоже красная, но текст ошибки другой, а curl изнутри контейнера отвечает на /metrics нормально.
  • Сценарий 3. Все цели up, но Prometheus стал заметно тяжелее, а число рядов выросло с сотен до десятков тысяч.

Для каждого сценария запиши, что видишь: текст в поле ошибки цели (lastError), значение up, число рядов.

Гипотезы

Составь список причин, которые дают такой симптом, и проверь их в порядке дешевизны. Например: цель недоступна по сети; путь /metrics отдаёт не 200; какой-то источник отдаёт слишком много рядов; конфиг Prometheus не перечитан.

Проверки

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

# 1. что говорит сам Prometheus о цели (health и lastError)
curl -s localhost:9090/api/v1/targets | jq -r '.data.activeTargets[] | "\(.labels.job)\t\(.health)\t\(.lastError)"'
# 2. отвечает ли приложение изнутри сети мониторинга
docker compose -f monitoring/compose.yml exec prometheus wget -qO- http://notes:8080/metrics | head -5
# 3. сколько всего рядов у метрик приложения
curl -s localhost:9090/api/v1/query \
  --data-urlencode 'query=count({__name__=~"notes_.*"})' | jq -r '.data.result[0].value[1]'
# 4. какие метрики самые «жирные» по числу рядов
curl -s localhost:9090/api/v1/status/tsdb | jq -r '.data.seriesCountByMetricName[:5][] | "\(.name) \(.value)"'
# 5. какая задача даёт эти ряды
curl -s localhost:9090/api/v1/query \
  --data-urlencode 'query=count by (job) ({__name__="notes_http_requests_total"})' | jq -c '.data.result[]'

Разбор: wget -qO- внутри контейнера делает то же, что curl -s снаружи: так ты проверяешь доступность из той же сети, в которой работает Prometheus (с ноутбука всё может выглядеть иначе). count(...) считает ряды, count by (job) считает ряды отдельно по каждой задаче. Команду 2 запускай из ~/notes.

Исправление

Разбор трёх сценариев

Сценарий 1. connection refused. В lastError видно Get "http://notes:8080/metrics" или, в этой поломке, Get "http://notes:8081/metrics": dial tcp 172.18.0.4:8081: connect: connection refused. Имя резолвится (контейнер есть), но на порту 8081 никто не слушает. Приложение слушает 8080: проверь docker compose ps и docker compose logs notes, затем сравни порт в targets файла prometheus.yml с портом приложения и верни 8080. Если бы в ошибке было no such host, это значило бы, что контейнера нет в сети notes-net. После правки docker compose -f monitoring/compose.yml restart prometheus, через 15-30 секунд up = 1.

Сценарий 2. Неверный metrics_path. Цель down с server returned HTTP status 404 Not Found, хотя приложение живо и curl на /metrics внутри контейнера даёт 200. В prometheus.yml у задачи notes появился metrics_path: /metric. Исправь путь (по умолчанию он /metrics, ключ можно вовсе убрать), проверь конфиг через promtool check config и перезапусти Prometheus. Признак, что дело в конфиге, а не в сервисе: curl руками работает, а Prometheus видит 404.

Сценарий 3. Взрыв кардинальности. Все цели up, но count({__name__=~"notes_.*"}) показывает тысячи, а seriesCountByMetricName ставит notes_http_requests_total на первое место. Запрос count by (job) указывает на задачу notes-shadow: это второй источник, который имитирует ошибку разработчика, когда в метку path попал сырой адрес вида /notes/17, и порождает 20 000 разных рядов. В реальной жизни ты бы нашёл виновную метку в коде и вернул route_label(...). Здесь достаточно убрать задачу из prometheus.yml и удалить контейнер break82-shadow (это делает fix). Уже записанные ряды не исчезнут сразу: они станут устаревшими и уйдут по retention, а чтобы очистить сразу на учебном стенде, выполни docker compose -f monitoring/compose.yml down -v (удалит том prom-data и всю историю). Главный вывод: метки метрик должны иметь конечный список значений, а sample_limit в конфиге задачи защищает Prometheus, отбрасывая цели с слишком большим числом рядов.

Убедись, что все три цели up, а docker ps -a --filter label=break=8.2 пуст.

ИИ в помощь

Общие правила работы с ИИ-помощником собраны на странице «ИИ-помощник», здесь только сценарии этой темы.

Задача: разобрать цель, которая показывает down.

В Prometheus цель notes в статусе down, lastError: Get "http://notes:8081/metrics": dial tcp 172.18.0.4:8081: connect: connection refused. Приложение слушает порт 8080 в Docker Compose-сети notes-net. Объясни построчно, что означает ошибка, и назови 2-3 места, где искать причину.

Проверь ответ: connection refused значит, что имя найдено, а порт закрыт. Типичная ошибка нейросетей: советовать «проверить DNS» или перезапустить Prometheus. Сверь адрес с prometheus.yml и портом приложения.

Задача: выбрать тип метрики и имя.

В приложении «Заметки» нужны метрики: число отправленных писем, текущее число открытых соединений с базой, время выполнения SQL-запроса. Для каждой назови тип (counter, gauge, histogram), имя по правилам Prometheus и набор меток с оценкой кардинальности.

Проверь ответ: у счётчика имя оканчивается на _total, у времени единица в секундах (_seconds), в метках нет неограниченных значений вроде user_id. Нейросети часто предлагают миллисекунды и метку с адресом запроса целиком.

Задача: проверить конфиг prometheus.yml перед запуском.

Вот мой prometheus.yml: <вставь файл без паролей>. Найди ошибки отступов и ключей, объясни, что делает каждый блок, и скажи, какой командой проверить файл до запуска.

Проверь ответ: проверь, что нейросеть назвала promtool check config, а не выдуманный флаг. Типичная ошибка: заменить имя контейнера на localhost, из-за чего цель перестаёт находиться.

Словарик урока

Термин Простыми словами
Сэмпл (sample) Одна точка ряда: момент времени и число
Ряд (series) Метрика с конкретным набором меток
Состояние цели (health), lastError up или down на странице Targets и текст последней ошибки сбора
scrape_timeout Сколько Prometheus ждёт ответа цели; не больше интервала
Prometheus Программа, которая по расписанию собирает метрики и хранит их во времени
Pull Схема, при которой сборщик сам приходит за данными, а не ждёт, пока их пришлют
Цель (target) Один адрес, откуда собирают метрики, например notes:8080
Задача (job) Группа однотипных целей; становится меткой job
Экземпляр (instance) Конкретный адрес цели внутри задачи; метка instance
Scrape Один сбор метрик с цели: HTTP-запрос и разбор ответа
scrape_interval Как часто собирать; у нас 15 секунд
/metrics Страница приложения с текущими числами в текстовом формате
Формат exposition Текстовый формат /metrics: # HELP, # TYPE и строки имя{метки} значение
Метрика up Метрика, которую Prometheus сам пишет про цель: 1 ответила, 0 нет
Временной ряд Последовательность пар «время, число» для одного имени и набора меток
Метка (label) Пара имя="значение", которая делит метрику на группы
Кардинальность Число уникальных комбинаций значений меток, то есть число рядов
Counter Счётчик: только растёт, при перезапуске обнуляется
Gauge Датчик: значение идёт вверх и вниз
Histogram Распределение значений по корзинам: _bucket, _sum, _count
Корзина (bucket, le) Диапазон гистограммы с верхней границей; корзины кумулятивные
Summary Сводка с квантилями, посчитанными в приложении; в новом коде редко
Staleness Пометка ряда устаревшим: когда цель исчезла или сбор не удался, запрос перестаёт возвращать её ряды
Lookback delta Окно в 5 минут: ряд без пометки устаревания (push, федерация) запрос ещё отдаёт по последней точке
TSDB, retention База временных рядов Prometheus и срок хранения данных (по умолчанию 15 дней)
Exporter Программа-переводчик: читает чужую систему и отдаёт /metrics
node_exporter, cAdvisor Экспортёры метрик хоста и метрик контейнеров
Pushgateway Шлюз для короткоживущих задач: они отправляют туда итог, Prometheus забирает
Service discovery Автоматический поиск целей (в Kubernetes, 8.9)
promtool Утилита проверки конфигов Prometheus

Вопросы с собеседований

Раздел для повторения: ответь вслух, потом открой ответ. Вопросы с пометкой «часто» задают почти на каждом собеседовании по теме урока: начни с них.

1. [junior] [часто] Чем pull-модель Prometheus отличается от push и в чём плюсы pull?

Ответ

Prometheus сам ходит по целям (targets) и забирает метрики с /metrics через заданный интервал, это и есть pull. Push - когда приложение само отправляет данные в хранилище. У pull есть плюсы: по up сразу видно, что сбор с цели не удался (up 0: цель лежит или отдаёт мусор вместо метрик; up 1 ещё не значит, что приложение здорово), метрики можно открыть в браузере или через curl, а нагрузку на сбор контролирует сервер, а не клиенты. Цели находятся через service discovery (автоматический поиск целей, например в Kubernetes). Push нужен для коротких пакетных задач, которые успевают завершиться между опросами: для них есть Pushgateway, но это исключение, а не норма. Старые значения в нём не исчезают сами, их удаляют явно.

Что хотят услышать: Prometheus сам опрашивает /metrics, метрика up как проверка живости цели, service discovery, контроль нагрузки на стороне сервера, Pushgateway только для короткоживущих задач.

Красный флаг: «Prometheus принимает метрики от приложений» без оговорок или совет слать всё через Pushgateway.

2. [junior] [часто] Чем counter отличается от gauge и что у них происходит при рестарте процесса?

Ответ

Counter только растёт: число запросов, число ошибок. Gauge показывает текущее значение: размер очереди, память. При рестарте процесса счётчик сбрасывается в 0, датчик принимает новое текущее значение. Поэтому по счётчику смотрят rate(), а не значение.

Что хотят услышать: примеры для каждого типа, сброс счётчика, что rate его обрабатывает.

Красный флаг: «счётчик может уменьшаться» или использование gauge для числа запросов.

3. [junior] Коллега предлагает слать метрики из cron-скрипта прямо в Prometheus. Что скажешь?

Ответ

Prometheus сам забирает метрики по HTTP (pull); приём пуша (remote write, OTLP) по умолчанию выключен и для коротких скриптов не применяется. Скрипт живёт секунды, его не успеют опросить. Для таких задач в конце скрипта отправляют итог в Pushgateway, а Prometheus собирает уже Pushgateway. Но это для коротких задач, обычные сервисы остаются на pull.

Что хотят услышать: pull-модель, Pushgateway для короткоживущих задач, оговорку, что у Pushgateway нет автоматической очистки старых значений и up показывает живость шлюза, а не задачи.

Красный флаг: «просто поставим там push вместо pull» без понимания, зачем Prometheus ходит сам.

4. [junior] В Prometheus цель красная (DOWN). Твои действия

Ответ

Сначала смотрю страницу /targets и текст lastError. connection refused значит, что процесс не слушает порт; no such host значит, что нет имени в сети; context deadline exceeded значит, что цель не успела ответить за таймаут; 404 значит, что неверный metrics_path. Потом иду curl-ом к цели из той же сети, где работает Prometheus.

Что хотят услышать: разбор по тексту ошибки, проверка из сети самого Prometheus (а не с ноутбука), сверка порта и metrics_path, статус up.

Красный флаг: «перезапущу Prometheus» без чтения ошибки.

5. [junior] [на скорость] После деплоя график requests_total упал в ноль. Это баг?

Ответ

Скорее всего нет: процесс перезапустился, и счётчик обнулился. rate() и increase() замечают такой сброс и не показывают провала. Проверяю, что цель снова up, и смотрю на скорость запросов, а не на сырое значение.

Что хотят услышать: сброс счётчика, rate против сырого значения, проверка up и времени старта процесса.

Красный флаг: «откатим релиз», не посмотрев на график скорости.

6. [middle] Prometheus падает по OOM. Память растёт после вчерашнего релиза. Что делаешь?

Ответ

Подозреваю рост кардинальности: в метку попало что-то неограниченное. Сначала смотрю число рядов и самые «тяжёлые» метрики безопасным путём: страница Status > TSDB Status (/tsdb-status) в UI или /api/v1/status/tsdb. Тяжёлый запрос topk(10, count by (__name__)({__name__=~".+"})) по всем рядам запускаю только после стабилизации: на Prometheus, который и так падает по памяти, он сам может его добить. Нахожу метрику и метку, откатываю или исправляю код, чтобы значения были из конечного списка. Временно поднимаю лимит памяти, но это не лечение.

Что хотят услышать: кардинальность, seriesCountByMetricName, связь с релизом, чистка на стороне приложения, а не «добавить памяти». Плюс упоминание, что можно ограничить ряды на цель параметром sample_limit.

Красный флаг: «увеличу память и retention», без поиска причины.

7. [middle] Алерт «ошибок больше порога» молчит, а сервис лежит. Почему?

Ответ

Если сервис не отвечает, ряды notes_http_requests_total перестают приходить, и после первого неудачного сбора Prometheus сразу помечает их устаревшими. Выражение ... > порога на пустом множестве ничего не возвращает, и алерт не срабатывает. Пропажу ловят отдельным алертом на up == 0 (или на absent()), это обязательная пара к алертам по значениям.

Что хотят услышать: staleness, пустой результат вместо нуля, up == 0, absent, for.

Красный флаг: «у алерта неправильный порог».

8. [middle] Какие корзины выбрать для гистограммы задержек и что будет, если выбрать плохо?

Ответ

Корзины должны покрывать реальные задержки и границы SLO (например, есть корзина ровно на пороге 0.5 с). Если все запросы по 20 мс, а первая корзина 100 мс, то p95 окажется где-то внутри неё, оценка будет грубой (квантиль вычисляется интерполяцией внутри корзины). Слишком много корзин раздувают число рядов: каждая корзина это ряд на каждую комбинацию меток.

Что хотят услышать: интерполяция внутри корзины, корзина на границе SLO, цена за каждую корзину, что менять корзины потом больно.

Красный флаг: «корзины любые, Prometheus разберётся».

9. [middle] Единственный Prometheus упал ночью, на графиках дыра. Как сделать надёжнее?

Ответ

Первый шаг: два одинаковых Prometheus, которые собирают одни и те же цели независимо (HA-пара), с постоянным диском и алертом на up Prometheus с соседней реплики. Упавший Prometheus ничего не пошлёт сам, поэтому за ним следит соседняя реплика или внешний dead man’s switch (Watchdog, разберём в 8.5). Вторая проблема: данные у каждого свои, а графики надо смотреть с одного из них. Для долгого хранения и единого запроса добавляют Thanos, Mimir или VictoriaMetrics с записью в объектное хранилище (remote write). Начинаю с одного узла и разумным retention, пока он не упирается в объём.

Что хотят услышать: независимые реплики, а не кластер; персистентный том; внешнее хранилище для долгой истории; не усложнять раньше времени.

Красный флаг: «Prometheus кластеризуется из коробки».

10. [middle] [на скорость] Метрики CronJob пропадают, между запусками в Prometheus пусто. Что делать?

Ответ

Задача живёт слишком мало, поэтому её не успевают опросить. Решение: Pushgateway. Джоб перед завершением отправляет туда gauge last_success_timestamp и длительность, Prometheus забирает их у шлюза. Алерт строится на возрасте последнего успеха, а не на самой метрике.

Что хотят услышать: Pushgateway, метрику «время последнего успеха», оговорку про застывшие значения, алерт по возрасту.

Красный флаг: «уменьшим scrape_interval до секунды».

11. [junior] Что такое job и instance и откуда они берутся?

Ответ

Prometheus сам добавляет к каждой собранной метрике два лейбла. job берётся из имени задачи в scrape_configs, instance - это адрес цели в виде хост:порт. По ним можно выделить один сервис или один конкретный под. Отдельно Prometheus для каждой цели записывает метрику up: 1, если сбор прошёл, 0, если нет. Поэтому в PromQL я начинаю диагностику с up == 0 и смотрю, у каких job и instance сбор сломан.

Что хотят услышать: job из scrape config, instance как хост:порт, метрика up, использование для диагностики.

Красный флаг: «лейблы job и instance пишет приложение в /metrics».

12. [middle] Сколько Prometheus хранит данные и что делать, если нужен год истории?

Ответ

Данные лежат в локальной TSDB на диске, по умолчанию хранятся 15 дней, срок меняет флаг --storage.tsdb.retention.time, а объём ограничивает --storage.tsdb.retention.size. Локальное хранилище не рассчитано на годы и на отказоустойчивость. Для долгой истории я настраиваю remote_write в отдельное хранилище: Thanos, Mimir, VictoriaMetrics или похожее. Чаще всего для графиков за год хватает агрегатов recording rules, а не сырых данных. Диск под Prometheus я считаю заранее: число рядов, интервал сбора и срок хранения.

Что хотят услышать: локальная TSDB, 15 дней по умолчанию, флаги retention, remote_write для долгого хранения, планирование диска.

Красный флаг: просто поставить срок хранения в 5 лет на маленьком диске.

Проверено на версиях

  • Задание 1 (demo.py) запущено с prometheus_client 0.26.0 на Python 3.9 (macOS): вывод в уроке взят из прогона, заголовки # HELP и # TYPE для клиента 0.26.0 тоже.
  • promtool check config выполнен на prom/prometheus:v3.15.0 для prometheus.yml из задания 2: конфиг валиден.
  • Prometheus v3.15.0, node_exporter v1.12.1, cAdvisor v0.60.6 (образ из ghcr.io, в gcr.io новые версии не публикуются): образы в этом уроке не запускались, compose.yml не прогонялся, вывод targets и запросов в заданиях 2 и 3 ориентировочный и не снят с настоящего стенда: имена метрик cAdvisor и метки job сверяй со своим /metrics.
  • app.py v5 приведён к эталону project/notes/versions/v5.py (фрагменты уроков сверены с ним), в контейнере не запускался.
  • Скрипт поломок break/8.2/break.sh: проверен shellcheck, не запускался.
  • Python: 3.12 в Ubuntu 24.04 и 3.14 в 26.04 (проверено для клиента только на 3.9), Docker Compose без ключа version:.

Итог урока: ты умеешь

  • умею объяснить, почему Prometheus собирает метрики сам (pull) и что означает up
  • умею прочитать /metrics руками и разобрать # HELP, # TYPE, корзины гистограммы
  • умею отличить counter, gauge и histogram и выбрать тип под задачу
  • умею поднять Prometheus, node_exporter и cAdvisor в Compose и подключить их к сети «Заметок»
  • умею проверить конфиг через promtool check config и по lastError найти причину DOWN
  • умею добавить /metrics в приложение с ограниченным набором значений меток
  • умею находить взрыв кардинальности по числу рядов и status/tsdb

Дальше: Урок 8.3: PromQL: rate, агрегации, квантили

Проверь себя

Короткий тест по уроку: 5 вопросов из банка в 30. Засчитывается только полностью правильный ответ, порог 60%. Каждая новая попытка даёт другие вопросы, пока банк не закончится. Ответы видны после проверки.

Тест работает с включённым JavaScript.

тема 8 урок 8.2 4 ч курс 0/0 ← → уроки

Помоги улучшить курс

Что нужно изменить?