Skip to content

History and graphs

Ferrule keeps two kinds of history:

  • Readings over time, such as port errors, temperatures, optic power and modem uptime, in VictoriaMetrics, a time-series database that runs in the stack beside Ferrule. It draws the graphs on the dashboard.
  • Events, such as outages, alerts, reboots and firmware changes, in Ferrule's own archive. That is what the outage ledger, timeline and alert history read: see WAN, outages and your ISP.

There is nothing to set up for either. Both are on named Docker volumes, so they survive a redeploy.

VictoriaMetrics in the stack

The stack's second container, ferrule-victoria-metrics, holds the history. Ferrule writes every reading to it after each poll. It isn't published on your network: the dashboard reaches it inside the stack and fetches graphs for you.

The graphs on the dashboard

Graph Where
Errors per second on a port, last 6 hours Click a port: see Switches, ports and optics
Modem uptime, last 24 hours The cable modem tile on the WAN tab

A new install shows Not enough history yet for a trend until a few readings are in. History unavailable means VictoriaMetrics can't be reached.

How long history is kept

RETENTION sets it, 13w (13 weeks) by default. Settings → History storage shows:

  • History kept: the setting in force.
  • History on disk: its size, and how much it grows a day.
  • Oldest history: how far back it goes so far.
  • Free on the volume.
  • Outage archive: its size and how many days it keeps. The archive is separate: LEDGER_RETENTION, a year (8760h) by default.

Plan a change

  1. Open Settings → History storage.
  2. Move the slider, from 8 to 52 weeks. It shows how much disk that takes, and the most it reaches just before the oldest month is dropped.
  3. Click Add to Stack environment or Copy for the RETENTION= line.
  4. Apply it:
  1. Open the ferrule stack and find Environment variables.
  2. Add or change the lines. In Advanced mode you can paste several at once.
  3. Click Pull and redeploy.
  1. Open .env in the folder where you cloned ferrule-deploy.
  2. Add or change the lines.
  3. Run docker compose up -d in that folder.

VictoriaMetrics restarts with the new setting. The collector and the outage archive carry on.

Shortening deletes history

Going from 26 to 13 weeks deletes everything older than 13 weeks at VictoriaMetrics' next monthly cleanup. There is no undo. Lengthening loses nothing; the new limit fills in as time passes.

Why Settings can't change it for you

VictoriaMetrics reads its retention once, when it starts. Changing it from the dashboard would mean restarting containers, which needs the Docker socket. Ferrule doesn't take that access, so it gives you the line instead.

When backups are set up, the archive is backed up daily and history weekly: see Backups.

Your own Prometheus or Grafana

Ferrule publishes every reading at /metrics on its own port, in the Prometheus text format. Point your Prometheus at it, and Grafana at your Prometheus.

scrape_configs:
  - job_name: ferrule
    static_configs:
      - targets: ["<docker-host>:8090"]

Set METRICS_TOKEN in the stack: Settings → Stack environment can make one. Prometheus sends it as a bearer token:

scrape_configs:
  - job_name: ferrule
    static_configs:
      - targets: ["<docker-host>:8090"]
    authorization:
      credentials: "<the METRICS_TOKEN value>"

Without the token, /metrics answers 401 with sign in first.

Every metric starts infra_ and is named for what it measures, in base units: infra_port_receive_errors_total, infra_port_sfp_receive_power_dbm, infra_device_temperature_celsius, infra_wan_window_availability_ratio. Names ending _total are counters that only go up and reset when a device reboots, so graph them with rate(), for example rate(infra_port_receive_errors_total[5m]). _ratio is 0 to 1, not a percentage.

Alerts are metrics too: infra_wan_alert, infra_device_alert and infra_port_alert carry the same WAN, device and port alerts the dashboard shows, so your own alerting can't disagree with it.

If something's wrong

What you see Why, and the fix
History backend not reachable on Settings The ferrule-victoria-metrics container is stopped. Start it, or redeploy the stack
No planner on Settings VictoriaMetrics hasn't held half a day of history yet
Prometheus gets 401 Sign-in is on: set METRICS_TOKEN and send it

More in Troubleshooting.