inferwatch

Métricas en tiempo real e históricas para LLM servidos localmente — Ollama y vLLM — con un panel en el navegador, una pantalla de configuración y un servidor MCP para que un agente pueda consultar los mismos datos.

Un proceso Python, un archivo SQLite. Sin Docker, sin Node, sin Prometheus, sin servicios externos. Nunca se interpone en la ruta de solicitudes, por lo que no puede ralentizar ni romper la inferencia.

┌── 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)

Los dos motores no son simétricos, y la herramienta no finge lo contrario

Este es el hecho central del diseño, por lo que vale la pena decirlo claramente.

Ambas pestañas muestran utilización de GPU, VRAM, temperatura y consumo de energía, ya que esos se miden con nvidia-smi en lugar de con cualquiera de los motores. La temperatura y la energía tienen gráficos separados en lugar de compartir un eje, y cada uno se agrega según lo que exige su unidad: la utilización promedia entre tarjetas, la VRAM y los vatios suman, la temperatura informa la tarjeta más caliente. La temperatura es la única serie que no se traza desde cero: un rango de 33–68 °C que comienza en 0 desperdicia la mayor parte del gráfico.

Por lo tanto, obtienen pestañas de panel separadas, tablas separadas y herramientas MCP separadas. No se intenta reconstruir filas por solicitud para vLLM diferenciando contadores: no se puede recuperar qué TTFT perteneció a qué solicitud, y falsificarlo pondría filas inventadas junto a las reales.

Ollama: de dónde vienen los números

Ollama no expone un endpoint /metrics (verificado — la ruta no está en el binario). Con OLLAMA_DEBUG=1, el llama.cpp integrado imprime un bloque de tiempos por solicitud, que se combina con la línea de acceso y la línea del programador:

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

Eso produce TTFT, división prefill/decode, recuentos de tokens, tasa de decode, estado, cliente, endpoint y modelo — para cada solicitud, de cada cliente, sin tocar la ruta de solicitudes. Dos números surgen de la combinación que ninguna fuente tiene por sí sola:

• espera en cola = latencia de pared − tiempo de ejecución: tiempo dedicado a esperar en lugar de generar. Un proxy no puede separar estos.

• reutilización de caché de prompt = longitud completa del prompt − tokens realmente evaluados.

Se requiere OLLAMA_DEBUG=1. Sin él, llama.cpp no imprime líneas de tiempos: las tasas de solicitudes, los estados y las métricas de GPU aún funcionan, pero TTFT y los recuentos de tokens permanecen vacíos. El panel lo indica en un banner en lugar de mostrar ceros.

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

vLLM: de dónde vienen los números

El endpoint Prometheus nativo de vLLM se consulta cada collection.scrape_interval_s (por defecto 10s). Los contadores acumulativos se diferencian; los cubos de histograma se diferencian por cubo; ambos se escriben agregados por minuto, porque almacenar cada consulta añadiría millones de filas al mes en resoluciones que ningún gráfico usa.

Tres detalles que vale la pena conocer:

• Los límites de cubo propios de vLLM se almacenan con los recuentos. Sus límites avanzan 1ms/20ms/250ms/2.5s/40s/640s; los de Ollama avanzan 25ms/200ms/1.5s/15s/60s. Ninguno es un refinamiento del otro, por lo que re-cubicar uno en el otro requeriría interpolar entre límites — inventar números. Los percentiles se calculan contra los límites de cada fuente y se informan como límites superiores de cubo.

• _sum y _count son exactos, por lo que la media es exacta. Dado que los cubos de vLLM son gruesos en el rango de segundos, el panel y las herramientas MCP lideran con la media y etiquetan los percentiles como "como máximo".

• Los reinicios se detectan mediante process_start_time_seconds (y por un contador que retrocede). El intervalo que abarca un reinicio se descarta en lugar de emitirse como un delta falso.

La latencia entre tokens se ha escrito time_per_output_token_seconds, inter_token_latency_seconds y request_time_per_output_token_seconds a lo largo de las versiones de vLLM. Todos se recopilan y se usa el que tenga datos, por lo que esto funciona con servidores antiguos y nuevos sin configuración.

