mikroscope

README

Sub-second, kernel-level telemetry for container-capable MikroTik RouterOS devices: RouterOS 7.24 or later, on arm64, 32-bit ARM or x86_64. A static Go agent runs on the router, in a scratch container, and reads the shared kernel's /proc at 1 to 100 Hz, 10 by default — per-core CPU with the softirq split, softnet drops, interrupts per CPU — where an exporter that polls the RouterOS API, such as mktxp or mikrotik-exporter, reads cpu-load: all cores in one figure, a trailing mean of about one second on the RB5009 it was measured on. A CLI on your machine installs it, records a window with markers, draws the chart, or runs as a collector into eleven sinks, Prometheus and InfluxDB 3 among them. Two MIT-licensed binaries.

What the observer costs the router is measured rather than promised: at the 10 Hz install default the agent used 2.69 % of one core and 13.2 MiB of resident memory, read from its own cgroup, on an RB5009UG+S+ (4 × 1.4 GHz Cortex-A72, RouterOS 7.24.2) — one 300 s window at steady state, the shipped configuration, the collector forwarding to InfluxDB 3, on 2026-09-18. That is inside the project's ≤ 16 MiB memory budget and above its ≤ 2 % CPU one. The 2.85 % and 31.3 MiB that 1.0.0 published were measured with a 300 s ring, which 1.0.6 cut to 60 s: the memory fell with the ring, and 2.85 % against 2.69 % is the noise between two windows. None of it transfers to a board that is not this one: Agent cost says how the figure is taken and how to take it on your own device, and the rate ceiling has all six runs, from 10 to 100 Hz.

Install

curl -fsSL https://raw.githubusercontent.com/jmrplens/mikroscope/main/install.sh | bash

or, in PowerShell on Windows:

irm https://raw.githubusercontent.com/jmrplens/mikroscope/main/install.ps1 | iex

Either one works out the platform, takes the newest release, and refuses to install anything whose checksum is not the one the release published. On a terminal it then offers the other half — the agent, which runs on the router — and shows every RouterOS command before writing any of them.

Or build it yourself with go install github.com/jmrplens/mikroscope/cmd/mikroscope@latest, or take an archive from the releases page. Install the CLI has each platform step by step, with the checksum and the cosign signature.

Put the agent on the router

mikroscope doctor  --router admin@192.168.88.1   # read-only; names the fix for anything missing
mikroscope install --router admin@192.168.88.1   # lists every command, asks, then writes
mikroscope status  --router admin@192.168.88.1   # what is installed, and whether it answers

On a router that already runs the agent, doctor also reads the samples its ring still holds and reports a layer-2 loop, STP churn or a flapping link by port, and softnet drops by CPU. Those findings and its other WARN lines (a registry credential meant for another registry, an agent published on the LAN without a token) never change its exit status.

install builds the agent from this repository if you have Go. Without it, add --remote-image jmrplens/mikroscope-agent:latest and the router pulls the image itself from Docker Hub — nothing is uploaded and there is no architecture to choose. The registry host travels inside the reference (registry-1.docker.io/…), so the router's global /container/config needs no change and no registry login. Pin the version instead of latest for a deployment you want to be able to reproduce. Install methods covers the others: the image tar, a RouterOS script (or the site's script generator) for a device you reach only through WebFig or Winbox, and the whole install by hand, in the terminal or through WebFig's menus. mikroscope uninstall removes whatever any of them created.

Two things the tool cannot do for you: RouterOS 7.24 or later, and device-mode container=yes, which MikroTik gates behind a physical reset-button press or a power cycle. Requirements is that list, and mikroscope doctor checks all of it against your own device, the RouterOS version included.

Use it

export MIKROSCOPE_ROUTER=admin@192.168.88.1

# Record a window and draw it
mikroscope record --for 5m --out cap    # cap.jsonl, cap.csv, cap.markers.csv
mikroscope mark --out cap "queue tree applied"
mikroscope plot --in cap                # cap.svg, deterministic

# Or keep it running, into a store and a dashboard
export GRAFANA_TOKEN=…
mikroscope forward \
  --influx http://influx:8181 --influx-db mikroscope \
  --grafana http://grafana:3000        # creates the datasource and publishes the dashboard

Or take a stack whole: deploy/ has two compose files, each a collector and somewhere for it to write, plus a Grafana. The InfluxDB one publishes its dashboard on start once GRAFANA_TOKEN is in .env; the Prometheus one needs the dashboard imported, and its README gives both ways.

docker compose -f deploy/compose.influxdb-grafana.yaml up -d

