Runs
A run is one start of a program under es-python, from launch to exit. This page explains runs, how to narrow the events list to a single run with the run picker, and how counts change when you do.
What a run is
Every time you start a program with es-python (for example es-python app.py --port 8080), that invocation is one run. Each run gets its own id, so two starts of the same command are two runs, even with identical arguments. A worker pool or forked children started by that program belong to the same run.
An event row groups every occurrence of a finding, from every run that ever hit it. Runs let you ask a narrower question: "what did this run of my program find?" This is useful after a test suite, a deployment or a reproduction attempt.
Runs are an es-python feature. A machine reports them once it has been installed (or reinstalled) with an agent that sends run ids.
The run picker
The Runs button (Pick a run...) in the es-python toolbar opens the run picker: every run on your machines, newest first. Click a run to show only the events it produced. If a machine is selected in the Machine filter, the picker lists only that machine's runs.
Each run in the picker shows:
- a short id (the first eight characters of the run id) and when the run started,
- the command line it was started with (secrets shown as
[masked]), or "(command line not sent)" when the machine does not send command lines, - how many distinct events it produced and how many occurrences those add up to.
Type in filter by command line to find runs whose command contains your text. The picker loads 50 runs at a time; Load more fetches the next ones, and Close leaves without choosing.
If the picker says No runs yet, none of your machines have reported runs: reinstall the machine to get an agent that does.
Grouped runs
A run marked grouped instead of an id was reported by an agent that did not send run ids. It stands for every invocation of that command line on that machine, not a single one. Choosing it narrows the list to all events from that command line.
What choosing a run does
Choosing a run sets one condition in Advanced search, Run is <run id>, and opens the panel so you can see it. It replaces any conditions you had there; your toolbar filters, time range and scope stay as they were, so they narrow the run's events further.
Because it is an ordinary condition, the run filter is kept in the page address and in saved searches, and it applies to the Map as well as the list.
To go back to every run, remove the condition with its ×, click Clear in the panel, or click Reset in the toolbar.
From an event
You can also start from an event. Open it, and in its Command line block click Only this run to narrow to the run that produced it, or All runs of this command to see every run started with the same command line (a Command line is ... condition).
Counts under a run filter
While the list is narrowed to exactly one run, the count on each event is that run's own occurrences, not the event's all-time total. Hover the count to check: it says Occurrences in this run or Occurrences in total, across every run.
The per-run count is only used when the conditions pick out one run unambiguously. With Match any, with a Not on the run condition, or with two run conditions, the counts are all-time totals again.
The sidebar counts and the event tally under the toolbar are not affected by a run filter; they always describe the whole list.
How long runs are kept
A run is kept as long as at least one event it produced is still stored. When its events are removed (for example when you delete the machine, or when old events are removed by the retention period), the run disappears from the picker too.