Haskell Inspector

Command-line reference

Generated from commit e8a491d6e1e2.

The complete command-line interface, generated from the option parser. The same text is available in your terminal with hins --help and hins <command> --help. A machine-readable version is at cli.json.

#Synopsis

Usage: hins [--version] [(-p|--pid PID) | (-d|--descriptor PATH) | --snapshot PATH | --eventlog PATH | (-r|--run PROG) [--run-arg ARG] [--paused] | --attach-any [--match-prog NAME] [--match-cwd DIR]] [--log LEVEL] [--log-file PATH] [--debug-log PATH] [--event-buffer-mb N] [--refresh-interval-ms N] [--sample-capacity N] [--list-formats CMD | --list-all-formats] [--every TIME] [--repeat N] [--duration T] [--until-exit] [--pause-at WHEN] [--request-gc] [-o|--output PATH] [-f|--format FMT] [--pretty | --no-pretty] [--color | --no-color] [COMMAND | [--dap-stdio | [--web] [--with-dap]] [--port N] [--web-port-file PATH] [--web-unix-socket PATH]]
Option Description
-h, --help Show this help text
--version Print version and exit
-p, --pid PID Attach to PID by looking up its descriptor file
-d, --descriptor PATH Attach via the debuggee descriptor file at PATH (a .desc file written by the connector)
--snapshot PATH Load a recorded heap snapshot from PATH
--eventlog PATH Load a .eventlog file from PATH
-r, --run PROG Spawn PROG with the connector preloaded, then attach. Use --run-arg ARG (repeated) to forward arguments.
--run-arg ARG Argument forwarded to the spawned program; may be repeated
--paused Start the spawned program in paused mode (sets HASKELL_INSPECTOR_START_PAUSED for the child)
--attach-any Attach to the most-recently-published descriptor (optionally filtered by --match-prog / --match-cwd)
--match-prog NAME With --attach-any: restrict to descriptors whose progname (or exe basename) equals NAME
--match-cwd DIR With --attach-any: restrict to descriptors whose cwd is at or under DIR (symlinks resolved)
--log LEVEL Log level: debug, info, warn, error, off (default: "error")
--log-file PATH Send logs to PATH (default: stderr)
--debug-log PATH Engine debug-hook log file
--event-buffer-mb N Eventlog ring-buffer size in MiB
--refresh-interval-ms N Engine tick period in milliseconds
--sample-capacity N Per-sample ring capacity (CC / alloc / STG-stack rings). Default 10_000_000.
--list-formats CMD List output formats for CMD (or pass --list-formats with no argument for all) and exit
--list-all-formats List output formats for every command and exit
--every TIME Re-run the command every TIME (e.g. 100ms, 5s, 2m, 1h)
--repeat N Stop after N runs/ticks
--duration T Stop after wall-clock T
--until-exit Stop when the target program exits or detaches
--pause-at WHEN Where to pause for analysis: now (default), before-gc, after-gc (the GC modes wait for the next major GC)
--request-gc With --pause-at before-gc/after-gc, trigger a major GC now instead of waiting for one
-o, --output PATH Write report to PATH (- for stdout). Supports {n} {ts} {cmd} placeholders.
-f, --format FMT Output format. Run --list-formats to see options.
--pretty Pretty-print JSON
--no-pretty Don't pretty-print JSON
--color Force colour
--no-color Disable colour
--dap-stdio DAP-over-stdio frontend only
--web Web frontend
--with-dap Also start DAP-over-stdio alongside web
--port N Web server port (0 = let the OS pick a free port) (default: 3000)
--web-port-file PATH Write the actual bound web port to PATH (useful with --port 0 when stdout is unavailable)
--web-unix-socket PATH Serve HTTP over an AF_UNIX socket at PATH instead of a TCP port (overrides --port; reaches clients across a sandbox network namespace via a socat bridge)

#ui

Open the interactive UI (Web / DAP). Default when no command is given.

Usage: hins ui [--dap-stdio | [--web] [--with-dap]] [--port N] [--web-port-file PATH] [--web-unix-socket PATH]
Option Description
--dap-stdio DAP-over-stdio frontend only
--web Web frontend
--with-dap Also start DAP-over-stdio alongside web
--port N Web server port (0 = let the OS pick a free port) (default: 3000)
--web-port-file PATH Write the actual bound web port to PATH (useful with --port 0 when stdout is unavailable)
--web-unix-socket PATH Serve HTTP over an AF_UNIX socket at PATH instead of a TCP port (overrides --port; reaches clients across a sandbox network namespace via a socat bridge)
-h, --help Show this help text

