Skip to content
mikroscope

First recording

Record the router’s kernel while you change something on it, then read on one chart what the change did. This takes an agent that is already installed: Quick install puts one there.

Before you start

Section titled “Before you start”
  • mikroscope status --router admin@192.168.88.1 prints an agent: line. The commands below reach the agent at its default address, 172.30.10.2:9123; pass --subnet and --port if you installed with others.
  • For step 3, a RouterOS API user with read access. API user has the two commands that create one.

Step 3 reads three environment variables:

Variable Flag
MIKROSCOPE_API_ADDR --api
MIKROSCOPE_API_USER --api-user
MIKROSCOPE_API_PASSWORD none

The password has no flag, so it stays out of ps and your shell history. The CLI does not read .env itself: export the variables, or copy .env.example to .env and load it with set -a; . ./.env; set +a. Environment variables lists every variable.

Steps

Section titled “Steps”

  1. Record while you make the change.

    Terminal window
    mikroscope record --for 60s --out burst

    On a terminal, type a line and press Enter at any moment worth remembering: it becomes a marker in the agent’s clock. The CLI says so when it starts: type a line and press Enter to add a marker; Ctrl-C stops. Without --for it records until Ctrl-C. At the end it prints what it wrote:

    recorded 600 samples (seq 11..610), 0 gap(s), 0 marker(s), via direct http://172.30.10.2:9123
      burst.jsonl
      burst.csv
      burst.markers.csv
      burst.meta.json

    The summary counts the markers typed into record itself, and names any stretch of samples that had already left the agent’s ring.

  2. Mark from another terminal.

    Terminal window
    mikroscope mark --out burst "queue tree applied"

    It prints marker added to burst.markers.csv at <time>. mark appends to the same file while record runs, and works after the recording too.

  3. Add the router’s own log.

    Terminal window
    export MIKROSCOPE_API_ADDR=192.168.88.1:8728 MIKROSCOPE_API_USER=mikroscope MIKROSCOPE_API_PASSWORD=…
    mikroscope mark --out burst --log-markers --router-tz Europe/Madrid

    Every log line inside the recording’s window whose topic is system, interface or container becomes a marker:

    7 log marker(s) added to burst.markers.csv (window <start> → <end>, topics system,interface,container)

    Add firewall or script with --topics. --router-tz is the IANA zone the router’s clock shows, because RouterOS log times carry no zone; it defaults to your machine’s. record --log-markers does the same when the recording ends.

  4. Plot it.

    Terminal window
    mikroscope plot --in burst

    It writes burst.svg and prints burst.svg: 600 samples, 10 markers. --title sets the heading and --svg another path. The same recording always gives the same bytes.

  5. Keep collecting (optional). To keep the samples rather than a window, run the collector into Prometheus, InfluxDB 3 or another sink; with --grafana it also publishes the dashboard (Set up in Grafana).

Read the chart

Section titled “Read the chart”

The chart has three panels on one time axis:

  • Busy ratio per core. The share of each 100 ms tick a core spent working. One sample of one core at 100 % is 100 ms of work, and moves a four-core, one-second average by only 2.5 %: the short excursions an average hides are the point of sampling at 10 Hz.
  • softnet, per second. dropped counts packets the kernel lost from its backlog, which no interface counter shows; time_squeeze counts the times the kernel paced itself. A squeeze on its own is not a fault.
  • Memory available. What the kernel could hand out without swapping.

Each marker is a dashed vertical line, drawn in every panel, with its label beside it. Log markers that fall in the same second fold into one line labelled N× and the first message. A gap in the samples is a red line. A label longer than 40 characters is cut to 37 and an ellipsis.

Idle baseline reads a real recording of a router at rest line by line, the shape other recordings are compared with, and Diagnose faults has the signatures a fault leaves on these panels.

Remove the agent

Section titled “Remove the agent”
Terminal window
mikroscope uninstall --router admin@192.168.88.1 --yes

It removes every object the install created, reading the list from the install manifest on the router, and ends with verified: nothing mikroscope created remains on the router. Without --yes it only lists them. Upgrade and uninstall has what it never touches, and how to remove dashboards and stored data.

Written and maintained by José Manuel Requena Plens (jmrplens)GitHub