Первый запуск:
Prometheus и FastAPI

Категория

Практика

Уровень

Начальный

Нужно

Docker Desktop или Docker Engine с Compose v2; браузер

Результат

Target UP, запросы up и http_requests_total

§1Состав стенда

Пять глав модуля описывали путь числа по частям. В этой главе весь путь запускается на вашем компьютере. Стенд — папка prometheus-start из архива модуля. В ней приложение, настройки Prometheus и файлы для Docker. Python на компьютере для основного варианта не нужен.

↓ Скачать prometheus-start.zip

Человек обращается к обоим контейнерам с компьютера, а Prometheus обращается к приложению внутри сети по имени api. Почему адреса разные, объясняла глава 2.2. Теперь по порядку: какие файлы лежат в папке и по каким адресам открывается стенд.

Файлы стенда

Три файла в дереве выделены: в них находится всё, что относится к метрикам. Остальные нужны для сборки образа и для опытов.

Адреса стенда

Номера 8020 и 9092 выбраны потому, что порты 8000 и 9090 часто заняты другими программами и стендом модуля 1. Оба порта открыты только на адресе 127.0.0.1, поэтому с других компьютеров сети стенд недоступен.

Из трёх выделенных файлов первым разобрано приложение: в нём числа появляются.

§2Приложение app.py

Приложение стенда делает две вещи: отдаёт товар по номеру и считает собственные запросы. Счёт ведётся в одном месте, через которое проходят все запросы, и сначала показано, как это место устроено.

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

Код приложения

Ниже — рабочая часть файла. В полном файле есть ещё три адреса для опыта с ошибками из главы 2.4: /metrics/slow, /metrics/broken, /metrics/html. Рабочая конфигурация к ним не обращается.

from fastapi import FastAPI, Request
from fastapi.responses import PlainTextResponse, Response
from prometheus_client import (
    CONTENT_TYPE_LATEST, CollectorRegistry, Counter,
    disable_created_metrics, generate_latest,
)

disable_created_metrics()
registry = CollectorRegistry()

HTTP_REQUESTS = Counter(
    "http_requests_total",
    "Total HTTP requests",
    ["method", "status"],
    registry=registry,
)

SERVICE_PATHS = {"/metrics", "/metrics/slow", "/metrics/broken", "/metrics/html"}

app = FastAPI(title="Prometheus start")


@app.middleware("http")
async def count_requests(request: Request, call_next):
    response = await call_next(request)
    if request.url.path not in SERVICE_PATHS:
        HTTP_REQUESTS.labels(request.method, str(response.status_code)).inc()
    return response


@app.get("/items/{item_id}")
async def get_item(item_id: int):
    if item_id > 100:
        return PlainTextResponse("not found", status_code=404)
    return {"item_id": item_id}


@app.get("/metrics")
async def metrics():
    return Response(generate_latest(registry), media_type=CONTENT_TYPE_LATEST)

В таблице каждая существенная строка разобрана дважды: что она делает и что изменится в ответе /metrics, если её убрать.

Разбор по строкам

>>> from prometheus_client import Counter, CollectorRegistry, generate_latest
>>> r = CollectorRegistry()
>>> c = Counter("demo_total", "Demo", ["method"], registry=r)
>>> c.labels("GET").inc(); c.labels("GET").inc()
>>> print(generate_latest(r).decode())
# HELP demo_total Demo
# TYPE demo_total counter
demo_total{method="GET"} 2.0
# HELP demo_created Demo
# TYPE demo_created gauge
demo_created{method="GET"} 1.790692138359471e+09

>>> c.labels("GET").inc(-1)
Traceback (most recent call last):
  ...
ValueError: Counters can only be incremented by non-negative amounts.

Приложение считает числа и отдаёт их по запросу. Теперь нужен тот, кто будет запрашивать, и это описывают два файла настроек.

§3Конфигурация и Compose

На стенде два файла настроек. Файл prometheus.yml разобран в главе 2.2: одно задание api, target api:8000, интервал 15 секунд, timeout 10 секунд.