#fragmentation

Block / MBlock fragmentation report. Implicitly pauses.

Usage: hins fragmentation [--include-pinned]
Option Description
--include-pinned Include pinned blocks in the breakdown
-h, --help Show this help text

#consistency

Heap consistency check. Exits non-zero on violations. Implicitly pauses.

Usage: hins consistency
Option Description
-h, --help Show this help text

#closure

Inspect a single closure by id. Implicitly pauses.

Usage: hins closure ID
Option Description
ID Closure id (hex address)
-h, --help Show this help text

#mvars

MVar inventory (paused).

Usage: hins mvars
Option Description
-h, --help Show this help text

#tvars

TVar inventory (paused).

Usage: hins tvars
Option Description
-h, --help Show this help text

#blackholes

Blackhole inventory (paused).

Usage: hins blackholes
Option Description
-h, --help Show this help text

#weaks

Weak reference inventory (paused).

Usage: hins weaks
Option Description
-h, --help Show this help text

#cc-stacks

Cost-centre stack census (target compiled with -prof).

Usage: hins cc-stacks
Option Description
-h, --help Show this help text

#pinned

Pinned-block inventory.

Usage: hins pinned
Option Description
-h, --help Show this help text

#blocks

MBlock / block allocation map.

Usage: hins blocks
Option Description
-h, --help Show this help text

#ticky

Dump ticky-ticky counters (target compiled with -ticky).

Usage: hins ticky
Option Description
-h, --help Show this help text

#heql

Run HEQL (the Heap Exploration Query Language) over the paused heap. Implicitly pauses.

Usage: hins heql [--source TEXT] [--file PATH] [--tag TAG] [--print] [--ast] [--stdlib] [--explain] [--arg NAME=EXPR] [--expand-depth N]
Option Description
--source TEXT Inline query catalog (DSL text). Overrides --file and the built-in defaults.
--file PATH Read the query catalog from PATH instead of the built-in default catalog.
--tag TAG Run only the query whose tag matches TAG.
--print Parse the catalog and report each query without attaching (surfaces parse errors).
--ast heql: parse the catalog and print each declaration's parse tree; no typechecking, no debuggee.
--stdlib heql: print the standard library reference (names, types, grades, descriptions); no debuggee.
--explain heql: print each query's intermediate representations (HEQL Core, FLAX Plan, FLAX bytecode); no debuggee.
--arg NAME=EXPR heql: override a view parameter (repeatable). EXPR is HEQL expression text, checked against the parameter's type.
--expand-depth N heql: auto-run each row's lazy expand handles to depth N, splicing sub-tables into the result as expanded entries. Handles beyond the ceiling stay listed unexpanded; a handle revisiting a node on its own descent path is marked skipped.
-h, --help Show this help text

#threads

Print thread states. Combine with --every for live monitoring.

Usage: hins threads
Option Description
-h, --help Show this help text

#eventlog

Stream eventlog messages. Filter by event kind.

Usage: hins eventlog [--type LIST] [--exclude LIST] [--type-regex RE] [--list-types]
Option Description
--type LIST Comma-separated event-kind names to include (e.g. GC,HeapAllocated)
--exclude LIST Comma-separated event-kind names to exclude
--type-regex RE Power-user escape hatch: regex over event-kind names
--list-types Print the event kinds the target supports and exit
-h, --help Show this help text

#metrics

Stream live time-series metrics.

Usage: hins metrics [--series NAME]
Option Description
--series NAME Restrict to the given metric series; may be repeated
-h, --help Show this help text

#sample

Sampling subcommands.

Usage: hins sample COMMAND
Option Description
-h, --help Show this help text

#sample stacks

Run the STG stack sampler and emit raw samples.

Usage: hins sample stacks [--period US] [--budget N] [--no-resolve | --resolve]
Option Description
--period US Sampler period in microseconds
--budget N Max samples per tick
--no-resolve Keep frame names as raw hex info-table pointers
--resolve Resolve info-table pointers to Module.Label names (default)
-h, --help Show this help text

