inferwatch

Метрики в реальном времени и за прошлые периоды для локально развёрнутых LLM — Ollama и vLLM — с браузерным дашбордом, экраном настроек и MCP-сервером, чтобы агент мог запрашивать те же данные.

Один процесс Python, один файл SQLite. Никаких Docker, Node, Prometheus и внешних сервисов. Он никогда не находится на пути запроса, поэтому не может замедлить или нарушить инференс.

┌── Ollama ──────────────┐        ┌── vLLM ────────────────┐
│ journald / file /      │        │ GET /metrics           │
│ docker logs            │        │ (native Prometheus)    │
└──────────┬─────────────┘        └──────────┬─────────────┘
           │ per-request rows                │ pre-aggregated
           ▼                                 ▼
        ┌──────────────── SQLite (WAL) ────────────────┐
        │  requests · rollups · vllm_samples/hist      │
        └───────┬──────────────────────────┬───────────┘
                ▼                          ▼
         dashboard :7070            MCP server (stdio)

Два движка несимметричны, и инструмент не утверждает обратного

Это центральный факт архитектуры, поэтому его стоит сформулировать прямо.

Обе вкладки показывают загрузку GPU, видеопамять, температуру и потребляемую мощность, поскольку они измеряются через nvidia-smi, а не каким-либо из движков. Температура и мощность получают отдельные графики, а не общую ось, и каждая агрегируется так, как требует её единица измерения: загрузка усредняется по картам, видеопамять и ватты суммируются, температура показывает самую горячую карту. Температура — единственный ряд, который строится не от нуля: диапазон 33–68 °C, начинающийся с 0, занимал бы большую часть графика впустую.

Поэтому для них предусмотрены отдельные вкладки дашборда, отдельные таблицы и отдельные MCP-инструменты. Не предпринимается попыток восстановить построчные данные по запросам для vLLM путём вычитания счётчиков: невозможно определить, какому запросу принадлежал тот или иной TTFT, а подделка поставила бы выдуманные строки рядом с настоящими.

Ollama: откуда берутся числа

Ollama не предоставляет эндпоинт /metrics (проверено — такого маршрута нет в бинарнике). При OLLAMA_DEBUG=1 встроенный llama.cpp печатает блок таймингов для каждого запроса, который объединяется со строкой доступа и строкой планировщика:

slot print_timing: id 0 | task 6763 | prompt eval time = 1254.52 ms /  55 tokens
slot print_timing: id 0 | task 6763 |        eval time = 14591.31 ms / 416 tokens
[GIN] ... | 200 | 16.862061865s | 192.0.2.10 | POST "/v1/chat/completions"
time=... msg="context for request finished" runner.name=.../llama3.2:3b

Это даёт TTFT, разбивку prefill/decode, количество токенов, скорость декодирования, статус, клиента, эндпоинт и модель — для каждого запроса, от любого клиента, не затрагивая путь запроса. Из объединения получаются два числа, которых нет ни у одного источника по отдельности:

• ожидание в очереди = реальная задержка − время работы раннера: время, потраченное на ожидание, а не на генерацию. Прокси не может разделить эти величины.

• повторное использование кэша промпта = полная длина промпта − фактически обработанные токены.

Требуется OLLAMA_DEBUG=1. Без него llama.cpp не печатает строки таймингов: частоты запросов, статусы и метрики GPU по-прежнему работают, но TTFT и количество токенов остаются пустыми. Дашборд сообщает об этом в баннере, а не показывает нули.

# /etc/systemd/system/ollama.service.d/override.conf
[Service]
Environment="OLLAMA_DEBUG=1"

vLLM: откуда берутся числа

Собственный эндпоинт Prometheus у vLLM опрашивается каждые collection.scrape_interval_s (по умолчанию 10 с). Кумулятивные счётчики преобразуются в разности; корзины гистограмм — в разности по каждой корзине; и то и другое сохраняется агрегированно по минутам, потому что хранение каждого опроса добавляло бы миллионы строк в месяц с разрешением, которое не использует ни один график.

Три детали, о которых стоит знать:

• Собственные границы корзин vLLM хранятся вместе со счётчиками. Его границы идут с шагом 1мс/20мс/250мс/2,5с/40с/640с; у Ollama шаг 25мс/200мс/1,5с/15с/60с. Ни одна не является уточнением другой, поэтому перекладывание одной в другую потребовало бы интерполяции между границами — то есть выдумывания чисел. Перцентили вычисляются по собственным границам каждого источника и сообщаются как верхние границы корзин.

• _sum и _count точны, поэтому среднее точно. Поскольку корзины vLLM грубые в диапазоне секунд, дашборд и MCP-инструменты выводят на первое место среднее, а перцентили помечают как «не более».

