Prom ML

Plot Prometheus time series and predict_linear-style extrapolation (linear regression). The CLI can fetch from a live Prometheus instance or plot from saved query_range JSON.

Prerequisites: Go 1.17+ (install).

go mod download

---

Generating plots

The entry point is cmd/main.go. Run with go run ./cmd (or build with go build -o promml ./cmd).

1. From a local Prometheus instance

You need a Prometheus server with data (e.g. scraping metrics). Then:

# Plot a query (default: last 60 minutes, output graph.png)
go run ./cmd -prom http://localhost:9090 -query 'up' -out up.png

# Custom time range and step
go run ./cmd -prom http://localhost:9090 -query 'node_filesystem_free_bytes{device="/dev/vda1"}' \
  -step 5m -minutes 120 -out disk.png

# Add 12h/24h predict_linear extrapolation
go run ./cmd -prom http://localhost:9090 -query 'node_filesystem_free_bytes{device="/dev/vda1"}' \
  -step 5m -minutes 120 -predict -out disk.png

# Explicit start/end (RFC3339)
go run ./cmd -prom http://localhost:9090 -query 'up' \
  -start '2025-01-01T00:00:00Z' -end '2025-01-01T12:00:00Z' -step 15s -out range.png

Flags (Prometheus mode):

Flag	Description
-prom	Prometheus base URL (required for live fetch).
-query	PromQL query (required with -prom).
-out	Output PNG path (default: graph.png).
-step	Step duration, e.g. 15s, 5m (default: 15s).
-minutes	Last N minutes when -start/-end omitted (default: 60).
-start	Start time (RFC3339).
-end	End time (RFC3339).
-predict	Add 12h and 24h prediction lines to the plot.

Running Prometheus with Docker

Quick way to get a Prometheus to point the CLI at:

# Create a minimal config (optional: add scrape configs for your targets)
mkdir -p prometheus
echo 'global: { scrape_interval: 15s }
scrape_configs:
  - job_name: prometheus
    static_configs: [{ targets: [localhost:9090] }]' > prometheus/prometheus.yml

# Run Prometheus (data in ./prometheus/data)
docker run --rm -d -p 9090:9090 \
  -v "$(pwd)/prometheus/prometheus.yml:/etc/prometheus/prometheus.yml" \
  -v "$(pwd)/prometheus/data:/prometheus" \
  --name prometheus prom/prometheus:latest

Then use -prom http://localhost:9090 (or http://host.docker.internal:9090 from another container). To stop: docker stop prometheus.

---

2. From JSON examples (included)

The repo includes Prometheus query_range-style JSON files (e.g. scenario1_slow_leak.json). You can plot them without a running Prometheus:

# Plot raw series (output: scenario1_slow_leak.png)
go run ./cmd -json scenario1_slow_leak.json

# Custom output path
go run ./cmd -json scenario1_slow_leak.json -out my_plot.png

# Plot with 12h and 24h predict_linear extrapolation
go run ./cmd -json scenario1_slow_leak.json -predict

# All scenario examples with prediction lines
go run ./cmd -json scenario1_slow_leak.json -predict
go run ./cmd -json scenario2_burst_recovery.json -predict
go run ./cmd -json scenario3_runaway_fill.json -predict
go run ./cmd -json scenario4_sawtooth_cleanup.json -predict
go run ./cmd -json scenario5_false_safety.json -predict

Flags (JSON mode):

Flag	Description
-json	Path to a Prometheus query_range JSON file (required if -prom not set).
-out	Output PNG path (default: <json basename>.png).
-predict	Run linear regression and add 12h/24h prediction lines.

JSON files must match the Prometheus /api/v1/query_range response shape: data.result[].values as [[timestamp_seconds, "value"], ...].

---

Help

go run ./cmd

Prints usage, flags, and examples when no -prom or -json is given.

---

Jupyter notebooks (GoNB)

Prerequisites for running the Go notebooks:

• Go (1.17 or later). Install from go.dev.
• Jupyter. Install via pip: pip install jupyter or pip install jupyterlab for JupyterLab.

Ensure $GOPATH/bin (or $GOBIN if set) is in your PATH so Go-installed binaries are found.

1. Install Jupyter

pip install jupyter

Or for JupyterLab:

pip install jupyterlab

2. Install GoNB and tools

Install the GoNB kernel plus goimports and gopls (for auto-complete and import handling):

go install github.com/janpfeifer/gonb@latest && \
go install golang.org/x/tools/cmd/goimports@latest && \
go install golang.org/x/tools/gopls@latest

3. Register the GoNB kernel with Jupyter

gonb --install

If gonb is not in your PATH, run it from $GOPATH/bin or $HOME/go/bin:

$HOME/go/bin/gonb --install

4. Install project dependencies

From the project root:

go mod download

5. Running Jupyter

Start Jupyter from the project directory:

jupyter notebook --no-browser

Or with JupyterLab:

jupyter lab --no-browser

Copy the URL printed in the terminal (e.g. http://localhost:8888/tree?token=...) into your browser.

6. Using notebooks

1. Open an existing notebook or create a new one.
2. For new notebooks, choose "Go (gonb)" as the kernel (Kernel → Change kernel → Go (gonb)).
3. Use import "github.com/opeonikute/promml" to import this package in cells.