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 사용률, VRAM, 온도 및 전력 소모를 표시합니다. 이는 두 엔진이 아니라 nvidia-smi로 측정되기 때문입니다. 온도와 전력은 축을 공유하지 않고 별도의 차트로 표시되며, 각각 해당 단위가 요구하는 방식으로 집계됩니다: 사용률은 카드 전체 평균, VRAM과 와트는 합산, 온도는 가장 높은 카드를 보고합니다. 온도는 0부터 플롯되지 않는 유일한 시리즈입니다 — 0부터 시작하는 33–68 °C 범위는 플롯의 대부분을 낭비하기 때문입니다.

따라서 별도의 대시보드 탭, 별도의 테이블, 별도의 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, 프리필/디코드 분할, 토큰 수, 디코드 속도, 상태, 클라이언트, 엔드포인트 및 모델을 얻을 수 있습니다 — 모든 클라이언트의 모든 요청에 대해, 요청 경로에 개입하지 않고. 두 소스 중 어느 것도 단독으로는 갖지 못한 두 가지 숫자가 이 결합에서 나옵니다:

• 큐 대기 시간 = 벽시계 지연시간 − 러너 시간: 생성이 아닌 대기에 소요된 시간. 프록시는 이 둘을 분리할 수 없습니다.

• 프롬프트 캐시 재사용 = 전체 프롬프트 길이 − 실제로 평가된 토큰 수.

OLLAMA_DEBUG=1이 필수입니다. 없으면 llama.cpp는 타이밍 라인을 출력하지 않습니다: 요청 속도, 상태 및 GPU 메트릭은 여전히 작동하지만 TTFT와 토큰 수는 비어 있습니다. 대시보드는 0을 표시하는 대신 배너로 이를 알립니다.

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

vLLM: 숫자가 나오는 곳

vLLM의 네이티브 Prometheus 엔드포인트는 collection.scrape_interval_s(기본 10초)마다 스크래핑됩니다. 누적 카운터는 차분되고, 히스토그램 버킷은 버킷별로 차분되며, 둘 다 분 단위로 집계되어 기록됩니다. 모든 스크래핑을 저장하면 어떤 차트도 사용하지 않는 해상도로 한 달에 수백만 행이 추가되기 때문입니다.

알아둘 만한 세 가지 세부 사항:

• vLLM 자체 버킷 경계가 카운트와 함께 저장됩니다. vLLM의 경계는 1ms/20ms/250ms/2.5s/40s/640s 단계이고, Ollama의 경계는 25ms/200ms/1.5s/15s/60s 단계입니다. 어느 쪽도 다른 쪽의 세분화가 아니므로, 하나를 다른 것으로 리버케팅하려면 경계 사이를 보간해야 합니다 — 숫자를 발명하는 것입니다. 백분위수는 각 소스의 자체 경계에 대해 계산되어 버킷 상한으로 보고됩니다.

• _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에서 렌더링되므로 하드코딩된 것이 없습니다:

./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 로그 리더. 모든 사람이 systemd에서 Ollama를 실행하는 것은 아닙니다:

file 리더는 tail -F처럼 따라가며, 로테이션(inode 변경)과 잘림을 견디고, 오프셋을 유지하여 재시작 시 재생하지 않습니다. Ollama의 Go 라인은 time=을 포함하지만, 토큰 수를 담고 있는 llama.cpp의 slot 라인은 타임스탬프가 없으므로 가장 최근에 본 것이 전달됩니다. 조인이 의존하는 순서는 항상 유지됩니다. 절대 정밀도는 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로 생성됨 — 수동으로 편집하지 마세요.

수집

보존

대시보드

서버

소스 필드

sources add에 --set key=value로 설정하거나 Settings 탭에서 설정합니다.

Ollama (--kind ollama)

vLLM (--kind vllm)

명령줄 플래그

설정을 고정하는 플래그는 환경 변수와 Settings 탭보다 우선합니다. 탭에서는 해당 키가 원본과 함께 읽기 전용으로 표시됩니다.

범위: Ollama 소스 1개, vLLM 소스 여러 개

