Run the demo stack

The demo is a self-contained stack: a small api-server (Prometheus metrics, request logs, fault injection), Prometheus (scraping and evaluating alerting rules), and a traffic generator — the upstream systems NavFlow ingests from. NavFlow runs on your machine and reads from the stack exactly as it would read from your real systems: three sources, one saved view, a trigger, and a fault injector to cause incidents on demand.

The division of labour is the real one: Prometheus owns alerting (the demo ships three rules); NavFlow ingests the fired alerts, correlates them with the metrics and logs, and a trigger wakes a subscribed agent with the whole timeline to diagnose.

Everything is two files you can curl — no repo checkout needed.


 demo stack (docker)                     NavFlow (installed locally)
 ┌───────────────┐  scrape   ┌──────────┐
 │  api-server   │◄──────────│Prometheus│◄─── metrics (:9090 PromQL)
 │  :8080        │           └──────────┘
 │  /metrics     │──logs────────────────────── docker logs
 │  /demo/inject │  (fault injection)          → one correlated timeline + triggers
 └───────────────┘
        ▲ traffic-generator

Start the stack

One compose file — the api-server image is prebuilt, and the Prometheus config is inlined:


curl -O https://raw.githubusercontent.com/glassflow/navflow/main/demo/docker-compose.yml
docker compose up -d              # api-server + prometheus + traffic

Give it ~10s, then check it’s alive:


curl -s localhost:8080/api/stats                  # {"ok": true, ...}
curl -s 'localhost:9090/api/v1/query?query=up'    # prometheus is scraping

Run NavFlow against it

Install NavFlow the normal way (not in Docker) and seed it with the demo catalog — from any directory:


uv tool install navflow          # or: pipx install navflow
 
curl -O https://raw.githubusercontent.com/glassflow/navflow/main/demo/catalog.demo.yaml
NAVFLOW_CATALOG=catalog.demo.yaml navflow up

The console opens at http://127.0.0.1:8787 with everything configured: three sources — demo_metrics, demo_logs, and demo_alerts (the alerts Prometheus’s own rules fire) — all keyed api-server, a service_timeline view over them, and the incident trigger watching it.

The catalog seeds only while your catalog is still empty. If you’ve run NavFlow before, point --data-dir at a fresh directory (or pass a fresh NAVFLOW_DB).

Look around

Explore — pick the api-server entity and watch metrics, logs, and the alerts Prometheus fires merge into one time-ordered timeline. Flip Agent view to see the exact read an agent gets over MCP.
Views / Triggers — service_timeline is the saved read; the incident trigger watches it and fires when Prometheus fires an alert, pushing the whole correlated timeline to a subscribed agent.

Cause an incident

Flip a fault by POSTing a scenario to the api-server:


curl -s -XPOST localhost:8080/demo/inject -H 'content-type: application/json' \
  -d '{"scenario": "error_spike"}'

error_spike — 5xx storm → Prometheus fires HighErrorRate
latency — p99 > 1s → Prometheus fires HighLatency
dependency_outage — a dependency goes down → Prometheus fires DependencyDown
clear — roll back; the alerts resolve (a resolved event lands in the timeline)

Give it ~30s (the rules have a 15s for:, then NavFlow polls the alerts). The alert lands in Explore (the timeline turns red) next to the metric that tripped it and the error logs, the incident trigger fires, and — once an agent is subscribed — it shows in Agents → Trigger dispatches.

Ask an agent about it

With an agent connected, the incident is a question away:

Use navflow: what happened to api-server in the last 15 minutes?

The agent reads the correlated timeline — the 5xx storm, the alert, and the surrounding logs and metrics in one response.

Stop


docker compose down              # from the directory with docker-compose.yml

Files

Both live in demo/ in the repo:

docker-compose.yml — the whole stack, self-contained (prebuilt api-server image, Prometheus config inlined).
catalog.demo.yaml — NavFlow’s view of the stack (sources, views, triggers).

The repo also has the api-server source (demo/api-server/), a build override for hacking on it, and inject.sh, a wrapper around the inject call above.