# First recording

Record the router's kernel while you change something, mark the moments, add the router's own log and plot it as one chart.

Source: https://docs.jmrp.io/mikroscope/start/walkthrough/

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](https://docs.jmrp.io/mikroscope/start/) puts one there.

## 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](https://docs.jmrp.io/mikroscope/security/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`](https://github.com/jmrplens/mikroscope/blob/main/.env.example) to `.env` and load it with
`set -a; . ./.env; set +a`. [Environment variables](https://docs.jmrp.io/mikroscope/reference/environment/) lists every
variable.

## Steps

1. **Record while you make the change.**

   ```sh
   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:

   ```text
   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.**

   ```sh
   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.**

   ```sh
   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:

   ```text
   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.**

   ```sh
   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](https://docs.jmrp.io/mikroscope/sinks/) into Prometheus, InfluxDB 3 or another sink; with
   `--grafana` it also publishes the dashboard
   ([Set up in Grafana](https://docs.jmrp.io/mikroscope/dashboards/import-and-check/)).

## 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](https://docs.jmrp.io/mikroscope/playbooks/idle/#recorded-chart) reads a real recording of a router at rest line by
line, the shape other recordings are compared with, and
[Diagnose faults](https://docs.jmrp.io/mikroscope/playbooks/) has the signatures a fault leaves on these panels.

## Remove the agent

```sh
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](https://docs.jmrp.io/mikroscope/install/upgrade/) has what it never touches,
and how to remove dashboards and stored data.

> **ssh is not a data path**
>
> `record`, `mark` and `plot` never use ssh: the samples travel over HTTP to the veth address, or
> through the RouterOS API relay. Only the install commands connect over ssh, one connect per
> batch of reads.

## See also

- [Record, mark and plot](https://docs.jmrp.io/mikroscope/record/): the files, the transports and the markers in full.
- [Triggered capture](https://docs.jmrp.io/mikroscope/record/triggers/): let the agent keep the seconds around a fault
  for you.
- [Run the collector](https://docs.jmrp.io/mikroscope/sinks/): what `forward` merges and where it sends it.
- [Diagnose faults](https://docs.jmrp.io/mikroscope/playbooks/): the signatures a fault leaves on these panels.