vLLM 행은 전체에서 소스별로 키가 지정되므로 원하는 수의 vLLM 인스턴스를 나란히 모니터링할 수 있습니다. Ollama 테이블(requests, events, ps_samples)은 소스 파티셔닝되지 않으므로 한 번에 정확히 하나의 Ollama 소스만 실행됩니다. 두 번째를 활성화하면 두 인스턴스를 한 숫자 집합으로 조용히 혼합하는 대신 경고를 기록하고 무시합니다. 해당 테이블의 파티셔닝은 신중하게 수행할 가치가 있는 스키마 변경입니다.

대시보드

http://127.0.0.1:7070 — 세 개의 탭: Ollama, vLLM, Settings.

어떤 GPU가 어떤 엔진에 속하는지

호스트는 종종 둘 이상의 엔진을 실행하므로 인스턴스 창에 모든 카드를 표시하면 모든 카드를 사용한다는 의미가 됩니다. 각 vLLM 인스턴스의 GPU는 프로세스를 추적하여 해석됩니다 — 서비스하는 포트 → 수신 대기 pid → 하위 프로세스 → nvidia-smi의 컴퓨트 프로세스와 교차 → 해당 카드. 인스턴스의 카드는 시리즈 색상을 가지며 VRAM 타일은 해당 카드만 계산합니다. 호스트의 다른 카드는 "other engine"이라는 라벨과 함께 회색으로 계속 표시됩니다.

속성 지정에는 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 및 지연 시간의 고정 버킷 히스토그램을 저장합니다. 히스토그램은 더할 수 있으므로 모든 범위에 대한 백분위수는 버킷을 합산하고 대상 순위까지 이동하여 계산됩니다. 백분위수의 백분위수는 의미가 없을 것입니다. 이것은 그렇지 않습니다.

원시 창 내부의 쿼리는 정확한 백분위수를 반환합니다. 그 너머의 쿼리는 히스토그램에서 가져오며 포함 버킷의 상한으로 보고됩니다. 모든 응답에는 exact: true|false가 포함됩니다.

재시작 및 재부팅

상태는 소스별로 유지됩니다 — journald 커서, 파일 inode+오프셋, 또는 docker 타임스탬프 — 그리고 SIGTERM 시 플러시됩니다. 두 가지 요소가 이를 안전하게 만듭니다(단지 대략적으로가 아니라):

쓰기는 멱등적입니다. 모든 요청 및 이벤트 행은 dedupe_key를携带합니다. UNIQUE 인덱스 아래에서 삽입은 INSERT OR IGNORE입니다. 이미 저장된 행을 다시 읽는 것은 no-op이므로, ingest는 반복 실행될 수 있고 재시도는 안전하게 기존 실행과 겹칠 수 있습니다.

사용할 수 없는 커서는 신뢰되지 않습니다. 커서가 가리키는 journal이 순환되어 사라진 경우, journalctl은 자동으로 커서에 내장된 타임스탬프로 재배치하고 계속합니다. 그러나 커서가 미래의 타임스탬프로 스탬프된 경우 (시계 오차 또는 데이터베이스 복원으로 인해), journalctl은 해당 항목이 도착할 때까지 차단합니다. 이는 수집을 무기한 정지시킬 수 있습니다. 따라서 미래 타임스탬프의 커서는 시작 시 거부됩니다. 유사하게, 팔로우가 두 번 연속으로 항목을 산출하지 못하면 수집은 중지됩니다.

systemctl stop은 1초 미만으로 완료됩니다. systemd는 ExecMainStatus=15를 Result=success와 함께 기록합니다: uvicorn은 신호를 받은 후 의도적으로 재발생시키므로, SIGTERM으로 종료하는 것은 예상된 동작입니다 — 충돌이 아닙니다.

명확한 한계

