Packages
The BEAM accessory for agents, by agents. A runtime-evidence library that attaches to a running development node and gives a coding agent a bounded, masked window of what the node did: structured events, request traces and process snapshots.
Current section
Files
Jump to
Current section
Files
docs/cheat-sheet.md
# Cheat sheet
[Index](README.md) · [Glossary](glossary.md) · [Cheat sheet](cheat-sheet.md)
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](#set-up)
- [Check the node](#check-the-node)
- [Start a session](#start-a-session)
- [Mark, act, and read](#mark-act-and-read)
- [Follow a request or a process](#follow-a-request-or-a-process)
- [Stop and report](#stop-and-report)
- [Several agents at once](#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](live/live-api-and-transports.md#boot-the-target).
```sh
(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](live/live-welcome-and-reports.md#welcome-document) and
[Load Insider into the target](live/live-api-and-transports.md#load-insider-into-the-target).
```sh
# 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](live/live-api-and-transports.md#live-observation) and
[Lease](live/live-api-and-transports.md#lease).
```sh
# 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](live/live-sessions-and-readers.md#pairing-marks),
[Pairing chart](live/live-sessions-and-readers.md#pairing-chart),
[Digest](live/live-digest-filters-and-trends.md#digest),
[Known-normal baseline](live/live-digest-filters-and-trends.md#known-normal-baseline), and
[Cursors and gaps](live/live-sessions-and-readers.md#cursors-and-gaps).
```sh
# 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](live/live-otel-traces.md#read-one-request-as-a-trace),
[Timeline of a process or request](live/live-otel-traces.md#timeline-of-a-process-or-request),
and [One-shot inspections](live/live-runtime-evidence.md#one-shot-inspections).
```sh
# 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](live/live-api-and-transports.md#stop-and-check-the-cleanup-receipt)
and [Agent reports](live/live-welcome-and-reports.md#agent-reports).
```sh
# 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](live/live-api-and-transports.md#several-agents-at-once-the-escript).
```sh
mix escript.build
./insider-lab live status "${N[@]}" --session SESSION_ID
```