• Перезапуски обнаруживаются через process_start_time_seconds (а также по счётчику, идущему в обратную сторону). Интервал, охватывающий перезапуск, отбрасывается, а не выдаётся как ложная дельта.

Межтокенная задержка в разных версиях vLLM называлась time_per_output_token_seconds, inter_token_latency_seconds и request_time_per_output_token_seconds. Собираются все варианты, и используется тот, в котором есть данные, так что это работает со старыми и новыми серверами без настройки.

Related MCP server: System Monitor MCP Server

Установка

Требуется Python 3.10 или новее — не из-за этого кода (он совместим с 3.9), а потому что fastapi, uvicorn, starlette и mcp требуют именно его.

pip install git+https://github.com/floatsmyboat/inferwatch     # or:
git clone https://github.com/floatsmyboat/inferwatch && cd inferwatch
python3 -m venv --upgrade-deps .venv && .venv/bin/pip install -e ".[dev]"

Установка даёт вам две команды:

Пока нет на PyPI; устанавливайте из git.

Выполните обратное заполнение из уже имеющегося журнала, затем посмотрите базу данных:

inferwatch ingest --since 2d      # or: python -m inferwatch.main ingest
inferwatch stats

Запустите:

inferwatch serve                  # http://127.0.0.1:7070

Как служба — юнит формируется из systemd/inferwatch.service.in для текущего пользователя, пути к checkout и интерпретатора, так что ничего не зашито жёстко:

./scripts/install-systemd.sh          # system service (uses sudo)
sudo systemctl enable --now inferwatch

./scripts/install-systemd.sh --user   # or per-user, no sudo
systemctl --user enable --now inferwatch

Переопределите с помощью HOST=0.0.0.0 PORT=7070 DATADIR=... ./scripts/install-systemd.sh.

Доступ по сети

Аутентификации нет. Дашборд доступен только для чтения (только GET) и не хранит тексты промптов и ответов — только счётчики, тайминги, имена моделей и адреса клиентов. Ограничьте доступ на межсетевом экране:

sudo ufw allow from 192.168.1.0/24 to any port 7070 proto tcp comment "inferwatch"

Настройка того, что отслеживается

Всё можно изменить на вкладке Настройки дашборда или из CLI:

python -m inferwatch.main sources                       # list
python -m inferwatch.main sources add --kind vllm --name qwen \
    --set url=http://127.0.0.1:8000
python -m inferwatch.main sources add --kind ollama --name box \
    --set reader=file --set path=~/.ollama/logs/server.log
python -m inferwatch.main sources disable qwen

Читатели журналов Ollama. Не все запускают Ollama под systemd:

Читатель file следит за файлом как tail -F, переживая ротацию (смену inode) и усечение, и сохраняет смещение, чтобы перезапуск не приводил к повторному чтению. Go-строки Ollama содержат time=, но строки slot от llama.cpp — те, что содержат количество токенов, — не имеют временной метки, поэтому переносится самая последняя из виденных. Порядок, от которого зависят объединения, сохраняется всегда; абсолютная точность ниже, чем у journald, а строка [GIN] с разрешением в секунду поджимается вперёд, чтобы время никогда не выглядело идущим назад.

Приоритет настроек

spec default  <  database (Settings tab)  <  environment  <  command line

Ключ, заданный через переменную окружения или флаг, отображается только для чтения на вкладке «Настройки» с указанием источника, потому что процессу было сказано использовать его, и браузер не должен молча это переопределять. Сохранение выполняется по принципу «всё или ничего», поэтому опечатка в одном поле не может оставить частично применённую конфигурацию. Изменения источников, интервалов и срока хранения применяются без перезапуска; server.host и server.port помечены как требующие перезапуска, и API сообщает об этом после сохранения.

Справочник по конфигурации

Каждый параметр ниже можно изменить на вкладке «Настройки», задать через переменную окружения, а некоторые можно задать флагом. Таблицы генерируются из кода (scripts/gen-config-docs.py), поэтому они не могут разойтись с тем, что программа действительно принимает.

Сгенерировано scripts/gen-config-docs.py — не редактируйте вручную.

Сбор данных

Хранение

Дашборд

Сервер

Поля источника

Задайте их с помощью --set key=value в sources add или на вкладке Settings.

Ollama (--kind ollama)

vLLM (--kind vllm)

Флаги командной строки

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

Область действия: один источник Ollama, много источников vLLM