Related MCP server: System Monitor MCP Server

Instalación

Requiere Python 3.10 o más reciente — no por este código (que es limpio para 3.9) sino porque fastapi, uvicorn, starlette y mcp lo requieren.

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]"

Instalar te da dos comandos:

Aún no está en PyPI; instala desde git por ahora.

Haz un backfill desde un journal que ya tengas, luego mira la base de datos:

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

Ejecútalo:

inferwatch serve                  # http://127.0.0.1:7070

Como servicio — la unidad se genera desde systemd/inferwatch.service.in para el usuario actual, la ruta de checkout y el intérprete, por lo que nada está codificado:

./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

Anula con HOST=0.0.0.0 PORT=7070 DATADIR=... ./scripts/install-systemd.sh.

Exponerlo en una red

No hay autenticación. El panel es de solo lectura (solo GET) y no almacena texto de prompts ni respuestas — solo recuentos, tiempos, nombres de modelos y direcciones de clientes. Restringe en el firewall:

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

Configurar lo que se monitorea

Todo es editable desde la pestaña Configuración del panel, o desde la 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

Lectores de registros de Ollama. No todos ejecutan Ollama bajo systemd:

El lector file sigue como tail -F, sobreviviendo a la rotación (cambio de inodo) y truncamiento, y persiste un offset para que un reinicio no reproduzca. Las líneas Go de Ollama llevan time=, pero las líneas slot de llama.cpp — las que contienen los recuentos de tokens — no llevan timestamp, por lo que el más reciente visto se arrastra hacia adelante. El orden, del que dependen las uniones, siempre se mantiene; la precisión absoluta es menor que la de journald, y una línea [GIN] de resolución de segundo se sujeta hacia adelante para que el tiempo nunca parezca retroceder.

Precedencia de configuración

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

Una clave suministrada por el entorno o una bandera se muestra solo lectura en la pestaña Configuración con su origen, porque al proceso se le dijo que la usara y un navegador no debe anularla silenciosamente. Guardar es todo o nada, por lo que un error tipográfico en un campo no puede dejar una configuración a medias. Los cambios en fuentes, intervalos y retención se aplican sin reinicio; server.host y server.port están marcados como que necesitan uno, y la API lo dice después de guardar.

Referencia de configuración

Cada configuración a continuación es editable en la pestaña Configuración, configurable como variable de entorno, y algunas se pueden fijar con una bandera. Las tablas se generan desde el código (scripts/gen-config-docs.py), por lo que no pueden desviarse de lo que el programa realmente acepta.

Generado por scripts/gen-config-docs.py — no editar a mano.

Colección

Retención

Panel

Servidor

Campos de fuente

Establezca estos con --set key=value en sources add, o en la pestaña Settings.

Ollama (--kind ollama)

vLLM (--kind vllm)

Banderas de línea de comandos

Las banderas que fijan un ajuste tienen prioridad sobre el entorno y la pestaña Settings; la pestaña muestra esas claves de solo lectura con su origen.

Alcance: una fuente de Ollama, muchas fuentes de vLLM

Las filas de vLLM se identifican por fuente en todas partes, por lo que se puede monitorear cualquier número de instancias vLLM en paralelo. Las tablas de Ollama (requests, events, ps_samples) no están particionadas por fuente, por lo que exactamente una fuente de Ollama se ejecuta a la vez; habilitar una segunda registra una advertencia y la ignora en lugar de mezclar silenciosamente dos instancias en un conjunto de números. Particionar esas tablas es un cambio de esquema que vale la pena hacer deliberadamente.

Dashboard

http://127.0.0.1:7070 — tres pestañas: Ollama, vLLM, Settings.

¿Qué GPU pertenecen a qué motor?

Un host a menudo ejecuta más de un motor, por lo que trazar cada tarjeta en el panel de una instancia implicaría que usa todas. Las GPU de cada instancia vLLM se resuelven siguiendo procesos — el puerto que sirve → el pid que escucha → sus descendientes → intersectado con los procesos de cómputo de nvidia-smi → las tarjetas que estos ocupan. Las tarjetas de la instancia llevan el color de la serie y su mosaico de VRAM cuenta solo esas; las otras tarjetas del host permanecen visibles en gris, etiquetadas como "other engine".