병렬 처리에서의 귀속 (Ollama). llama.cpp의 타이밍 라인과 액세스 라인은 함께 나타나지 않으므로, 도착 순서대로 연결됩니다. 단일 in-flight 요청에서는 정확합니다. 그러나 두 요청이 완료되고 두 액세스 라인이 인쇄되기 전에 두 타이밍 라인이 인쇄되면, 로그는 어떤 타이밍이 어떤 액세스에 속하는지 명확히 구분하지 못합니다. 이러한 행은 attribution='ambiguous'로 저장됩니다. (타이밍이 있지만 액세스가 없는 행 — 예: 요청이 기록되기 전에 중단된 경우 — 은 attribution='orphan'으로 저장됩니다.) 2일간의 개발 호스트 백필에서 174개의 정확한 귀속, 9개의 모호한 귀속, 4개의 고아 행이 나왔습니다. 동시성이 높을수록 모호한 점유율이 높아집니다.

vLLM의 카운터는 요청별로 정렬되지 않습니다. generation_tokens_total은 토큰이 스트리밍됨에 따라 증가하고, request_success_total은 요청이 완료될 때만 증가합니다. 짧은 시간 창에서는 이들이 겹치지만 다른 요청 집합을 설명하므로, 하나를 다른 하나로 나누는 것은 토큰/요청을 제공하지 않습니다. API는 counters_aligned: false로 이를 표시하고, 대시보드는 vLLM 탭에서 이를 명시합니다.

vLLM에 대한 요청별 정보는 없습니다. 위에서 다룬 바와 같이, 요청별 세부 정보가 필요하다면 vLLM의 요청 수준 로깅이 유일한 소스이며, 이는 프롬프트 텍스트를 기록합니다 — 이 도구는 의도적으로 그것을 저장하지 않습니다.

로그는 피드이지 아카이브가 아닙니다. journal은 journald.conf에 따라 하루나 이틀만 보관할 수 있습니다. SQLite 파일이 기록 보관소입니다. 로그가 inferwatch가 실행되는 것보다 빠르게 순환되면, 그 간격은 복구할 수 없습니다.

동일한 마이크로초의 두 개의 동일한 이벤트는 하나로 합쳐집니다. dedupe_key는 이벤트 값에서 파생되므로, 동일한 마이크로초 타임스탬프를 가진 두 개의 동일한 요청은 하나의 행으로 합쳐집니다. 이는 중복 경고를 제거하기 위한 의도된 절충입니다 — 반복되는 경고를 버리는 것이 기록을 복제하는 것보다 낫습니다.

헬스 체크 트래픽은 분리되지만 제외되지는 않습니다. 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까지에서 이를 실행하며, 휠을 빌드하고, 대시보드 HTML이 그 안에 있는지 확인하고, 빈 디렉토리에 설치하여 소스 트리가 패키징 실수를 가릴 수 없도록 합니다. 네트워크, GPU 또는 엔진이 필요하지 않습니다. 파서 픽스처는 실제 로그 라인의 말 그대로의 발췌문이고, /metrics 발췌문도 마찬가지입니다. 커버리지에는 상관관계자의 조인 및 모호한/고아 사례, 히스토그램 백분위수 및 롤업 멱등성, 스키마 마이그레이션, 신호 안전 플러시, 커서 검증, 파일 순환 및 잘림, 타임스탬프 단조성, 카운터 재설정 감지, 구성 우선순위 및 잠금이 포함됩니다. 이 파일의 구성 참조는 스펙에서 생성되며, 테스트는 그것이 표류하지 않았는지 확인합니다. 대시보드의 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

기여

이슈와 풀 리퀘스트를 환영합니다. 변경 사항을 쉽게 수용할 수 있는 두 가지:

• python -m unittest discover -s tests -t .가 통과합니다.

• inferwatch/config.py를 건드렸다면, python scripts/gen-config-docs.py를 실행하여 README의 구성 참조가 코드와 일치하도록 합니다 — 테스트가 이를 강제합니다.

파서 변경 사항은 실제 엔진 출력에서 그대로 복사된 픽스처 라인을 가져와야 합니다 — 기존 테스트가 하는 방식입니다. 로그 형식과 메트릭 이름은 계약이 아니며, 실제 픽스처가 미래의 변경 사항을 명확히 드러내는 것입니다.

라이선스

Apache License 2.0 — LICENSE 및 NOTICE를 참조하십시오.