# mikroscope documentation

> Sub-second kernel telemetry from inside a MikroTik router, with the cost of the observer measured rather than claimed. mikroscope is open source under the MIT licence and written in Go: an agent that runs in a container on MikroTik RouterOS 7.24 or later (arm64, arm, x86_64), and a CLI that installs it, records, plots and forwards to eleven sinks. Current release: 1.6.1, 2026-10-06.

This is the index of the mikroscope documentation site. Every entry links one page and carries that page's own description. Source and issues live at https://github.com/jmrplens/mikroscope, and the releases page there carries the CLI archives, the agent image tars and the GHCR image.

Home: [mikroscope](https://docs.jmrp.io/mikroscope/): Sub-second kernel telemetry from inside a MikroTik router, with the cost of the observer measured rather than claimed. ([markdown](https://docs.jmrp.io/mikroscope/index.md))

## Start here

- [Quick install](https://docs.jmrp.io/mikroscope/start/): Install the CLI, check the router and run the agent in a RouterOS container, in four commands. ([markdown](https://docs.jmrp.io/mikroscope/start/index.md))
- [First recording](https://docs.jmrp.io/mikroscope/start/walkthrough/): Record the router's kernel while you change something, mark the moments, add the router's own log and plot it as one chart. ([markdown](https://docs.jmrp.io/mikroscope/start/walkthrough/index.md))
- [FAQ](https://docs.jmrp.io/mikroscope/start/questions/): Short answers about mikroscope on MikroTik RouterOS, from MIPS and the 7.24 minimum to cost, production use, cpu-load and the Grafana dashboards, each linked to the page with the detail. ([markdown](https://docs.jmrp.io/mikroscope/start/questions/index.md))
- [Compared with alternatives](https://docs.jmrp.io/mikroscope/start/compared/): What SNMP, The Dude, Graphing, the Profiler, mktxp and mikrotik-exporter read on a MikroTik router, beside mikroscope, and when to use them instead. ([markdown](https://docs.jmrp.io/mikroscope/start/compared/index.md))

## Install

- [Install methods](https://docs.jmrp.io/mikroscope/install/routes/): The ways to put the mikroscope agent on a MikroTik router — the CLI with a registry pull, the image tar or a checkout, a RouterOS script, the generator, or by hand — and what each needs. ([markdown](https://docs.jmrp.io/mikroscope/install/routes/index.md))
- [Requirements](https://docs.jmrp.io/mikroscope/install/prerequisites/): What the router needs before an install — RouterOS 7.24 or later, a container-capable architecture, the container package and device-mode — what your computer needs, and how doctor checks each. ([markdown](https://docs.jmrp.io/mikroscope/install/prerequisites/index.md))
- [Install the CLI](https://docs.jmrp.io/mikroscope/install/cli/): Install the `mikroscope` CLI on Linux, macOS or Windows, pick the archive for your computer rather than the router, and verify it. ([markdown](https://docs.jmrp.io/mikroscope/install/cli/index.md))
- [Install with the CLI](https://docs.jmrp.io/mikroscope/install/): Install the agent with mikroscope install over ssh, what it checks and writes in order, how it marks what it owns, and the flags and variables it reads. ([markdown](https://docs.jmrp.io/mikroscope/install/index.md))
- [Script generator](https://docs.jmrp.io/mikroscope/install/generator/): Fill in a form and get the RouterOS script that installs the agent, the same script `mikroscope plan --rsc` prints, and the script that removes it again. ([markdown](https://docs.jmrp.io/mikroscope/install/generator/index.md))
- [RouterOS script](https://docs.jmrp.io/mikroscope/install/script/): Generate the install as one RouterOS script with mikroscope plan --rsc, run it from the router's terminal or with /import, verify it, read its manifest and remove it. ([markdown](https://docs.jmrp.io/mikroscope/install/script/index.md))
- [Manual install: terminal](https://docs.jmrp.io/mikroscope/install/manual-cli/): Install the agent by typing each RouterOS command in the router's terminal — the manifest, the veth, the address, the list memberships, the envlist and the container — then verify it and remove it. ([markdown](https://docs.jmrp.io/mikroscope/install/manual-cli/index.md))
- [Manual install: WebFig and Winbox](https://docs.jmrp.io/mikroscope/install/manual-gui/): Install the agent from the router's WebFig or Winbox menus, form by form, with no CLI; then start it, check it and remove it. ([markdown](https://docs.jmrp.io/mikroscope/install/manual-gui/index.md))
- [Offline install](https://docs.jmrp.io/mikroscope/install/offline/): Install the agent on a router that cannot reach a registry — choose the image tar for its architecture, verify the download, and install from it with the CLI or a RouterOS script. ([markdown](https://docs.jmrp.io/mikroscope/install/offline/index.md))
- [Upgrade and uninstall](https://docs.jmrp.io/mikroscope/install/upgrade/): Upgrade the agent to a new release, what to do when coming from an older one, remove everything an install created from the router, and remove the dashboards and stored data. ([markdown](https://docs.jmrp.io/mikroscope/install/upgrade/index.md))

## Configure

- [Network access](https://docs.jmrp.io/mikroscope/install/reaching-the-agent/): Reach the agent on its veth address from your host, directly, through a static route, over the RouterOS API relay or with --expose, and read what the probe after install says. ([markdown](https://docs.jmrp.io/mikroscope/install/reaching-the-agent/index.md))
- [Firewall lists](https://docs.jmrp.io/mikroscope/install/firewall/): The list memberships install adds so the router's raw drop rules let the agent's replies through, how to name your own lists or none, and what doctor checks. ([markdown](https://docs.jmrp.io/mikroscope/install/firewall/index.md))
- [Storage and container settings](https://docs.jmrp.io/mikroscope/install/layout/): Where install puts the image, the container root and the install manifest, the container's settings and the flags that change them, and how to size its memory. ([markdown](https://docs.jmrp.io/mikroscope/install/layout/index.md))
- [API user](https://docs.jmrp.io/mikroscope/security/api-user/): Create the dedicated RouterOS user the collector logs in as, with the policy each command needs, and see what that policy lets it read. ([markdown](https://docs.jmrp.io/mikroscope/security/api-user/index.md))
- [Expose on the LAN](https://docs.jmrp.io/mikroscope/security/expose/): Publish the agent on the router's LAN address with install --expose, the two tagged firewall rules it adds, who reaches the agent through them, the token they require and how they come off. ([markdown](https://docs.jmrp.io/mikroscope/security/expose/index.md))

## Use

- [Record, mark and plot](https://docs.jmrp.io/mikroscope/record/): Pull a window of full-rate samples to your machine, mark moments in it, add the router's own log and draw it as a deterministic SVG. ([markdown](https://docs.jmrp.io/mikroscope/record/index.md))
- [Triggered capture](https://docs.jmrp.io/mikroscope/record/triggers/): Keep full-rate samples around a condition you set on the agent, fetch them over HTTP, and count the fires that were not captured. ([markdown](https://docs.jmrp.io/mikroscope/record/triggers/index.md))
- [Run the collector](https://docs.jmrp.io/mikroscope/sinks/): Run mikroscope forward to pull a MikroTik router's kernel telemetry, merge it with the RouterOS API tier, derive values and write the timeline to eleven sinks. ([markdown](https://docs.jmrp.io/mikroscope/sinks/index.md))
- [Prometheus](https://docs.jmrp.io/mikroscope/sinks/prometheus/): MikroTik RouterOS kernel metrics on the collector's /metrics: every agent family recomputed from the samples, the API tier, derived values, one scrape job. ([markdown](https://docs.jmrp.io/mikroscope/sinks/prometheus/index.md))
- [InfluxDB 3](https://docs.jmrp.io/mikroscope/sinks/influxdb/): MikroTik RouterOS kernel telemetry into InfluxDB 3 over /api/v3/write_lp: URL and token, delivery and drops, every measurement, and what Core refuses. ([markdown](https://docs.jmrp.io/mikroscope/sinks/influxdb/index.md))
- [Other sinks](https://docs.jmrp.io/mikroscope/sinks/other/): The JSONL file, stdout, SQL, PostgreSQL, Loki, OTLP, Graphite, Elasticsearch and Telegraf: what each sink carries, how it delivers and what its protocol cannot hold. ([markdown](https://docs.jmrp.io/mikroscope/sinks/other/index.md))
- [RouterOS API tier](https://docs.jmrp.io/mikroscope/sinks/api-tier/): What the collector asks the RouterOS binary API, the presets that ask less, what cpu-load averages and what a missing value means. ([markdown](https://docs.jmrp.io/mikroscope/sinks/api-tier/index.md))
- [Dashboards](https://docs.jmrp.io/mikroscope/dashboards/): The five Grafana dashboards for MikroTik RouterOS kernel telemetry, one per store: how they get into Grafana, every section and panel, and what each store cannot carry. ([markdown](https://docs.jmrp.io/mikroscope/dashboards/index.md))
- [Set up in Grafana](https://docs.jmrp.io/mikroscope/dashboards/import-and-check/): Put the mikroscope dashboards into Grafana: published by the collector, imported with the CLI or by hand, with each store's datasource; then check every panel, update and remove them. ([markdown](https://docs.jmrp.io/mikroscope/dashboards/import-and-check/index.md))
- [Alert rules](https://docs.jmrp.io/mikroscope/dashboards/alerts/): The Grafana alert rules generated beside the dashboards: what each fires on, how to install them, where each threshold comes from and what they cannot see. ([markdown](https://docs.jmrp.io/mikroscope/dashboards/alerts/index.md))
- [Diagnose faults](https://docs.jmrp.io/mikroscope/playbooks/): The signature of each fault mikroscope has read on a MikroTik router, where it shows in the data, and the two checks to run before you trust a reading. ([markdown](https://docs.jmrp.io/mikroscope/playbooks/index.md))

## Reference

- [CLI](https://docs.jmrp.io/mikroscope/reference/cli/): Every verb of the mikroscope CLI and its flags, grouped by verb, with each flag's default, accepted values and the MIKROSCOPE_* variable that sets it, read from the Go source. ([markdown](https://docs.jmrp.io/mikroscope/reference/cli/index.md))
- [Environment variables](https://docs.jmrp.io/mikroscope/reference/environment/): The MIKROSCOPE_* variables the CLI reads, the credentials that exist only as variables, and the envlist variables the agent reads on the router. ([markdown](https://docs.jmrp.io/mikroscope/reference/environment/index.md))
- [HTTP endpoints](https://docs.jmrp.io/mikroscope/reference/http/): Every path the agent serves on the veth, its query parameters, what it returns, how the token guards it, and the line formats of /snapshot and /stream. ([markdown](https://docs.jmrp.io/mikroscope/reference/http/index.md))
- [Prometheus metrics](https://docs.jmrp.io/mikroscope/reference/metrics/): Every Prometheus metric family mikroscope's collector exposes for a MikroTik RouterOS device, by source, with its type, its labels and when it is absent. ([markdown](https://docs.jmrp.io/mikroscope/reference/metrics/index.md))
- [Store schema](https://docs.jmrp.io/mikroscope/reference/measurements/): Every InfluxDB measurement and SQL table mikroscope writes, with tags, fields, columns, keys, units, and whether each value is a delta or a level. ([markdown](https://docs.jmrp.io/mikroscope/reference/measurements/index.md))
- [Derived values](https://docs.jmrp.io/mikroscope/sinks/derive/): What the collector computes beside the raw samples: memory pressure, per-packet PMU cost, packets per interrupt, the burst flag, and when each is withheld. ([markdown](https://docs.jmrp.io/mikroscope/sinks/derive/index.md))
- [Detection rules](https://docs.jmrp.io/mikroscope/sinks/detections/): The eleven detection rules mikroscope runs on MikroTik RouterOS kernel data: the exact condition of each, what it needs, and what it may not claim. ([markdown](https://docs.jmrp.io/mikroscope/sinks/detections/index.md))
- [Device info](https://docs.jmrp.io/mikroscope/sinks/device-info/): What the agent learns about a MikroTik board without the RouterOS API (identity, ceilings, cadences) and how every sink receives it as facts, not samples. ([markdown](https://docs.jmrp.io/mikroscope/sinks/device-info/index.md))
- [Port names](https://docs.jmrp.io/mikroscope/reference/port-names/): The kernel log says eth5 where RouterOS says ether6: measure the mapping on a dead port, read the known mappings, and see how the agent, the collector and the dashboards use them. ([markdown](https://docs.jmrp.io/mikroscope/reference/port-names/index.md))
- [Troubleshooting](https://docs.jmrp.io/mikroscope/reference/troubleshooting/): Symptoms in the words you see (a doctor line, a RouterOS error, a container that exits, an empty panel, a sink that drops), with the cause and the fix for each. ([markdown](https://docs.jmrp.io/mikroscope/reference/troubleshooting/index.md))
- [Glossary](https://docs.jmrp.io/mikroscope/reference/glossary/): The terms these pages use without defining them, from envlist, veth and privileged to PMU, PSI, softnet, ring and sink, one sentence each with a link. ([markdown](https://docs.jmrp.io/mikroscope/reference/glossary/index.md))

## Explanation

- [How it works](https://docs.jmrp.io/mikroscope/how-it-works/): The agent in a RouterOS container, the veth it answers on, the collector on your machine and the sinks it writes to, and what the design cannot do. ([markdown](https://docs.jmrp.io/mikroscope/how-it-works/index.md))
- [Resolution limits](https://docs.jmrp.io/mikroscope/limits/): The kernel's 10 ms tick as the floor of every CPU reading on a MikroTik router, the PMU counters that read beneath it, and how far back the agent's ring reaches. ([markdown](https://docs.jmrp.io/mikroscope/limits/index.md))
- [Container visibility](https://docs.jmrp.io/mikroscope/limits/namespaces/): Which kernel files inside a RouterOS container describe the router and which only the container, and what that means for traffic, connection counts and host mounts. ([markdown](https://docs.jmrp.io/mikroscope/limits/namespaces/index.md))
- [Privileged mode](https://docs.jmrp.io/mikroscope/limits/privileged/): What privileged=yes on the agent's RouterOS container makes readable, what it leaves out of reach, and what running without it costs. ([markdown](https://docs.jmrp.io/mikroscope/limits/privileged/index.md))
- [Source cadences](https://docs.jmrp.io/mikroscope/limits/source-floors/): Which kernel sources the agent reads and stores every tick and which less often, the named reason each reports, and FLOOR_HZ, which turns every floor off. ([markdown](https://docs.jmrp.io/mikroscope/limits/source-floors/index.md))
- [Security model](https://docs.jmrp.io/mikroscope/security/): Which piece of mikroscope runs on the MikroTik router and which on your host, what each reaches, where every credential lives, and how to report a flaw. ([markdown](https://docs.jmrp.io/mikroscope/security/index.md))
- [Installer safeguards](https://docs.jmrp.io/mikroscope/security/installer/): The objects install will not build on, the values it will not put in a RouterOS command, and how uninstall proves it left nothing behind. ([markdown](https://docs.jmrp.io/mikroscope/security/installer/index.md))

## Evidence

- [Tested on](https://docs.jmrp.io/mikroscope/about/status/): The devices, RouterOS versions, dates and conditions behind every measurement and check in the mikroscope documentation, what was found, and what has not been tested. ([markdown](https://docs.jmrp.io/mikroscope/about/status/index.md))
- [Agent cost](https://docs.jmrp.io/mikroscope/cost/): What the agent, an SSH connect and the RouterOS API tier cost a MikroTik RB5009, measured from the agent's own cgroup and RouterOS's profiler, and how to measure the agent on your router. ([markdown](https://docs.jmrp.io/mikroscope/cost/index.md))
- [Rate ceiling](https://docs.jmrp.io/mikroscope/cost/rate-ceiling/): Six measured runs at 10, 20, 50 and 100 Hz on an RB5009 at its shipped configuration, none of which lost a sample, and what sampling faster buys. ([markdown](https://docs.jmrp.io/mikroscope/cost/rate-ceiling/index.md))
- [Limits of the evidence](https://docs.jmrp.io/mikroscope/cost/limits/): The questions the measurements on this site cannot answer, and which metric to reach for instead of guessing. ([markdown](https://docs.jmrp.io/mikroscope/cost/limits/index.md))
- [Idle baseline](https://docs.jmrp.io/mikroscope/playbooks/idle/): Sixty idle seconds on a MikroTik RB5009 read at 10 Hz: the busy floor, a softnet squeeze that is never zero, and a kernel log that stays silent. ([markdown](https://docs.jmrp.io/mikroscope/playbooks/idle/index.md))
- [Layer-2 loop](https://docs.jmrp.io/mikroscope/playbooks/loop/): A layer-2 loop behind a MikroTik RB5009 bridge port that RouterOS's log never showed, found in the kernel log at the STP hello interval, and that came back later. ([markdown](https://docs.jmrp.io/mikroscope/playbooks/loop/index.md))
- [CPU-bound core](https://docs.jmrp.io/mikroscope/playbooks/cpu/): One saturated core of a MikroTik RB5009 read at 10 Hz: why the device total hides it, the scheduler moving the load between cores, and the temperature. ([markdown](https://docs.jmrp.io/mikroscope/playbooks/cpu/index.md))
- [Packet flood](https://docs.jmrp.io/mikroscope/playbooks/packet-flood/): A 10 s ICMP flood at a MikroTik RB5009, read from inside its container: the switch interrupt standing in for a port counter, one core paying, time_squeeze. ([markdown](https://docs.jmrp.io/mikroscope/playbooks/packet-flood/index.md))
- [Flash wear](https://docs.jmrp.io/mikroscope/playbooks/flash-wear/): A MikroTik RB5009 writes to its NAND at idle: see it in the YAFFS counters, trace it to a logging rule, and read the ECC counters that warn before a loss. ([markdown](https://docs.jmrp.io/mikroscope/playbooks/flash-wear/index.md))
- [Port losing frames](https://docs.jmrp.io/mikroscope/playbooks/port-errors/): A MikroTik port counting rx-overflow: telling a load from a microburst with the port counters, what did not fix it, and the sender pacing that did. ([markdown](https://docs.jmrp.io/mikroscope/playbooks/port-errors/index.md))
- [Conntrack without the API](https://docs.jmrp.io/mikroscope/playbooks/conntrack/): The real conntrack count of a MikroTik router from inside a RouterOS container: the nf_conntrack slab where the namespace says 0, checked against the API. ([markdown](https://docs.jmrp.io/mikroscope/playbooks/conntrack/index.md))
- [Test suites](https://docs.jmrp.io/mikroscope/reference/testing/): The four test suites, unit, end to end, real stores and the virtual RouterOS lab: what each proves, how to run it, what it needs and when CI runs it. ([markdown](https://docs.jmrp.io/mikroscope/reference/testing/index.md))

## About

- [Releases](https://docs.jmrp.io/mikroscope/about/changelog/): The current mikroscope release and its date, read at build from VERSION and CHANGELOG.md, what every release publishes, and where the full history is. ([markdown](https://docs.jmrp.io/mikroscope/about/changelog/index.md))
- [Lineage and licence](https://docs.jmrp.io/mikroscope/about/lineage/): Which parts of mikroscope came from cs-routeros-bouncer, ghchronicle and go-routeros, what changed on the way, and the MIT licence they arrive under. ([markdown](https://docs.jmrp.io/mikroscope/about/lineage/index.md))
- [Logo and brand](https://docs.jmrp.io/mikroscope/about/brand/): Nine sample bars and the line of their own mean, why none of it is drawn at partial opacity, and the contrast each tone measures against its page. ([markdown](https://docs.jmrp.io/mikroscope/about/brand/index.md))

## Machine-readable references

Each file below holds pages concatenated as markdown, separated by `---`, with every link absolute. Sizes are bytes of UTF-8; tokens are the size divided by four, an estimate rather than a count.

- [Core documentation](https://docs.jmrp.io/mikroscope/llms-core.txt) (226 KB, about 58k tokens): the pages to read first, in this order: Home; Quick install; First recording; FAQ; Compared with alternatives; Install methods; Requirements; How it works; Resolution limits; Tested on; Agent cost
- [Full documentation](https://docs.jmrp.io/mikroscope/llms-full.txt) (1.2 MB, about 313k tokens): every English page concatenated, in this order

One file per section of the sidebar, its pages in the same order as above:

- [Start here](https://docs.jmrp.io/mikroscope/llms/start-here.txt) (31 KB, about 8k tokens): the 4 pages of this section
- [Install](https://docs.jmrp.io/mikroscope/llms/install.txt) (147 KB, about 38k tokens): the 10 pages of this section
- [Configure](https://docs.jmrp.io/mikroscope/llms/configure.txt) (57 KB, about 15k tokens): the 5 pages of this section
- [Use](https://docs.jmrp.io/mikroscope/llms/use.txt) (284 KB, about 73k tokens): the 11 pages of this section
- [Reference](https://docs.jmrp.io/mikroscope/llms/reference.txt) (355 KB, about 91k tokens): the 11 pages of this section
- [Explanation](https://docs.jmrp.io/mikroscope/llms/explanation.txt) (79 KB, about 20k tokens): the 7 pages of this section
- [Evidence](https://docs.jmrp.io/mikroscope/llms/evidence.txt) (237 KB, about 61k tokens): the 12 pages of this section
- [About](https://docs.jmrp.io/mikroscope/llms/about.txt) (29 KB, about 8k tokens): the 3 pages of this section

The markdown link beside each page above is that page as markdown, at its own path with `index.md` appended, which is the cheapest way to read one page as text.

## Other languages

- [Spanish documentation index](https://docs.jmrp.io/mikroscope/es/llms.txt): the same documentation in Spanish, page for page

<!-- https://docs.jmrp.io/mikroscope/llms.txt -->