La atribución necesita ss, una instancia local y visibilidad de procesos de nvidia-smi (a menudo ausente dentro de contenedores). Cuando falta alguno de estos, el panel lo indica y muestra todas las tarjetas sin énfasis, en lugar de adivinar.

Una fila de filtro limita todo lo que está debajo. Cada gráfico tiene un conmutador Table que muestra la misma serie como números, por lo que ningún valor es alcanzable solo al pasar el cursor. Un feed SSE en vivo impulsa el ticker de solicitudes y la cifra de tasa actual.

Parámetros de URL: ?tab=vllm, ?window=6h, ?model=llama3.2:3b, ?source=name, ?nostream=1 (desactiva el feed en vivo — útil para pantallas de kiosco y herramientas de captura de pantalla, que de lo contrario esperan para siempre en un stream abierto).

API

/api/sources/probe verifica una definición antes de que se guarde, por lo que un error tipográfico aparece allí en lugar de como silencio en los gráficos.

Servidor MCP

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

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

Abre el mismo archivo SQLite de solo lectura (mode=ro más PRAGMA query_only) y responde a través de la misma capa de consultas que el panel, por lo que un número que informa siempre coincide con el número en pantalla.

Retención

• Filas crudas por solicitud (Ollama): 7 días (retention.raw_days).

• Muestras de GPU, eventos, filas de vLLM: 30 días (retention.sample_days).

• rollup_1m y rollup_1h: se conservan indefinidamente.

Los rollups almacenan histogramas de cubos fijos de TTFT y latencia, no percentiles precalculados. Los histogramas se suman, por lo que un percentil sobre cualquier rango se calcula sumando los cubos y avanzando hasta el rango objetivo. Los percentiles de percentiles no tendrían sentido; esto no.

{"type": "text"}

Las consultas dentro de la ventana sin procesar devuelven percentiles exactos; más allá provienen de histogramas y se informan como el límite superior del cubo contenedor. Cada respuesta lleva exact: true|false.

Reinicios y rearranques

El estado de reanudación es por fuente — un cursor de journald, un inodo+offset de archivo, o una marca de tiempo de docker — y se vacía en SIGTERM. Dos cosas hacen que eso sea seguro en lugar de meramente probable:

Las escrituras son idempotentes. Cada fila de solicitud y evento lleva una dedupe_key bajo un índice UNIQUE, y las inserciones son INSERT OR IGNORE. Releer líneas que ya estaban almacenadas es un no-op, por lo que ingest puede ejecutarse repetidamente y una reanudación puede superponerse de forma segura.

Un cursor que no se puede usar no es de confianza. Si el diario al que apunta un cursor fue rotado, journalctl se reposiciona silenciosamente usando la marca de tiempo incrustada en el cursor y se reanuda correctamente. Pero un cursor sellado en el futuro (desviación de reloj, base de datos restaurada) hace que journalctl espere entradas que no llegarán, deteniendo la recopilación silenciosamente; tal cursor se rechaza al inicio. Un intento de seguimiento que no produce nada dos veces seguidas hace lo mismo.

systemctl stop se completa en mucho menos de un segundo. systemd registra ExecMainStatus=15 junto con Result=success: uvicorn deliberadamente vuelve a lanzar la señal después de apagarse, por lo que salir por SIGTERM es esperado, no un fallo.

Limitaciones honestas

Atribución bajo paralelismo (Ollama). El id de tarea en las líneas de temporización de llama.cpp y el estado de la línea de acceso nunca aparecen juntos, por lo que se unen por orden de llegada. Con una solicitud en curso eso es exacto. Cuando dos terminan antes de que se imprima cualquiera de las líneas de acceso, nada en el registro las desambigua — esas filas se almacenan como attribution='ambiguous' en lugar de adivinarse. Valores: exact, ambiguous, none (falló antes de llegar al runner — no se adivina ningún modelo tampoco), orphan (temporizaciones sin línea de acceso). Un backfill de 2 días en el host de desarrollo obtuvo 174 exactos, 9 ambiguos, 4 huérfanos, con OLLAMA_NUM_PARALLEL=1 en efecto; espera una mayor proporción de ambiguos cuanto más solicitudes se ejecuten concurrentemente.