Файл compose.yaml описывает, какие контейнеры запустить. Docker Compose — программа, которая запускает несколько контейнеров одной командой и объединяет их в сеть.

name: prometheus-start
services:
  api:
    build: .
    ports: ['127.0.0.1:8020:8000']

  prometheus:
    image: prom/prometheus:v3.5.0
    command:
      - --config.file=/etc/prometheus/${PROM_CONFIG:-prometheus.yml}
      - --storage.tsdb.path=/prometheus
      - --web.enable-lifecycle
    ports: ['127.0.0.1:9092:9090']
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
      - ./prometheus-errors.yml:/etc/prometheus/prometheus-errors.yml:ro
      - prometheus-data:/prometheus
    depends_on: [api]

volumes:
  prometheus-data:

Все три выделенных файла разобраны. Остальное делается командами.

§4Запуск

Файлы разобраны, и стенд можно запускать. Запуск состоит из пяти шагов: запустить контейнеры, проверить их, отправить запросы к приложению, открыть страницу /metrics и открыть Prometheus. Команды выполняются в папке prometheus-start. Переключатель системы вверху страницы показывает команды для вашей операционной системы. В macOS и Linux команды одинаковые.

1. Собрать образ приложения и запустить оба контейнера. При первом запуске Docker скачивает образы Python и Prometheus. Это занимает от одной до нескольких минут.

   docker compose up -d --build

2. Проверить, что контейнеры работают.

   NAME                            IMAGE                    STATUS             PORTS
   prometheus-start-api-1          prometheus-start-api     Up 17 seconds      127.0.0.1:8020->8000/tcp
   prometheus-start-prometheus-1   prom/prometheus:v3.5.0   Up About an hour   127.0.0.1:9092->9090/tcp

3. Отправить запросы к приложению. До первого запроса у счётчика нет ни одного ряда (глава 2.3, §5). Команды отправляют 20 запросов к товарам и один запрос к несуществующему товару.

   for i in $(seq 1 20); do curl -s -o /dev/null http://localhost:8020/items/$i; done
   curl -s -o /dev/null http://localhost:8020/items/500

   1..20 | ForEach-Object { Invoke-WebRequest -UseBasicParsing "http://localhost:8020/items/$_" | Out-Null }
   curl.exe -s -o NUL http://localhost:8020/items/500

4. Посмотреть страницу /metrics. В Windows пишут curl.exe: в PowerShell слово curl обозначает другую команду.

   # HELP http_requests_total Total HTTP requests
   # TYPE http_requests_total counter
   http_requests_total{method="GET",status="200"} 20.0
   http_requests_total{method="GET",status="404"} 1.0

5. Открыть Prometheus: http://localhost:9092, меню Status → Target health.

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

§5Status → Target health

На этой странице Prometheus показывает все target и результат последнего scrape каждого. Ниже — страница стенда и разбор её элементов.

В колонке State бывает три значения. Сразу после запуска там стоит UNKNOWN: target уже в списке, но первого scrape ещё не было, и ждать его приходится до 15 секунд. После успешного scrape состояние становится UP, и ряд up равен 1. После неуспешного — DOWN: ряд up равен 0, а рядом записан текст ошибки.

Target в состоянии UP означает, что числа попадают в базу. Следующий шаг — получить их оттуда запросом.

§6Первые запросы

Запросы пишут на вкладке Query. В этой главе достаточно одного вида запроса — имени метрики. Такой запрос возвращает все ряды с этим именем.

Результат показывается двумя способами. Вкладка Table показывает последнее значение каждого ряда. Вкладка Graph показывает, как значения менялись.

Пять запросов для начала

Почему число обновляется не сразу

Prometheus показывает значения последнего scrape. Если отправить 10 запросов и сразу нажать Execute, число может остаться прежним. Новое значение появится после следующего scrape, не позже чем через 15 секунд.

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

§7Остановка приложения

Опыт повторяет главу 2.4, §8 на вашем компьютере. В нём приложение останавливается и запускается снова, а Prometheus продолжает работать.

