Man page
Description
bisector is a git bisect run [1] compatible tool used in LISA. Its goal is
to sequence commands to be repeated an arbitrary number of times and generates
a report.
For example, bisector can be used to compile a kernel, flash a board,
reboot it and run test suite. To achieve that, bisector runs a sequence of
steps, and saves a report file containing the result of each step. This step
sequence is run for a number of iterations, or for a given duration. That
allows tracking fluctuating bugs by repeating a test process many times.
The steps class can implement any run or report behavior, with the ability to
take parameters. They also decide what data is saved into the report, and
their contribution to the overall git bisect result:
good: the test steps passed
bad: the test steps failed
untestable: the build or flash step failed
abort: the reboot step failed, and the board is now unusable and requires manual intervention
NA: the step will not impact the overall result
It is important to note that bisector step classes usually only invoke a
user-specified command line tool and will use the return code to decide what
git bisect result to return. They can also implement more specific result
reporting, and additional run behaviors.
Options
bisector
usage: bisector [-h] [--cli-options CLI_OPTIONS]
{step-help,run,report,edit,monitor-server,monitor} ...
Git-bisect-compatible command sequencer.
bisector allows to run commands with timeout handling in predefined
sequences (steps). The output is saved in a report that can be later
analyzed. The exit status of all steps is merged to obtain a git bisect
compatible value which is returned. The error code 254 is used
when bisector itself encounters an error.
SIGNAL HANDLING
The script can be stopped with SIGINT (Ctrl-C) or SIGTERM (kill or timeout
commands) or SIGHUP (when the terminal dies) and will save the completed
iterations to the report. The execution can later be resumed with --resume.
options:
-h, --help show this help message and exit
--cli-options CLI_OPTIONS
YAML file containing command line option string in a
"cmd-line" toplevel key. Therefore, the same file can be used
for --steps. The options are inserted at the location of
--cli-options in the command line. That can be used to control what
can be overriden by configuration file and what is forced by the
command line
subcommands:
{step-help,run,report,edit,monitor-server,monitor}
bisector run
usage: bisector run [-h] [--cli-options CLI_OPTIONS] [-o OPTION] [--debug]
[--steps STEPS] [--allowed-bad ALLOWED_BAD] [--skip SKIP]
[--only ONLY] [--git-clean] [--inline CLASS NAME]
[-n ITERATIONS] [--timeout TIMEOUT] [--log LOG]
[--report REPORT] [--overwrite] [--resume] [--desc DESC]
[--early-bailout] [--upload-report] [--dbus | --no-dbus]
Run the given steps in a loop and record the result in a report file. The
report file can be inspected using the "report" subcommand. The exit status is
suitable for git bisect.
options:
-h, --help show this help message and exit
--cli-options CLI_OPTIONS
YAML file containing command line option string in a
"cmd-line" toplevel key. Therefore, the same file can
be used for --steps. The options are inserted at the
location of --cli-options in the command line. That
can be used to control what can be overriden by
configuration file and what is forced by the command
line
-o OPTION, --option OPTION
Step-specific options. Can be repeated. The format is
<step category or name pattern>.<option>=<value>. If
the step name or category is omitted, it will be
passed to all steps. See "step-help" subcommand for
the available options. Options specified this way
override the steps definition file, and can be used to
modify the report when used with run --resume or edit
subcommand.
--debug Show Python traceback to help debugging this script.
--steps STEPS YAML configuration of steps to run. The steps
definitions lives under a "step" toplevel key.
--allowed-bad ALLOWED_BAD
Percentage of bad iterations that still result in a
good overall result.
--skip SKIP Step name or category to skip. Can be repeated.
--only ONLY Step name or category to execute. Can be repeated.
--git-clean Run git reset --hard and git clean -fdx before and
after the steps are executed. It is useful for
automated bisect to avoid checkout failure that leads
to bisect abortion. WARNING: this will erase all
changes and untracked files from the worktree.
--inline CLASS NAME, -s CLASS NAME
Class and name of inline step. Can be repeated to
build a list of steps in the order of appearance.
-n ITERATIONS, --iterations ITERATIONS
Number of iterations. "inf" means an infinite number
of iterations.
--timeout TIMEOUT Timeout after which no more itertions will be started.
"inf" means infinite timeout (i.e. no timeout).
--log LOG Log all events to the log file. By default, a log file
is created as <report file>.log .
--report REPORT Execution report containing output and return values
for all steps. Can be displayed using the "report"
subcommand. The {commit} placeholder is replaced with
the truncated sha1 of HEAD in current directory, and
{date} by a string built from the current date and
time. If the file name ends with .pickle or
.pickle.gz, a Pickle file is created, otherwise YAML
format is used. YAML is good for archiving but slow to
generate and load, Pickle format cannot expected to be
backward compatible with different versions of the
tool but can be faster to read and write. CAVEAT:
Pickle format will not handle references to modules
that are not in sys.path.
--overwrite Overwrite existing report files.
--resume Resume execution from the report specified with
--report. The steps will be extracted from the report
instead of from the command line. The number of
completed iterations will be deducted from the
specified number of iterations.
--desc DESC Report description. Can use {commit} and {date}
placeholders.
--early-bailout Restart a new iteration if a step marked the commit as
bad or non-testable. Bisect abortion will still take
place even without this option.
--upload-report Continuously upload the report to an artifacts service
after every iteration. This relies on the following
environment variables: ARTIFACTORY_FOLDER or
ARTIFACTORIAL_FOLDER set to the folder's URL and
ARTIFACTORY_TOKEN or ARTIFACTORIAL_TOKEN set to the
token. Remember to use the right step option to upload
the results as they are computed if desired.
--dbus Try enable DBus API if the necessary dependencies are
installed.
--no-dbus Disable DBus even when pydbus module is available.
bisector report
usage: bisector report [-h] [--cli-options CLI_OPTIONS] [-o OPTION] [--debug]
[--steps STEPS] [--allowed-bad ALLOWED_BAD]
[--skip SKIP] [--only ONLY] [--export EXPORT] [--cache]
report
Analyze a report generated by run command. The exit status is suitable for git
bisect. In most cases, step options (``-o``) will act as filters to ignore
parts of the data before computing the overall bisect result.
positional arguments:
report Read back a previous session saved using --report
option of run subcommand.
options:
-h, --help show this help message and exit
--cli-options CLI_OPTIONS
YAML file containing command line option string in a
"cmd-line" toplevel key. Therefore, the same file can
be used for --steps. The options are inserted at the
location of --cli-options in the command line. That
can be used to control what can be overriden by
configuration file and what is forced by the command
line
-o OPTION, --option OPTION
Step-specific options. Can be repeated. The format is
<step category or name pattern>.<option>=<value>. If
the step name or category is omitted, it will be
passed to all steps. See "step-help" subcommand for
the available options. Options specified this way
override the steps definition file, and can be used to
modify the report when used with run --resume or edit
subcommand.
--debug Show Python traceback to help debugging this script.
--steps STEPS YAML configuration of steps to run. The steps
definitions lives under a "step" toplevel key.
--allowed-bad ALLOWED_BAD
Percentage of bad iterations that still result in a
good overall result.
--skip SKIP Step name or category to skip. Can be repeated.
--only ONLY Step name or category to execute. Can be repeated.
--export EXPORT Export the report as a Pickle or YAML file. File
format is infered from the filename. If it ends with
.pickle, a Pickle file is created, otherwise YAML
format is used.
--cache When loading a report, create a cache file named
"{report_filename}.cache.pickle" using the fastest
format available. It is the reused until the original
file is modified. This is mostly useful when working
with big YAML files that are long to load.
bisector step-help
Steps-specific options to be used with bisector run -o and bisector report -o.
LISA-test (test)
----------------
Inherits from: shell
Execute an exekall LISA test command and collect
:class:`exekall.engine.ValueDB`. Also compress the result directory and
record its path. It will also define some environment variables that are
expected to be used by the command to be able to locate resources to
collect.
run:
-o bail-out= (bool)
start a new iteration if the command fails, without executing
remaining steps for this iteration
-o cmd= (non-empty str)
shell command to be executed
-o compress-artifact= (bool)
compress the exekall artifact directory in an archive
-o delete-artifact= (bool)
delete the exekall artifact directory to Artifactorial as the
execution goes.
-o delete-artifact-hidden= (bool)
Remove hidden files and folders inside the artifacts
-o env= (env var list)
environment variables with a list of values that will be used for
each iterations, wrapping around. The string format is:
VAR1=val1%val2%...%%VAR2=val1%val2%.... In YAML, it is a map of var
names to list of values. A single string can be supplied instead of
a list of values.
-o kill-timeout= (int or "inf")
time to wait before sending SIGKILL after having sent SIGTERM
-o prune-db= (bool)
Prune exekall's ValueDB so that only roots values are preserved.
That allows smaller reports that are faster to load
-o shell= (non-empty str)
shell to execute the command in
-o timeout= (int or "inf")
timeout in seconds before sending SIGTERM to the command, or "inf"
for infinite timeout
-o upload-artifact= (bool)
upload the exekall artifact directory to Artifactorial as the
execution goes, and delete the local archive.
-o use-systemd-run= (bool)
use systemd-run to run the command. This allows cleanup of daemons
spawned by the command (using cgroups), and using a private /tmp
that is also cleaned up automatically
report:
-o download= (bool)
Download the exekall artifact archives if necessary
-o dump-artifact-dirs= (non-empty str)
write the list of exekall artifact directories to a file. Useful to
implement garbage collection of unreferenced artifact archives
-o export-db= (non-empty str)
export a merged exekall ValueDB, merging it with existing ValueDB if
the file exists
-o export-logs= (non-empty str)
export the logs and artifact directory symlink to the given
directory
-o ignore-excep= (comma-separated list)
ignore the given comma-separated list of exceptions class name
patterns that caused tests error. This will also match on base
classes of the exception.
-o ignore-non-error= (bool)
consider only tests that had an error
-o ignore-non-issue= (bool)
consider only tests that failed or had an error
-o ignore-testcase= (comma-separated list)
completely ignore untagged test cases matching one of the patterns
in the comma-separated list. * can be used to match any part of the
name.
-o iterations= (comma-separated list of integer ranges)
comma-separated list of iterations to consider. Inclusive ranges can
be specified with <first>-<last>
-o result-uuid= (comma-separated list)
show only the test results with a UUID in the comma-separated list.
-o show-artifact-dirs= (bool)
show exekall artifact directory for all iterations
-o show-basic= (bool)
show command exit status for all iterations
-o show-details= ("msg" or bool)
show details of results. Use "msg" for only a brief message
-o show-dist= (bool)
show graphical distribution of issues among iterations with a one
letter code: passed=".", failed="F", error="#", skipped="s",
undecided="u"
-o show-pass-rate= (bool)
always show the pass rate of tests, even when there are failures or
errors as well
-o show-rates= (bool)
show percentages of failure, error, skipped, undecided and passed
tests
-o testcase= (comma-separated list)
show only the untagged test cases matching one of the patterns in
the comma-separated list. * can be used to match any part of the
name
-o upload-artifact= (bool)
upload the artifact directory to an artifacts service and update the
in-memory report. Following env var are needed: ARTIFACTORY_FOLDER
or ARTIFACTORIAL_FOLDER set to the folder URL, and ARTIFACTORY_TOKEN
or ARTIFACTORIAL_TOKEN. Note: --export should be used to save the
report with updated paths
-o verbose= (bool)
increase verbosity
build (build)
-------------
Inherits from: shell
Similar to :class:`ShellStep` .
Non-zero exit status of the command will be interpreted as a bisect
untestable status, and zero exit status as bisect good.
run:
-o bail-out= (bool)
start a new iteration if the command fails, without executing
remaining steps for this iteration
-o cmd= (non-empty str)
shell command to be executed
-o env= (env var list)
environment variables with a list of values that will be used for
each iterations, wrapping around. The string format is:
VAR1=val1%val2%...%%VAR2=val1%val2%.... In YAML, it is a map of var
names to list of values. A single string can be supplied instead of
a list of values.
-o kill-timeout= (int or "inf")
time to wait before sending SIGKILL after having sent SIGTERM
-o shell= (non-empty str)
shell to execute the command in
-o timeout= (int or "inf")
timeout in seconds before sending SIGTERM to the command, or "inf"
for infinite timeout
-o trials= (int)
number of times the command will be retried if it does not return 0
-o use-systemd-run= (bool)
use systemd-run to run the command. This allows cleanup of daemons
spawned by the command (using cgroups), and using a private /tmp
that is also cleaned up automatically
report:
-o export-logs= (non-empty str)
export the logs to the given directory
-o ignore-non-issue= (bool)
consider only iteration with non-zero command exit status
-o iterations= (comma-separated list of integer ranges)
comma-separated list of iterations to consider. Inclusive ranges can
be specified with <first>-<last>
-o show-basic= (bool)
show command exit status for all iterations
-o verbose= (bool)
increase verbosity
flash (flash)
-------------
Inherits from: shell
Similar to :class:`ShellStep` .
Non-zero exit status of the command will be interpreted as a bisect
abort, and zero exit status ignored.
run:
-o bail-out= (bool)
start a new iteration if the command fails, without executing
remaining steps for this iteration
-o cmd= (non-empty str)
shell command to be executed
-o env= (env var list)
environment variables with a list of values that will be used for
each iterations, wrapping around. The string format is:
VAR1=val1%val2%...%%VAR2=val1%val2%.... In YAML, it is a map of var
names to list of values. A single string can be supplied instead of
a list of values.
-o kill-timeout= (int or "inf")
time to wait before sending SIGKILL after having sent SIGTERM
-o shell= (non-empty str)
shell to execute the command in
-o timeout= (int or "inf")
timeout in seconds before sending SIGTERM to the command, or "inf"
for infinite timeout
-o trials= (int)
number of times the command will be retried if it does not return 0
-o use-systemd-run= (bool)
use systemd-run to run the command. This allows cleanup of daemons
spawned by the command (using cgroups), and using a private /tmp
that is also cleaned up automatically
report:
-o export-logs= (non-empty str)
export the logs to the given directory
-o ignore-non-issue= (bool)
consider only iteration with non-zero command exit status
-o iterations= (comma-separated list of integer ranges)
comma-separated list of iterations to consider. Inclusive ranges can
be specified with <first>-<last>
-o show-basic= (bool)
show command exit status for all iterations
-o verbose= (bool)
increase verbosity
macro (macro)
-------------
Provide a loop-like construct to the steps definitions.
All sub-steps will be executed in order. This sequence will be repeated
for the given number of iterations or until it times out. The steps
definition YAML configuration file is interpreted assuming an implicit
toplevel :class:`MacroStep` that is parameterized using command line options.
run:
-o bail-out-early= (bool)
start a new iteration when a step returned bisect status bad or
untestable and skip all remaining steps
-o iterations= (int or "inf")
number of iterations
-o timeout= (int or "inf")
time after which no new iteration will be started
reboot (boot)
-------------
Inherits from: shell
Similar to :class:`ShellStep` .
Non-zero exit status of the command will be interpreted as a bisect
abort, and zero exit status as bisect good.
run:
-o bail-out= (bool)
start a new iteration if the command fails, without executing
remaining steps for this iteration
-o cmd= (non-empty str)
shell command to be executed
-o env= (env var list)
environment variables with a list of values that will be used for
each iterations, wrapping around. The string format is:
VAR1=val1%val2%...%%VAR2=val1%val2%.... In YAML, it is a map of var
names to list of values. A single string can be supplied instead of
a list of values.
-o kill-timeout= (int or "inf")
time to wait before sending SIGKILL after having sent SIGTERM
-o shell= (non-empty str)
shell to execute the command in
-o timeout= (int or "inf")
timeout in seconds before sending SIGTERM to the command, or "inf"
for infinite timeout
-o trials= (int)
number of times the command will be retried if it does not return 0
-o use-systemd-run= (bool)
use systemd-run to run the command. This allows cleanup of daemons
spawned by the command (using cgroups), and using a private /tmp
that is also cleaned up automatically
report:
-o export-logs= (non-empty str)
export the logs to the given directory
-o ignore-non-issue= (bool)
consider only iteration with non-zero command exit status
-o iterations= (comma-separated list of integer ranges)
comma-separated list of iterations to consider. Inclusive ranges can
be specified with <first>-<last>
-o show-basic= (bool)
show command exit status for all iterations
-o verbose= (bool)
increase verbosity
shell (shell)
-------------
Execute a command in a shell.
Stdout and stderr are merged and logged. The exit status of the command
will have no influence of the bisect status.
run:
-o bail-out= (bool)
start a new iteration if the command fails, without executing
remaining steps for this iteration
-o cmd= (non-empty str)
shell command to be executed
-o env= (env var list)
environment variables with a list of values that will be used for
each iterations, wrapping around. The string format is:
VAR1=val1%val2%...%%VAR2=val1%val2%.... In YAML, it is a map of var
names to list of values. A single string can be supplied instead of
a list of values.
-o kill-timeout= (int or "inf")
time to wait before sending SIGKILL after having sent SIGTERM
-o shell= (non-empty str)
shell to execute the command in
-o timeout= (int or "inf")
timeout in seconds before sending SIGTERM to the command, or "inf"
for infinite timeout
-o trials= (int)
number of times the command will be retried if it does not return 0
-o use-systemd-run= (bool)
use systemd-run to run the command. This allows cleanup of daemons
spawned by the command (using cgroups), and using a private /tmp
that is also cleaned up automatically
report:
-o export-logs= (non-empty str)
export the logs to the given directory
-o ignore-non-issue= (bool)
consider only iteration with non-zero command exit status
-o iterations= (comma-separated list of integer ranges)
comma-separated list of iterations to consider. Inclusive ranges can
be specified with <first>-<last>
-o show-basic= (bool)
show command exit status for all iterations
-o verbose= (bool)
increase verbosity
test (test)
-----------
Inherits from: shell
Similar to :class:`ShellStep` .
Non-zero exit status of the command will be interpreted as a bisect bad
status, and zero exit status as bisect good.
run:
-o bail-out= (bool)
start a new iteration if the command fails, without executing
remaining steps for this iteration
-o cmd= (non-empty str)
shell command to be executed
-o env= (env var list)
environment variables with a list of values that will be used for
each iterations, wrapping around. The string format is:
VAR1=val1%val2%...%%VAR2=val1%val2%.... In YAML, it is a map of var
names to list of values. A single string can be supplied instead of
a list of values.
-o kill-timeout= (int or "inf")
time to wait before sending SIGKILL after having sent SIGTERM
-o shell= (non-empty str)
shell to execute the command in
-o timeout= (int or "inf")
timeout in seconds before sending SIGTERM to the command, or "inf"
for infinite timeout
-o trials= (int)
number of times the command will be retried if it does not return 0
-o use-systemd-run= (bool)
use systemd-run to run the command. This allows cleanup of daemons
spawned by the command (using cgroups), and using a private /tmp
that is also cleaned up automatically
report:
-o export-logs= (non-empty str)
export the logs to the given directory
-o ignore-non-issue= (bool)
consider only iteration with non-zero command exit status
-o iterations= (comma-separated list of integer ranges)
comma-separated list of iterations to consider. Inclusive ranges can
be specified with <first>-<last>
-o show-basic= (bool)
show command exit status for all iterations
-o verbose= (bool)
increase verbosity
yield (yield)
-------------
Abort current iteration with the yield return code.
If the specified command returns a non-zero return code, bisector will
abort the current iteration with the yield return code.
.. note:: This step can only be used under the main macrostep (it cannot be
used in nested macrosteps).
run:
-o bail-out= (bool)
start a new iteration if the command fails, without executing
remaining steps for this iteration
-o cmd= (non-empty str)
shell command to be executed
-o env= (env var list)
environment variables with a list of values that will be used for
each iterations, wrapping around. The string format is:
VAR1=val1%val2%...%%VAR2=val1%val2%.... In YAML, it is a map of var
names to list of values. A single string can be supplied instead of
a list of values.
-o every-n-iterations= (int)
The step will be a no-op except if the iteration number can be
evenly divided by that value.
-o kill-timeout= (int or "inf")
time to wait before sending SIGKILL after having sent SIGTERM
-o shell= (non-empty str)
shell to execute the command in
-o timeout= (int or "inf")
timeout in seconds before sending SIGTERM to the command, or "inf"
for infinite timeout
-o trials= (int)
number of times the command will be retried if it does not return 0
-o use-systemd-run= (bool)
use systemd-run to run the command. This allows cleanup of daemons
spawned by the command (using cgroups), and using a private /tmp
that is also cleaned up automatically
bisector monitor
usage: bisector monitor [-h] [--cli-options CLI_OPTIONS] [--status]
[--prop PROP] [--list]
[--pause | --stop | --continue | --kill | --log | --report ... | --notif enable/disable PROPERTY]
PID
Monitor and control a running instance.
positional arguments:
PID Slave PID to act on or "all". Start a monitor-server
before using "all".
options:
-h, --help show this help message and exit
--cli-options CLI_OPTIONS
YAML file containing command line option string in a
"cmd-line" toplevel key. Therefore, the same file can
be used for --steps. The options are inserted at the
location of --cli-options in the command line. That
can be used to control what can be overriden by
configuration file and what is forced by the command
line
--status Show status.
--prop PROP Show given property.
--list List all slaves.
--pause Pause at the end of the iteration.
--stop Stop at the end of the iteration.
--continue Continue paused or stopped instance.
--kill Kill the given instance.
--log Show log in $PAGER.
--report ... Equivalent to running bisector report, all remaining
options being passed to it.
--notif enable/disable PROPERTY
Enable and disable desktop notifications when the
given property changes. 'all' will select all
properties.
bisector monitor-server
usage: bisector monitor-server [-h] [--cli-options CLI_OPTIONS]
[--notif enable/disable PROPERTY]
Start the DBus server to allow monitoring all running instances. Note that the
server is not necessary to monitor a specific run instance.
options:
-h, --help show this help message and exit
--cli-options CLI_OPTIONS
YAML file containing command line option string in a
"cmd-line" toplevel key. Therefore, the same file can
be used for --steps. The options are inserted at the
location of --cli-options in the command line. That
can be used to control what can be overriden by
configuration file and what is forced by the command
line
--notif enable/disable PROPERTY
Enable and disable desktop notifications when the
given property changes. 'all' will select all
properties.
bisector edit
usage: bisector edit [-h] [-o OPTION] [--debug] [--steps STEPS] report
Modify the properties of the steps in an existing report.
positional arguments:
report Report to edit.
options:
-h, --help show this help message and exit
-o OPTION, --option OPTION
Step-specific options. Can be repeated. The format is
<step category or name pattern>.<option>=<value>. If
the step name or category is omitted, it will be
passed to all steps. See "step-help" subcommand for
the available options. Options specified this way
override the steps definition file, and can be used to
modify the report when used with run --resume or edit
subcommand.
--debug Show Python traceback to help debugging this script.
--steps STEPS YAML configuration of steps used to find new paths of
classes if necessary. It is otherwise ignored and
--option must be used to edit the report.
Configuration
bisector run is configured using a YAML [2] file specified using --steps that
defines the steps that will be executed in a loop. Each declared step has a (usually
unique) name and a class that will influence the way its result is used and its
options.
The YAML file is structured as following:
# Top-level "steps" key is important as the same file can be used to host other
# information.
steps:
# build step will interpret a non-zero exit status of the command as a
# bisect untestable status, and zero exit status as bisect good.
-
class: BuildStep
cmd: make defconfig Image dtbs
trials: 1
# flash step will interpret a non-zero exit status of the command as a
# bisect abort, and zero exit status ignored.
-
class: FlashStep
cmd: flash-my-board
timeout: 180
trials: 5
# reboot step will interpret a non-zero exit status of the command as a
# bisect abort, and zero exit status as bisect good.
-
class: reboot
timeout: 300
trials: 10
cmd: reboot-my-board
# exekall LISA test will interpret a non-zero exit status of the command
# as bisect bad, and a zero exit status as bisect good.
-
class: LISA-test
name: one-small-task
# Using systemd-run ensures all child process is killed if the session
# is interrupted
use-systemd-run: true
timeout: 3600
cmd: lisa-test 'OneSmallTask*'
All step options can also be specified using --options/-o, which will
override what is described in the YAML steps configuration.
Monitoring
bisector run allows some live monitoring by exposing a DBus interface. This
is used by two subcommands: bisector monitor-server and bisector
monitor.
Server
bisector monitor-server acts as a registry of all bisector run
executing under the same user (DBus session bus). It allows bisector
monitor to list active instances and also forwards desktop notifications to
the desktop environment. The server can be (re)started after bisector run
if necessary.
Monitor
bisector monitor allows listing active instances of bisector run (when
the server is running), and allows querying various information from them.
Since the query can be directed to a specific PID, the server is only necessary
for listing.
Examples
A typical flow of bisector looks like that:
# Run the steps and generate a report.
# systemd-run will be used for all steps by using "-o" without specifying a
step name or category.
bisector run --desc "description of my report" --steps bisector_steps.yaml --report bisector.report.yml.gz -ouse-systemd-run=yes
# Later inspection of the report, only looking at the steps that have "test"
# name or category.
bisector report bisector.report.yml.gz
# Show steps with the "test" name or category
bisector report bisector.report.yml.gz --only test
# Help of a exekall LISA's step options
bisector step-help LISA-test
# Get all information about tests failures
bisector report bisector.report.yml.gz -overbose
# Show the tests failure backtraces and messages, and the metrics in the
# other cases.
# -oshow-details=msg only displays the message without the backtrace
bisector report bisector.report.yml.gz -oshow-details
# Ignore some exceptions in LISA results
# These exceptions are related to network/ssh issues and are usually not interesting
bisector report bisector.report.yml.gz -oignore-excep=ExceptionPxssh,HostError,TimeoutError
# Only show the results of a specific test case
# the name is as reported by exekall, so it is best to use * to match the
# boilerplate prefix.
# For example -otestcase='OneSmallTask:*' will match both
# "OneSmallTask:test_slack" and "OneSmallTask:test_task_placement".
bisector report bisector.report.yml.gz -otestcase='OneSmallTask:*'
# Only consider iterations 1 to 5, 42 and 56
# Useful to limit the amount of downloaded result archives
bisector report bisector.report.yml.gz -oiterations=1-5,42,56
# Ignore LISA tests results that are not failures
# use that to only download the result archives for failed tests.
bisector report bisector.report.yml.gz -oignore-non-issue
# Download the archives of failed tests and export stdout/sdterr logs to files in
# the "logs" directory.
# The hierarchy created is <folder to export to>/<step name>/<iteration number>
# This will create files for commands output, xUnit files and download the result archives.
bisector report bisector.report.yml.gz -oexport-logs=logs
# "-oXXXX=YYYY" options can be applied to a specific step instead of all of them using
# -o <step name or category>.XXXX=YYYY
# This command will only show iteration #2 for the eas_behaviour step
bisector report bisector.report.yml.gz -oeas_behaviour.iterations=2