Index · Glossary · Cheat sheet
The most-used observer commands, grouped by task. Run them from
tools/insider_lab in a checkout, or write insider-lab live in place of
mix insider.live with the escript from Hex
(mix escript.install hex insider_lab). Replace SESSION_ID, TRACE_ID,
and the pid with the values that earlier commands print.
Contents
- Set up
- Check the node
- Start a session
- Mark, act, and read
- Follow a request or a process
- Stop and report
- Several agents at once
Set up
Make a private cookie once, and boot the target with it. Then set N in
each shell. N is an array, so it works in bash and zsh. See
Boot the target.
(umask 077 && openssl rand -hex 24 > ~/.my_app.cookie)
N=(--node "my_app@$(hostname -s)" --cookie-file "$HOME/.my_app.cookie")
Check the node
See Welcome document and Load Insider into the target.
# Is live observation allowed here? --load installs Insider if it is missing
mix insider.live capabilities "${N[@]}" --load
# The agent quick start
mix insider.live welcome "${N[@]}"
# The whole reference
mix insider.live welcome "${N[@]}" --full
Start a session
See Live observation and Lease.
# Record Logger, OpenTelemetry, and Telemetry events
mix insider.live start "${N[@]}" --component logger --component otel --component telemetry --logger-level info
# State, lease, readers, and recording options
mix insider.live status "${N[@]}" --session SESSION_ID
# Change a recording option of the running session
mix insider.live amend "${N[@]}" --session SESSION_ID --telemetry-measurement duration --reader agent-a
Mark, act, and read
See Pairing marks, Pairing chart, Digest, Known-normal baseline, and Cursors and gaps.
# Serve a live chart for the programmer; give them the URL it prints
mix insider.live chart "${N[@]}" --session SESSION_ID --serve
# Mark the moment before you act
mix insider.live mark "${N[@]}" --session SESSION_ID --label 'about to click Confirm' --reader agent-a
# What happened since the mark, as plain text
mix insider.live digest "${N[@]}" --session SESSION_ID --since-mark 'about to click Confirm' --human
# The events since the newest mark, one line each
mix insider.live events "${N[@]}" --session SESSION_ID --since-mark --format compact
# The events from the start. Continue from the next_cursor it prints
mix insider.live events "${N[@]}" --session SESSION_ID --cursor 0 --limit 100
# Mark the anomalies of the last 5 minutes as normal, so digests lead with new ones
mix insider.live baseline "${N[@]}" --session SESSION_ID --human
# A chart of what happened since the mark, as one HTML file
mix insider.live chart "${N[@]}" --session SESSION_ID --since-mark
Follow a request or a process
See Read one request as a trace, Timeline of a process or request, and One-shot inspections.
# One request as a tree of spans and events
mix insider.live trace "${N[@]}" --session SESSION_ID --trace-id TRACE_ID --human
# Everything one process did, in time order
mix insider.live timeline "${N[@]}" --session SESSION_ID --pid '<0.1234.0>' --human
# One process now: status, memory, links, stack, and mailbox shapes
mix insider.live process "${N[@]}" --name MyApp.Worker
Stop and report
See Stop and check the cleanup receipt and Agent reports.
# Stop, then check the cleanup receipt in the result
mix insider.live stop "${N[@]}" --session SESSION_ID --reader agent-a
#=> {…,"result":{"receipt":{"schema":"insider.collector-session-receipt/v1",…},"state":"stopped",…},…}
# Report a difference between the docs and what you observed
mix insider.live report --category doc_mismatch --message 'welcome says X; observed Y'
Several agents at once
Each mix insider.live command takes Mix's build lock. Build the escript
once, and concurrent commands no longer wait. See
Several agents at once: the escript.
mix escript.build
./insider-lab live status "${N[@]}" --session SESSION_ID