Los contadores de tokens y solicitudes de vLLM no están alineados por solicitud. generation_tokens_total avanza a medida que los tokens se transmiten; request_success_total avanza solo cuando una solicitud se completa. En una ventana corta, por lo tanto, describen conjuntos de solicitudes superpuestos pero diferentes, y dividir uno por el otro no da tokens por solicitud. La API marca esto con counters_aligned: false, y el panel lo indica en la pestaña de vLLM.

Nada por solicitud para vLLM. Cubierto arriba. Si necesitas detalles por solicitud de vLLM, su registro a nivel de solicitud es la única fuente, y registra el texto del prompt — que esta herramienta deliberadamente nunca almacena.

Los registros son la fuente, no el archivo. Un diario puede contener solo un día o dos dependiendo de journald.conf; el archivo SQLite es el historiador. Si los registros rotan más rápido de lo que se ejecuta inferwatch, ese vacío es irrecuperable.

Dos eventos idénticos en bytes en el mismo microsegundo se colapsan en uno. La clave de deduplicación para eventos se construye a partir de sus valores, por lo que una advertencia idéntica registrada dos veces dentro de un microsegundo conserva una fila. Una compensación deliberada por idempotencia garantizada — descartar una advertencia repetida es mejor que duplicar el historial.

El tráfico de verificación de salud está separado, no contado. HEAD / y GET /api/ps fueron el 96% de las solicitudes en el host de desarrollo. Se almacenan con class='health' y se excluyen de las tasas de inferencia a menos que dashboard.include_health esté activado; requests_all siempre los incluye.

Depende de los formatos de registro y los nombres de métricas. Las líneas de temporización de Ollama son salida de depuración, no un contrato, y vLLM renombra métricas entre versiones. tests/test_parse.py contiene líneas de fixture verbatim y tests/test_vllm.py un extracto real de /metrics; si una actualización rompe el parseo, esas pruebas fallan y muestran qué cambió.

Pruebas

python -m unittest discover -s tests -t .

CI ejecuta esto en Python 3.10 hasta 3.14, más un trabajo de empaquetado que construye la rueda, verifica que el HTML del panel esté dentro, y lo instala en un entorno limpio desde un directorio vacío para que el árbol fuente no pueda ocultar un error de empaquetado. No se requiere red, GPU o motor. Los fixtures del parser son líneas de registro reales verbatim y un extracto real de /metrics. La cobertura incluye la unión del correlacionador y sus casos ambiguos/huérfanos/fallidos, percentiles de histograma e idempotencia de rollup, la migración de esquema, commits seguros para señales, validación de cursor, rotación y truncamiento de archivos, monotonicidad de marcas de tiempo, detección de reinicio de contadores, y precedencia y bloqueo de configuración. La referencia de configuración en este archivo se genera a partir de la especificación y una prueba falla si se desvía. El JavaScript del panel se verifica sintácticamente con un parser puro de Python y sus formateadores se ejecutan en un motor JS real (ambos opcionales — no se necesita Node).

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

Estructura

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

Contribuciones

Los issues y pull requests son bienvenidos. Dos cosas hacen que un cambio sea fácil de aceptar:

• python -m unittest discover -s tests -t . pasa.

• Si tocaste inferwatch/config.py, ejecuta python scripts/gen-config-docs.py para que la referencia de configuración del README coincida con el código — una prueba lo hace cumplir.

Los cambios en el parser deben venir con una línea de fixture copiada verbatim de la salida real del motor, como hacen las pruebas existentes. Los formatos de registro y los nombres de métricas no son contratos, y un fixture real es lo que hace obvia una futura ruptura.

Licencia

Apache License 2.0 — ver LICENSE y NOTICE.