# Мониторинг и профилирование

Флаги инструментирования записывают, что делает процесс Elide во время работы.

| Вопрос | Запись | Чем смотреть |
| --- | --- | --- |
| Что произошло во время запуска? | `--jfr=run.jfr` | `jfr` из JDK |
| Что лежит в куче? | `--heap-dump=heap.hprof` | VisualVM |
| Как куча ведёт себя со временем? | `--vmstat` | `jps`, `jstat` |
| Что делает работающий процесс? | `jcmd PID` | JFR, дампы кучи, стеки потоков |
| Где скомпилированный код тратит время CPU? | `--jitdump=DIR` | Linux `perf` |

Список флагов выводит `elide help instruments`. Они действуют для `run`, а также для скриптов, фрагментов и модулей.
Указывайте их перед любым `--` или `-m MODULE`. Установленный JDK 25 даёт `jfr`, `jcmd`, `jps` и `jstat`;
[VisualVM](https://visualvm.github.io/download.html) читает дампы кучи. О покрытии, трассировке CPU и отладчиках см.
[Отладка](/docs/debugging). Чтобы экспортировать трассировки, метрики и логи в систему наблюдаемости, см.
[OpenTelemetry](/docs/opentelemetry).

## Запись через JFR

```bash
elide --jfr=run.jfr run app.js
jfr summary run.jfr
jfr print --events 'dev.elide.*' run.jfr
```

`--jfr` использует настройки `profile` и сохраняет запись при обычном завершении. `--jfr-settings=default` или путь к
`.jfc` выбирает другие настройки. Имена файлов и настройки не могут содержать запятые и двойные кавычки.

| Событие | Что записывает |
| --- | --- |
| `dev.elide.Boot` | Запуск завершён; `elapsedNanos` — время запуска. |
| `dev.elide.GuestStart` / `dev.elide.GuestStop` | Выполнение программы точки входа: язык, длительность, итог, код выхода. |
| `dev.elide.HttpRequest` / `dev.elide.HttpResponse` | Один обслуженный запрос: метод, протокол, статус, длительность. |
| `dev.elide.HttpClientExchange` | Один исходящий запрос: время в очереди и на подключение, протокол, статус и байты тела. |
| `dev.elide.TransportTlsHandshake` | Одно TLS-рукопожатие: длительность, роль, итог и ALPN. |
| `dev.elide.Execution` | Команда завершилась, с её кодом выхода. |

URL, заголовки и полезная нагрузка не записываются.

## Дамп кучи

```bash
elide --heap-dump=heap.hprof run app.js
elide --heap-dump-on-oom=oom.hprof run app.js
visualvm --openfile heap.hprof
```

`--heap-dump` записывает дамп при обычном завершении. `--heap-dump-on-oom` записывает его при ошибке нехватки памяти и
затем завершает процесс без запуска хуков завершения.

## Наблюдение за работающим процессом

```bash
elide --vmstat run app.js &
jps -l
jstat -gc PID 1s
```

`--vmstat` делает процесс видимым в `jps` (по PID, без имени) и позволяет `jstat` снимать с него показатели. `jcmd`
подключается по PID с `--vmstat` или без него, в Linux и macOS, от того же пользователя ОС:

```bash
jcmd PID help
jcmd PID JFR.start name=profile settings=profile
jcmd PID JFR.dump name=profile filename=live.jfr
jcmd PID GC.heap_dump live.hprof
jcmd PID Thread.print
```

Принудительно завершённый процесс не записывает свои данные. Сохраните идущую запись через `jcmd` до того, как
остановите процесс.

## Профилирование с perf в Linux

```bash
perf record -k 1 --call-graph fp -o perf.data -- elide --jitdump=./jitdump run app.js
perf inject -j -i perf.data -o perf.jit.data
perf report -i perf.jit.data
```

`--jitdump` работает в релизных сборках для Linux. Не удаляйте каталог `jitdump`, пока не завершится `perf inject`.
Часто выполняемые функции появляются под объектами `jitted-`. Нулевой код выхода не гарантирует корректную запись;
проверьте, что в отчёте видны ваши функции. В WSL2 версия `perf` должна соответствовать работающему ядру.

## Параметры VM

У каждого флага есть запись в виде параметра VM:

```text
--jfr=run.jfr                 -XX:StartFlightRecording=filename=run.jfr,settings=profile,dumponexit=true
--heap-dump-on-oom=oom.hprof  -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=oom.hprof -XX:+ExitOnOutOfMemoryError
--vmstat                      -XX:+UsePerfData
--jitdump=DIR                 -XX:+RuntimeJitdump -XX:RuntimeJitdumpDir=DIR
```

`-XX:+DumpHeapAndExit -XX:HeapDumpPath=initial.hprof` записывает дамп начальной кучи и завершает работу. `-Xmx` и
`-XX:MaxHeapSize` — та же настройка, что и `--max-mem`; передавать оба — ошибка.