forward writes to eleven sinks — the file, Prometheus, InfluxDB 3, Loki, OTLP, Graphite, Elasticsearch, PostgreSQL both as a script and down a connection, Telegraf and standard output — and merges the kernel tier with the RouterOS API tier as it goes. First recording is the whole path once, end to end.

What it draws

Five Grafana dashboards, one per store Grafana can query, generated from a single panel list and shipped in the repository. forward --grafana creates the datasource and publishes the one for the store it writes to, at start, before the first sample.

Beside them, dashboards/ ships Grafana alert rules for InfluxDB, PostgreSQL and Prometheus (14, 10 and 15 rules): counters that should not move, a bridge port the bridge has stopped delivering to, and a wake-up storm judged against the device's own previous day rather than a fixed number. Alert rules lists them.

The overview, which every dashboard opens with — is this router healthy right now, and can these numbers be believed:

And the receive path, which is the section the kernel tier exists for — softnet backlog, drops, time squeezes and per-CPU budget, none of which the RouterOS API can see:

Both are a run of the canned fake agent the end-to-end suites use, written into a container store and photographed by the site's own script. The host is called rb5009 because the fake imitates that board's captured /proc, and the figures are whatever the fake publishes: read them as the shape of the page, never as a measurement. They were captured on 2026-09-17, before 1.2.0 turned the overview's memory gauge into a time series and fixed the size of the stat numbers, and have not been recaptured since.

The five dashboards, section by section, with a capture of each.

Where it has been verified

Device	Versioned profile	Tested on real hardware
MikroTik RB5009UG+S+ (arm64, RouterOS 7.24.2 measured; 7.24.4 install round trip, 2026-09-21)

Everything else the project builds for — 32-bit ARM and x86 RouterOS — is cross-compiled and CI-checked and has never run on hardware. Tested on is the measurement behind each claim. If you run mikroscope on another board, mikroscope status names it, and that plus what you measured is everything a pull request needs to add a row, or a board report if you would rather someone else wrote it.

Documentation

All of it is at https://jmrp.io/docs/mikroscope/, in English and Spanish.

Using it

• Quick install — the CLI, doctor, the agent and a check, in four commands
• First recording — record, mark and plot, the whole path once
• Install methods — the CLI, the script generator, a RouterOS script, by hand in the terminal or WebFig, offline; upgrade and uninstall
• Configure — network access, the two firewall traps, storage and container settings, the API user
• Record, mark and plot — recording, markers, charts, triggered capture
• Run the collector — the eleven sinks, the RouterOS API tier, the derive stage
• Dashboards — the five dashboards, publishing them, alert rules
• Diagnose faults — the signature of each fault, and the checks to make before trusting a reading
• Troubleshooting — the symptoms this produces, in the words you actually see

Knowing what to trust

• Agent cost — the observer's own CPU and memory, the rate ceiling, the tick floor
• How it works — the agent, the collector and the data path between them
• Resolution limits — namespaces, privileged, the per-source floors
• Security model — what runs where, the API user, what --expose opens, what the installer refuses
• Tested on — the devices, RouterOS versions and dates behind each claim, what has not been tested, and the known issues
• Case studies — an idle router first, then six faults read against it on the router they were measured on

Reference

• CLI · environment · HTTP endpoints · metric families · store schema

Contributing

CONTRIBUTING.md has the layout, the test suites, the virtual RouterOS lab they test the deployment in, and which one to run for which change. Questions go to Discussions; a bug, a board report, a feature request and a documentation defect each have an issue form. The Markdown under docs/ is generated from the site's English pages — change the page and its Spanish twin, then run pnpm run docs in site/.

Lineage: the deployment steps, the dockerless image builder and the vendored RouterOS API client come from cmd/perfmon and internal/rosapi in cs-routeros-bouncer (MIT), with attribution in each package.

License: MIT.

Documentation

Overview

Package mikroscope exists for one reason: it is the only package that can read the repository's VERSION file at compile time.

A go:embed directive cannot reach outside its own package directory, and VERSION sits at the module root because everything that has to agree on a release number reads it from there: the Makefile, GoReleaser's agent image tars and the release workflow's preflight, which refuses to release when the pushed tag and the file disagree. A package at the root can embed it; nothing under cmd/ or internal/ can.

Without this, a build nobody stamped reports "dev". That was true of every `go build`, every `go run ./cmd/mikroscope image` and therefore of every agent image tar built from one, because the real number only ever arrived through the release ldflags, and a plausible wrong version is not something anyone notices on a router.

Index

• Variables

Variables

var Version = strings.TrimSpace(versionFile)

Version is the release this build was compiled from. It is the floor, never a guess: release ldflags may still override what a command reports, which is what happens when a tag names a number the file has not caught up with yet.