Monitoring and profiling

The instrument flags record what an Elide process does while it runs.

Question	Capture	Inspect with
What happened during the run?	`--jfr=run.jfr`	JDK `jfr`
What is in the heap?	`--heap-dump=heap.hprof`	VisualVM
How does the heap behave over time?	`--vmstat`	`jps`, `jstat`
What is a running process doing?	`jcmd PID`	JFR, heap dumps, thread stacks
Where does compiled code spend CPU time?	`--jitdump=DIR`	Linux `perf`

List the flags with elide help instruments. They apply to run and to scripts, snippets and modules. Put them before any -- or -m MODULE. A JDK 25 install provides jfr, jcmd, jps and jstat; VisualVM reads heap dumps. For coverage, CPU tracing and debuggers, see Debugging. To export traces, metrics, and logs to an observability backend, see OpenTelemetry.

Record with JFR

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

--jfr uses the profile settings and saves on normal exit. --jfr-settings=default or a .jfc path picks other settings. File names and settings cannot contain commas or double quotes.

Event	Records
`dev.elide.Boot`	Startup finished; `elapsedNanos` is the startup time.
`dev.elide.GuestStart` / `dev.elide.GuestStop`	Entry program run, with language, duration, outcome, exit code.
`dev.elide.HttpRequest` / `dev.elide.HttpResponse`	One served request, with method, protocol, status, duration.
`dev.elide.HttpClientExchange`	One outgoing request, with queue and connect time, protocol, status and body bytes.
`dev.elide.TransportTlsHandshake`	One TLS handshake, with duration, role, outcome and ALPN.
`dev.elide.Execution`	The command finished, with its exit code.

URLs, headers and payloads are not recorded.

Dump the heap

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

--heap-dump writes on normal exit. --heap-dump-on-oom writes on an out-of-memory error, then exits without running shutdown hooks.

Watch a running process

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

--vmstat lists the process in jps (by PID, with no name) and lets jstat sample it. jcmd attaches by PID with or without --vmstat, on Linux and macOS, as the same OS user:

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

A killed process does not write its captures. Dump a live recording with jcmd before you stop it.

Profile with perf on Linux

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 works in Linux release builds. Keep the jitdump directory until perf inject finishes. Frequently run functions appear under jitted- objects. A zero exit does not prove a valid capture; check that the report shows your functions. On WSL2, perf must match the running kernel.

VM options

Each flag has a VM option spelling:

--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 dumps the initial heap, then exits. -Xmx and -XX:MaxHeapSize are the same setting as --max-mem; passing both is an error.