1. Остановить приложение: docker compose stop api.
2. Через 15–30 секунд обновить страницу Target health. Состояние стало DOWN, под target записан текст ошибки. На стенде в Docker Desktop это был текст EOF, затем context deadline exceeded. В другом окружении текст может отличаться.
3. На вкладке Query выполнить запрос up: значение 0. Затем запрос http_requests_total: пустой результат.
4. Запустить приложение: docker compose start api. После следующего scrape состояние станет UP. Запрос http_requests_total возвращает пустой результат до первого запроса к приложению: счётчик после запуска начинается заново.
5. На вкладке Graph выполнить запрос up за 5 минут. На графике значение опускается до 0 на время остановки.

Опыт подтверждает четыре наблюдения из главы 2.4: ряд up записывается и во время остановки, ряд приложения прерывается сразу, а счётчик после запуска начинается заново.

Остановка была намеренной. Следующий раздел помогает, когда target не работает без видимой причины.

§8Если target не UP

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

Проверка файла настроек

Файл настроек проверяет программа promtool. Она входит в образ Prometheus. Проверку выполняют до перезагрузки настроек.

$ docker compose exec prometheus promtool check config /etc/prometheus/prometheus.yml
Checking /etc/prometheus/prometheus.yml
 SUCCESS: /etc/prometheus/prometheus.yml is valid prometheus config file syntax

Все случаи выше относятся к запуску в Docker. Если Docker недоступен, стенд запускается иначе.

§9Вариант без Docker

Когда Docker недоступен, приложение и Prometheus запускают как обычные программы. Вариант проверен в macOS с архивом prometheus-3.5.0.darwin-arm64: target localhost:8020 получил состояние UP.

1. Скачать архив Prometheus 3.5.0 для своей системы со страницы prometheus.io/download и распаковать. В архиве — программы prometheus и promtool.
2. В папке стенда создать окружение Python и установить зависимости: python -m venv .venv, затем .venv/bin/pip install -r requirements.txt (в Windows — .venv\Scripts\pip).
3. Запустить приложение: .venv/bin/uvicorn app:app --port 8020.
4. Во втором окне терминала запустить Prometheus с файлом настроек стенда: ./prometheus --config.file=prometheus-local.yml. Веб-интерфейс откроется по адресу http://localhost:9090. Данные сохраняются в папке data рядом с программой.

В файле prometheus-local.yml записан target localhost:8020. Обе программы работают на одном компьютере, и localhost у них общий.

Стенд запущен одним из двух способов. Осталось проверить результат и поработать с ним самостоятельно.

§10Задания и проверка

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

Задания

В каждом задании меняется одна настройка. Результат проверяется в веб-интерфейсе Prometheus.

1. Интервал. Установите в prometheus.yml scrape_interval: 5s, перезагрузите конфигурацию и выполните up[1m]. Сколько значений стало за минуту и какой scrape_timeout показывает страница Status → Configuration?
2. Метка target. Добавьте target метку env: dev (глава 2.2, §5). На каких рядах она появилась?
3. Ошибка пути. Добавьте в задание metrics_path: /stats. Запишите текст ошибки и найдите, что изменилось в ответе /metrics приложения через минуту.
4. Вторая метрика. Добавьте в app.py gauge items_in_progress, который увеличивается в начале обработки /items/{id} и уменьшается в конце. Пересоберите образ (docker compose up -d --build) и найдите метрику в Query.

Итоговый стенд

В архиве prometheus-final собран готовый результат главы: все задания выполнены, для каждого опыта есть свой файл настроек. Стенд запускается теми же командами, что и основной.

↓ Скачать prometheus-final.zip

Порядок работы с итоговым стендом записан в файле PROHOD.md. Первые четыре шага повторяют запуск из этой главы. На пятом шаге проверяется вторая метрика: пять долгих запросов поднимают значение gauge до 5, затем оно возвращается к 0. Шестой шаг — остановка приложения. Шаги с седьмого по девятый — опыты с настройками: интервал 5 секунд, неверный путь и шесть заданий с ошибками. Основной и итоговый стенды занимают порты 8020 и 9092, поэтому перед запуском одного остановите другой командой docker compose down.

Шпаргалка

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