Troubleshooting Buildtest¶
This guide will discuss how to troubleshoot buildtest when you encounter issues.
How to enable debugging?¶
Whenever you run into issues with buildtest, you should enable debug mode by running
buildtest --debug <command>
which will stream debug messages to console. The debug
messages can help pinpoint issues and provide additional details.
buildtest will write a log file, you can view content of log via:
buildtest --view-log
buildtest --print-log
The --print-log
will print output to console, while --view-log
will display in paginated
mode. By default, buildtest will write logfile in $BUILDTEST_ROOT/var/buildtest.log. You can
view path to logfile via buildtest --logpath
.
If you want to filter log messages when running command you can run buildtest --loglevel <LOG_LEVEL>
.
The logging levels are defined in the python
logging library.
The buildtest info
command can be useful when debugging buildtest, it will report a
summary of details related to buildtest and system details that can help pinpoint issue.
How to troubleshoot buildtest configuration?¶
buildtest provides several location where configuration file can be defined. You can
see which configuration file is used by buildtest.
You can retrieve path to configuration used by buildtest by running buildtest config path
.
Check if the path to configuration file is one you want to use.
The environment variable BUILDTEST_CONFIGFILE can be used to specify path to configuration file, you should check if this variable is set in your shell.
To validate your configuration file with JSON Schema you should run the following:
buildtest config validate
If your configuration is invalid, please review the error message and fix the configuration. Please
run buildtest config validate
until your configuration is valid.
Hostname mismatch¶
The configuration file must specify hostnames
for determining where buildtest
can run, please see Configuring Hostnames. If you see an error message when validating configuration
file, please consider updating hostnames
property or login to the desired host where buildtest should
be run. An example below shows an error message when you run into hostname issues.
ConfigurationError: "[/Users/siddiq90/Documents/github/buildtest/buildtest/settings/config.yml]: Based on current system hostname: DOE-7086392.vpn-dhcp.lbl.gov\n we cannot
find a matching system ['generic'] based on current hostnames: {'generic': ['foo']} "
How to troubleshoot a buildspec?¶
If you are developing a buildspec file, please consider checking file is valid, there are several way to validate file, the most convenient way is to run:
buildtest buildspec validate -b <file>
If your buildspec is valid, your next step is to run the test. You should check if test is generated properly,
this can be done by running buildtest build -b <file> --stage=build
which will generate
the test and stop execution. Next you can navigate to the generated test and inspect
the content of test and run your test manually.
How to view past builds?¶
You can access build history via buildtest history
command. To see a list
of builds you can run:
buildtest history list
Next you can query a given build you can run:
buildtest history query <id>
To view output of buildtest build
command for a given build you can run:
buildtest history query -o <id>
The build history is valid until files are removed, which could be done via buildtest clean
or
files are remove manually. The build history provides a means for accessing old builds along with logfile
for each build.