#sample native

Run the signal-driven native C-stack sampler and emit raw PC samples.

Usage: hins sample native [--period US] [--budget N] [--backend auto|signal|external] [--off-cpu] [--min-block US]
Option Description
--period US Sampler period in microseconds
--budget N Max OS threads signalled per tick
`--backend auto signal
--off-cpu eBPF off-CPU profiling: sample where threads block and for how long (Linux, needs the eBPF engine)
--min-block US off-CPU: ignore blocks shorter than US microseconds (default 1000)
-h, --help Show this help text

#bp

Add a software code breakpoint on a function and stream hits (Linux/x86-64, trace mode).

Usage: hins bp FUNCTION
Option Description
FUNCTION Function name to break on (matched against the IPE map)
-h, --help Show this help text

#exceptions

Capture raised exceptions and aggregate them by type x raise site (live stream).

Usage: hins exceptions [--sync] [--async] [--message] [--deep] [--top N]
Option Description
--sync Capture synchronous exceptions (throw / stg_raisezh)
--async Capture asynchronous exceptions (throwTo / killThread)
--message Extract a bounded UTF-8 exception message
--deep Force exceptions via the RTS hook to recover the real type and message
--top N Show only the top N groups by count
-h, --help Show this help text

#stm-stats

Capture STM transaction outcomes (commit vs conflict re-run) and break down by thread / era / site (live stream, opt-in).

Usage: hins stm-stats [--top N]
Option Description
--top N Show only the top N conflict sites by count
-h, --help Show this help text

#record

Capture to disk: snapshot / eventlog / samples / metrics / all.

Usage: hins record COMMAND
Option Description
-h, --help Show this help text

#record snapshot

Pause, write a heap snapshot, resume.

Usage: hins record snapshot OUT [--format FMT]
Option Description
--format FMT Snapshot format: hins (default, re-open with --snapshot) or ghc-debug (ghc-debug-brick/-client)
-h, --help Show this help text

#record eventlog

Drain the eventlog ring buffer to a .eventlog file.

Usage: hins record eventlog OUT [--buffer-mb N] [--type LIST]
Option Description
--buffer-mb N Ring buffer size
--type LIST Restrict to given event kinds
-h, --help Show this help text

#record samples

Run the stack sampler and write samples (default format: speedscope).

Usage: hins record samples OUT [--period US]
Option Description
--period US Sampler period in microseconds
-h, --help Show this help text

#record metrics

Write a metrics file (default format: csv).

Usage: hins record metrics OUT [--series NAME]
Option Description
--series NAME Restrict to the given metric series
-h, --help Show this help text

#record stack-growth

Arm the threadStackOverflow trap and summarise growth snapshots.

Usage: hins record stack-growth
Option Description
-h, --help Show this help text

#record all

Write snapshot + eventlog + samples + metrics into DIR.

Usage: hins record all DIR
Option Description
-h, --help Show this help text

#report

Run a program to completion (or attach until it exits) and print an end-of-run summary: per-thread max stack + allocations, GC/heap, exceptions, stack growth, and contention.

Usage: hins report [--stack-traces] [--exceptions] [--top N]
Option Description
--stack-traces Include the backtrace captured at each stack-growth event
--exceptions Include exception messages and backtraces (otherwise just counts)
--top N Cap the per-thread tables and leaderboards to the top N entries
-h, --help Show this help text

#list

List live inspectable processes (descriptors published by the connector).

Usage: hins list [--available]
Option Description
--available Only show non-locked processes; in text format, output tab-separated <pid><TAB><prog> lines with no header for easy scripting (awk/cut/xargs).
-h, --help Show this help text

#batch

Run multiple commands against a single pause cycle.

Usage: hins batch [--script PATH]
Option Description
--script PATH Read script from PATH (default: stdin)
-h, --help Show this help text

#list-formats

List available output formats for CMD, or every command if omitted.

Usage: hins list-formats [CMD]
Option Description
-h, --help Show this help text

#help-examples

Print worked examples for the common CLI workflows.

Usage: hins help-examples
Option Description
-h, --help Show this help text

#Environment variables

Variables the inspector and its bundled connector read, discovered by scanning the source. Follow a read site for the surrounding context.

Variable Read at
APPDATA auto_init.c:180
FLAX_BC bc.c:16
FLAX_BENCH_OUT Main.hs:95, Main.hs:135
FLAX_BENCH_PLAN Main.hs:83
FLAX_BENCH_SRC Main.hs:76, Main.hs:108
FLAX_BMAP heap.c:175
FLAX_COLLPAR morsel.c:101
FLAX_COLPAR nodes.c:444
FLAX_DIAG driver.c:1039
FLAX_DOMFAST ops.c:936
FLAX_DRIVER driver.c:113
FLAX_MAX_ALLOC_MB flax_main.c:44
FLAX_MSBFS graph.c:756
FLAX_MSB_MB graph.c:762
FLAX_NOMEMGATE hgroup.c:374
FLAX_OHEXTEND ffi.c:705
FLAX_OHPAR objhash.c:41
FLAX_PAR_MIN nodes.c:351
FLAX_SHAPE_CHECK link.c:547
FLAX_SKIP vec.c:94
FLAX_SYMIDX heap.c:572
FLAX_TRIM Main.hs:136
FLAX_VEC vec.c:50
FLAX_WALKPAR nodes.c:1546
FLAX_WALL_MS flax_main.c:43
FLAX_WORKERS morsel.c:386, ops.c:26, graph.c:116, nodes.c:340, objhash.c:28
FLAX_WORLDPAR ops.c:41
FLAX_WORLDS_PUSH pushdown.c:65
HASKELL_INSPECTOR_BPF_HELPER ebpf_sampler.c:250
HASKELL_INSPECTOR_CAPTURE capture.c:30
HASKELL_INSPECTOR_CONNECTOR_LIB EmbeddedConnector.hs:87, Spawn.hs:98
HASKELL_INSPECTOR_CONNECTOR_RESOLVE Symbolize.hs:123
HASKELL_INSPECTOR_DISABLE auto_init.c:669
HASKELL_INSPECTOR_EBPF_OFFCPU external_sampler.c:1459
HASKELL_INSPECTOR_EBPF_OFFCPU_MIN_BLOCK_US external_sampler.c:1461
HASKELL_INSPECTOR_FORCE auto_init.c:672
HASKELL_INSPECTOR_HEARTBEAT_MS commands.c:274
HASKELL_INSPECTOR_LATENCY_ACTIVE_PROBE latency_monitor.c:887
HASKELL_INSPECTOR_LATENCY_ENABLE latency_monitor.c:883
HASKELL_INSPECTOR_LATENCY_HEARTBEAT_NS latency_monitor.c:877
HASKELL_INSPECTOR_LATENCY_PERIOD_NS latency_monitor.c:868
HASKELL_INSPECTOR_LATENCY_THRESHOLD_NS latency_monitor.c:859
HASKELL_INSPECTOR_LATENCY_TRACE latency_monitor.c:891
HASKELL_INSPECTOR_NATIVE_BACKEND ebpf_sampler.c:525
HASKELL_INSPECTOR_NATIVE_SAMPLE_SIGNAL_OFFSET signal_sampler.c:1530
HASKELL_INSPECTOR_PAUSE_WATCHDOG_MS listen.c:55
HASKELL_INSPECTOR_SAMPLER_TRACE sampler.c:2000
HASKELL_INSPECTOR_SOCKET auto_init.c:698
HASKELL_INSPECTOR_START_PAUSED auto_init.c:638
HASKELL_INSPECTOR_TRACE_CMDS commands.c:2278, eventlog.c:1977, listen.c:30
HASKELL_INSPECTOR_WRITE_TIMEOUT_MS hi_os_transport.c:161
HI_DEREF_STATS HeapAlloced.hs:154
HI_FLAX_TIMING FlaxDump.hs:348
HI_HEAP_TIMING NodeTable.hs:976, Debuggee.hs:480
HI_HEAP_TIMING_LIVE Debuggee.hs:503
HI_HEQL_BENCH BenchMetrics.hs:46
HI_IPE_IDLE_TICKS Base.hs:2186
HI_IPE_TIMING Base.hs:2194
HI_NODETABLE_MC Debuggee.hs:648
HOME auto_init.c:188
TMPDIR auto_init.c:311
USERPROFILE auto_init.c:182
XDG_DATA_HOME auto_init.c:186
Haskell Inspector