Строки vLLM везде привязаны к источнику, поэтому можно одновременно отслеживать любое количество экземпляров vLLM. Таблицы Ollama (requests, events, ps_samples) не разделены по источникам, поэтому одновременно работает ровно один источник Ollama; включение второго приводит к предупреждению и игнорированию, а не к незаметному смешиванию двух экземпляров в один набор чисел. Разделение этих таблиц — изменение схемы, которое стоит сделать осознанно.

Дашборд

http://127.0.0.1:7070 — три вкладки: Ollama, vLLM, Settings.

Какие GPU принадлежат какому движку

На хосте часто работает несколько движков, поэтому отображение каждой карты на панели экземпляра означало бы, что он использует все. GPU каждого экземпляра vLLM определяются по процессам: порт, который он обслуживает → pid, слушающий порт → его потомки → пересечение с вычислительными процессами nvidia-smi → карты, которые они занимают. Карты экземпляра несут цвет серии, и плитка VRAM учитывает только их; остальные карты хоста остаются видимыми серым цветом с подписью «другой движок».

Для атрибуции нужны ss, локальный экземпляр и видимость процессов nvidia-smi (часто отсутствует внутри контейнеров). Если чего-то из этого нет, панель сообщает об этом и показывает все карты без выделения, а не угадывает.

Одна строка фильтра ограничивает всё, что ниже. У каждого графика есть переключатель Table, показывающий те же ряды в виде чисел, так что ни одно значение не доступно только при наведении. Живой SSE-поток управляет бегущей строкой запросов и показателем текущей скорости.

Параметры URL: ?tab=vllm, ?window=6h, ?model=llama3.2:3b, ?source=name, ?nostream=1 (отключает живой поток — полезно для киосков и инструментов создания скриншотов, которые иначе ждут вечно открытый поток).

API

/api/sources/probe проверяет определение до сохранения, поэтому опечатка проявится там, а не как тишина на графиках.

MCP-сервер

./scripts/install-mcp.sh      # writes .mcp.json for this checkout (gitignored)

или claude mcp add inferwatch -- /path/to/.venv/bin/python -m inferwatch.mcp_server.

Открывает тот же файл SQLite только для чтения (mode=ro плюс PRAGMA query_only) и отвечает через тот же слой запросов, что и дашборд, поэтому число, которое он сообщает, всегда совпадает с числом на экране.

Хранение данных

• Сырые строки по запросам (Ollama): 7 дней (retention.raw_days).

• Сэмплы GPU, события, строки vLLM: 30 дней (retention.sample_days).

• rollup_1m и rollup_1h: хранятся бессрочно.

Сводки хранят гистограммы TTFT и задержки с фиксированными корзинами, а не предвычисленные процентили. Гистограммы суммируются, поэтому процентиль за любой диапазон вычисляется суммированием корзин и переходом к целевому рангу. Процентили от процентилей были бы бессмысленны; здесь это не так.

Запросы в пределах raw-окна возвращают точные процентили; за его пределами они берутся из гистограмм и сообщаются как верхняя граница содержащего бакета. Каждый ответ несёт exact: true|false.

Перезапуски и перезагрузки

Состояние возобновления задаётся по источнику — курсор journald, inode+offset файла или временная метка docker — и сбрасывается при SIGTERM. Два обстоятельства делают это безопасным, а не просто вероятным:

Записи идемпотентны. Каждая строка запроса и события несёт dedupe_key под UNIQUE-индексом, а вставки выполняются через INSERT OR IGNORE. Повторное чтение строк, которые уже были сохранены, — no-op, так что ingest можно запускать многократно, и возобновление может безопасно перекрываться.

Курсор, который нельзя использовать, не считается доверенным. Если журнал, на который указывает курсор, был ротирован, journalctl молча перепозиционируется, используя временную метку, встроенную в курсор, и корректно возобновляет работу. Но курсор, помеченный временной меткой в будущем (сдвиг часов, восстановленная база данных), заставляет journalctl ждать записи, которые не появятся, молча останавливая сбор; такой курсор отклоняется при запуске. Попытка follow, не давшая результата дважды подряд, делает то же самое.

systemctl stop завершается значительно быстрее секунды. systemd фиксирует ExecMainStatus=15 рядом с Result=success: uvicorn намеренно повторно возбуждает сигнал после завершения работы, так что выход по SIGTERM — ожидаемое поведение, а не сбой.

Честные ограничения

Атрибуция при параллелизме (Ollama). Идентификатор задачи в строках таймингов llama.cpp и статус в строке доступа никогда не появляются вместе, поэтому они объединяются по порядку прибытия. При одном выполняющемся запросе это точно. Когда два завершаются до того, как печатается любая строка доступа, ничто в логе их не различает — такие строки сохраняются как attribution='ambiguous', а не угадываются. Значения: exact, ambiguous, none (сбой до достижения runner — модель также не угадывается), orphan (тайминги без строки доступа). Двухдневный backfill на хосте разработки дал 174 exact, 9 ambiguous, 4 orphan, при действующем OLLAMA_NUM_PARALLEL=1; ожидайте большую долю ambiguous при большем числе одновременных запросов.

Счётчики токенов и запросов vLLM не выровнены по запросам. generation_tokens_total увеличивается по мере потоковой передачи токенов; request_success_total увеличивается только по завершении запроса. За короткое окно они поэтому описывают перекрывающиеся, но разные наборы запросов, и деление одного на другое не даёт токены на запрос. API помечает это через counters_aligned: false, и дашборд сообщает об этом на вкладке vLLM.

Никаких по-запросных данных для vLLM. Рассмотрено выше. Если вам нужны по-запросные детали из vLLM, его по-уровневый лог — единственный источник, и он логирует текст промпта — который этот инструмент намеренно никогда не хранит.

Логи — это источник, а не архив. Журнал может хранить лишь день или два в зависимости от journald.conf; файл SQLite — историк. Если логи ротируются быстрее, чем запускается inferwatch, этот разрыв невосстановим.

Два байт-идентичных события в одну и ту же микросекунду схлопываются в одно. Ключ дедупликации для событий строится из их значений, поэтому идентичное предупреждение, записанное дважды в пределах микросекунды, сохраняет одну строку. Это осознанный компромисс ради гарантированной идемпотентности — потеря повторного предупреждения лучше дублирования истории.

Трафик проверок здоровья отделён, но не подсчитывается. HEAD / и GET /api/ps составляли 96% запросов на хосте разработки. Они хранятся с class='health' и исключаются из частот вывода, если только dashboard.include_health не включён; requests_all всегда включает их.

Зависит от форматов логов и имён метрик. Строки таймингов Ollama — это отладочный вывод, а не контракт, и vLLM переименовывает метрики между релизами. tests/test_parse.py содержит дословные строки-фикстуры, а tests/test_vllm.py — реальный фрагмент /metrics; если обновление ломает парсинг, эти тесты падают и показывают, что изменилось.

Тесты

python -m unittest discover -s tests -t .

CI запускается на Python 3.10 — 3.14, плюс задание по упаковке, которое собирает wheel, проверяет, что HTML дашборда внутри него, и устанавливает его в чистое окружение из пустой директории, чтобы дерево исходников не могло замаскировать ошибку упаковки. Сеть, GPU и движок не требуются. Фикстуры парсера — это дословные реальные строки логов и реальный фрагмент /metrics. Покрытие включает объединение коррелятора и его случаи ambiguous/orphan/failed, процентили гистограмм и идемпотентность свёртки, миграцию схемы, безопасные к сигналам коммиты, валидацию курсора, ротацию и усечение файлов, монотонность временных меток, обнаружение сброса счётчиков, а также приоритет и блокировку конфигурации. Справочник конфигурации в этом файле генерируется из спецификации, и тест падает, если он расходится. JavaScript дашборда проверяется на синтаксис чистым Python-парсером, а его форматтеры выполняются в реальном JS-движке (оба опциональны — Node не требуется).

.venv/bin/python scripts/gen-config-docs.py --check   # docs match the code?

Структура

inferwatch/parse.py        ollama log line parsers (pure, fixture-tested)
inferwatch/readers.py      journald / file / docker log readers
inferwatch/collect.py      correlator, GPU + model pollers, maintainer
inferwatch/vllm.py         Prometheus scraper, delta and reset handling
inferwatch/gpuproc.py      maps GPUs to the process tree holding them
inferwatch/vllm_metrics.py vLLM query layer
inferwatch/metrics.py      ollama query layer (shared by API and MCP)
inferwatch/store.py        SQLite schema, rollups, histograms, retention
inferwatch/config.py       typed settings spec, precedence, source validation
inferwatch/supervisor.py   builds and rebuilds collectors from the sources table
inferwatch/api.py          FastAPI endpoints + SSE
inferwatch/web/index.html  dashboard (single file, no CDN, no build step)
inferwatch/mcp_server.py   MCP server (read-only)
inferwatch/main.py         serve / ingest / stats / sources

Участие

Приветствуются issues и pull request'ы. Две вещи делают изменение легко принимаемым:

• python -m unittest discover -s tests -t . проходит.

• Если вы трогали inferwatch/config.py, запустите python scripts/gen-config-docs.py, чтобы справочник конфигурации в README соответствовал коду — тест это обеспечивает.

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

Лицензия

Apache License 2.0 — см. LICENSE и NOTICE.