documentation/stubs/00_zmodule_options.html

<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Module Options</title>
</head>
<body>
<p>The following list is the modules included with the Phoronix Test Suite that are intended to extend the functionality of pts-core. Some of these options have commands that can be run directly in a similar manner to the other Phoronix Test Suite user commands. Some modules are just meant to be loaded directly by adding the module name to the AutoLoadModules tag in ~/.phoronix-test-suite/user-config.xml or via the PTS_MODULES environment variable. A list of available modules is also available by running <em>phoronix-test-suite list-modules.</em><hr></p>
<h2>Backup Creation + Restore</h2>
<p>This is a module for creating backups of the Phoronix Test Suite / Phoromatic and allows for restoring of created backups. The backup will be in ZIP or TAR format. If only a path is specified, the file-name will be auto-generated with a current time-stamp.</p>
<p><strong>phoronix-test-suite backup.create</strong></p>
<p><strong>phoronix-test-suite backup.restore</strong></p>
<h2>System Maintenance / Cleanup</h2>
<p>This module can be used for system maintenance cleanup tasks around the Phoronix Test Suite. Currently implemented is support for automatically un-installing tests that have not been run in a period of time. When the module is loaded via the REMOVE_TESTS_OLDER_THAN environment variable, it will be automatically invoked at the end of running any benchmarks. Or this module can be manually invoked with the command: phoronix-test-suite cleanup.tests.</p>
<p><strong>phoronix-test-suite cleanup.tests</strong></p>
<p>This module utilizes the following environment variables: REMOVE_TESTS_OLDER_THAN.</p>
<h2>Dummy Module</h2>
<p>This is a simple module intended for developers to just demonstrate some of the module functions.</p>
<p><strong>phoronix-test-suite dummy_module.dummy-command</strong></p>
<p>This is a simple module intended for developers to just demonstrate some of the module functions.</p>
<h2>Flush Caches</h2>
<p>Loading this module will ensure caches (page cache, swap, etc) automatically get flushed prior to running any test.</p>
<p>This module utilizes the following environment variables: PTS_FLUSH_CACHES.</p>
<h2>Result Exporter To HTML</h2>
<p>This module allows basic exporting of results to HTML for saving either to a file locally (specified using the EXPORT_RESULTS_HTML_FILE_TO environment variable) or to a mail account (specified using the EXPORT_RESULTS_HTML_EMAIL_TO environment variable). EXPORT_RESULTS_HTML_EMAIL_TO supports multiple email addresses delimited by a comma.</p>
<p>This module utilizes the following environment variables: EXPORT_RESULTS_HTML_EMAIL_TO, EXPORT_RESULTS_HTML_FILE_TO.</p>
<h2>Linux Perf Framework Reporter</h2>
<p>Setting LINUX_PERF=1 will auto-load and enable this Phoronix Test Suite module. The module also depends upon running a modern Linux kernel (supporting perf) and that the perf binary is available via standard system paths. Depending upon system permissions you may be limited to using perf as root or adjusting the /proc/sys/kernel/perf_event_paranoid setting.</p>
<p>This module utilizes the following environment variables: LINUX_PERF.</p>
<h2>Dynamic Result Viewer</h2>
<p>This module pre-loads the HTTP dynamic result viewer for Phoronix Test Suite data.</p>
<p><strong>phoronix-test-suite load_dynamic_result_viewer.start</strong></p>
<h2>Log Exporter</h2>
<p>This module allows for easily exporting test run logs and system logs to external locations via specifying the directory paths via the COPY_TEST_RUN_LOGS_TO and COPY_SYSTEM_LOGS_TO environment variables.</p>
<p>This module utilizes the following environment variables: COPY_TEST_RUN_LOGS_TO, COPY_SYSTEM_LOGS_TO.</p>
<h2>MATISK</h2>
<p>My Automated Test Infrastructure Setup Kit</p>
<p><strong>phoronix-test-suite matisk.run</strong></p>
<p><strong>phoronix-test-suite matisk.template</strong></p>
<h2>OpenBenchmarking.org Auto Comparison</h2>
<p>This module prints comparable OpenBenchmarking.org results in the command-line for reference purposes as tests are being run. OpenBenchmarking.org is automatically queried for results to show based on the test comparison hash and the system type (mobile, desktop, server, cloud, workstation, etc). No other system information or result data is transmitted.</p>
<p><strong>phoronix-test-suite ob_auto_compare.debug</strong></p>
<h2>Performance Per Dollar/Cost Calculator</h2>
<p>Setting the COST_PERF_PER_DOLLAR= environment variable to whatever value of the system cost/component you are running a comparison on will yield extra graphs that calculate the performance-per-dollar based on the test being run. The COST_PERF_PER_DOLLAR environment variable is applied just to the current test run identifier. Set the COST_PERF_PER_UNIT= environment variable if wishing to use a metric besides dollar/cost. The COST_PERF_PER_HOUR value can be used rather than COST_PERF_PER_DOLLAR if wishing to calculate the e.g. cloud time or other compute time based on an hourly basis.</p>
<p><strong>phoronix-test-suite perf_per_dollar.add</strong></p>
<p>This module utilizes the following environment variables: COST_PERF_PER_DOLLAR, COST_PERF_PER_UNIT, COST_PERF_PER_HOUR.</p>
<h2>Performance Tip Prompts</h2>
<p>This module alerts the user if the system configuration may not be the right one for achieving the best performance with the target benchmark(s). This initial version of the module actually cares only about the BFQ I/O scheduler and powersave governor checks.</p>
<p><strong>phoronix-test-suite perf_tips.show</strong></p>
<p>This module utilizes the following environment variables: SUPPRESS_PERF_TIPS.</p>
<p>This module alerts the user if the system configuration may not be the right one for achieving the best performance with the target benchmark(s). This initial version of the module actually cares only about the BFQ I/O scheduler: it gives a warning if BFQ is being used with an incorrect configuration in a disk benchmark, and suggests the right configuration to use. For the moment it only works for existing, throughput-based tests. It will need to be extended for responsiveness and soft real-time-latency tests.</p>
<h2>Benchmarking Compiler PGO Impact</h2>
<p>This module makes it easy to test a compiler PGO (Profile Guided Optimization) performance impact by running a test without PGO optimizations, capturing the PGO profile, rebuilding the tests with the PGO profile generated, and then repeat the benchmarks.</p>
<p><strong>phoronix-test-suite pgo.benchmark</strong></p>
<h2>Phoromatic Client</h2>
<p>The Phoromatic client is used for connecting to a Phoromatic server (Phoromatic.com or a locally run server) to facilitate the automatic running of tests, generally across multiple test nodes in a routine manner. For more details visit http://www.phoromatic.com/. This module is intended to be used with Phoronix Test Suite 5.2+ clients and servers.</p>
<p><strong>phoronix-test-suite phoromatic.connect</strong></p>
<p><strong>phoronix-test-suite phoromatic.explore</strong></p>
<p><strong>phoronix-test-suite phoromatic.upload-result</strong></p>
<p><strong>phoronix-test-suite phoromatic.set-root-admin-password</strong></p>
<p><strong>phoronix-test-suite phoromatic.list-results</strong></p>
<p><strong>phoronix-test-suite phoromatic.clone</strong></p>
<p><strong>phoronix-test-suite phoromatic.export-results-for-account-schedules</strong></p>
<p>The Phoromatic module contains the client support for interacting with Phoromatic and Phoromatic Tracker services.</p>
<h2>Pushover.net</h2>
<p>Submit notifications to your iOS/Android mobile devices of test results in real-time as push notifications, etc. Using the Pushover.net API.</p>
<p>This module utilizes the following environment variables: PUSHOVER_NET_USER.</p>
<h2>Report Test Time Graphs</h2>
<p>Setting the RUN_TIMES_ARE_A_BENCHMARK=1 environment variable will automatically create additional graphs for each test run plotting the run-time needed for each test being executed. Setting the INSTALL_TIMES_ARE_A_BENCHMARK=1 environment variable will automatically create additional graphs for each test run plotting the time required for the test installation. Setting the INSTALL_SIZES_ARE_A_BENCHMARK=1 environment variable will automatically create additional graphs for each test run plotting the size of the installed test directory.</p>
<p>This module utilizes the following environment variables: RUN_TIMES_ARE_A_BENCHMARK, INSTALL_TIMES_ARE_A_BENCHMARK, INSTALL_SIZES_ARE_A_BENCHMARK.</p>
<h2>Result Notifier</h2>
<p>A notification module.</p>
<h2>Custom Result Export Methods</h2>
<p>A simple example module about interfacing with Phoronix Test Suite core for dumping result files in a custom format.</p>
<p><strong>phoronix-test-suite results_custom_export.nf</strong></p>
<h2>System Monitor</h2>
<p>This module contains sensor monitoring support.</p>
<p>This module utilizes the following environment variables: MONITOR, PERFORMANCE_PER_WATT, PERFORMANCE_PER_SENSOR, MONITOR_INTERVAL, MONITOR_PER_RUN.</p>
<p>Monitoring these sensors is as easy as running your normal Phoronix Test Suite commands but at the beginning of the command add: MONITOR=&lt;selected sensors&gt;.  For example, this will monitor the CPU temperature and voltage during tests: 

    MONITOR=cpu.temp,cpu.voltage phoronix-test-suite benchmark universe

For some of the sensors there is an ability to monitor specific device, e.g. cpu.usage.cpu0 or hdd.read-speed.sda. If the PERFORMANCE_PER_WATT environment variable is set, a performance per Watt graph will also be added, assuming the system's power consumption can be monitored. PERFORMANCE_PER_SENSOR= will allow similar behavior but for arbitrary sensors. Below are all of the sensors supported by this version of the Phoronix Test Suite.

Supported Options:

  - all
  - all.ambient
  - ambient.temp
  - all.cgroup
  - cgroup.cpu-usage
  - all.cpu
  - cpu.fan-speed
  - cpu.freq
  - all.cpu.freq
  - cpu.freq.cpu0
  - cpu.freq.cpu1
  - cpu.freq.cpu2
  - cpu.freq.cpu3
  - cpu.freq.cpu4
  - cpu.freq.cpu5
  - cpu.freq.cpu6
  - cpu.freq.cpu7
  - cpu.freq.cpu8
  - cpu.freq.cpu9
  - cpu.freq.cpu10
  - cpu.freq.cpu11
  - cpu.freq.cpu12
  - cpu.freq.cpu13
  - cpu.freq.cpu14
  - cpu.freq.cpu15
  - cpu.peak-freq
  - cpu.power
  - cpu.temp
  - cpu.usage
  - all.cpu.usage
  - cpu.usage.cpu0
  - cpu.usage.cpu1
  - cpu.usage.cpu2
  - cpu.usage.cpu3
  - cpu.usage.cpu4
  - cpu.usage.cpu5
  - cpu.usage.cpu6
  - cpu.usage.cpu7
  - cpu.usage.cpu8
  - cpu.usage.cpu9
  - cpu.usage.cpu10
  - cpu.usage.cpu11
  - cpu.usage.cpu12
  - cpu.usage.cpu13
  - cpu.usage.cpu14
  - cpu.usage.cpu15
  - cpu.usage.summary
  - cpu.voltage
  - all.gpu
  - gpu.fan-speed
  - gpu.freq
  - gpu.memory-usage
  - gpu.power
  - gpu.temp
  - gpu.usage
  - gpu.voltage
  - all.hdd
  - hdd.read-speed
  - all.hdd.read-speed
  - hdd.read-speed.sda
  - hdd.read-speed.sdb
  - hdd.read-speed.nvme0n1
  - hdd.temp
  - all.hdd.temp
  - hdd.temp.sda
  - hdd.temp.sdb
  - hdd.temp.nvme0n1
  - hdd.write-speed
  - all.hdd.write-speed
  - hdd.write-speed.sda
  - hdd.write-speed.sdb
  - hdd.write-speed.nvme0n1
  - all.memory
  - memory.temp
  - memory.usage
  - all.swap
  - swap.usage
  - all.sys
  - sys.fan-speed
  - sys.iowait
  - sys.power
  - sys.temp
  - sys.voltage
  - all.sys.voltage

NOTE: Use the "system-sensors" command to see what sensors are available for monitoring on the system.</p>
<h2>Test Timeout</h2>
<p>This module allows killing a test if it exceeds a defined threshold, such as if the test is hung, etc. TEST_TIMEOUT_AFTER= environment variable can be used for controlling the behavior. When this variable is set, the value will can be set to "auto" or a positive integer. The value indicates the number of minutes until a test run should be aborted, such as for a safeguard against hung/deadlocked processes or other issues. Setting this to a high number as a backup would be recommended for fending off possible hangs / stalls in the testing process if the test does not quit on its own for whatever reason. If the value is "auto", it will quit if the time of a test run exceeds 3x the average time it normally takes the particular test to complete its run.</p>
<p>This module utilizes the following environment variables: TEST_TIMEOUT_AFTER.</p>
<h2>Timed Screenshot</h2>
<p>This is a module that will take a screenshot of the system at a pre-defined interval. ImageMagick must be installed onto the system prior to using this module.</p>
<p>This module utilizes the following environment variables: SCREENSHOT_INTERVAL.</p>
<h2>Toggle Screensaver</h2>
<p>This module toggles the system's screensaver while the Phoronix Test Suite is running. At this time, the GNOME and KDE screensavers are supported.</p>
<p>This module utilizes the following environment variables: HALT_SCREENSAVER.</p>
<h2>Linux Turbostat Dumper</h2>
<p>Setting TURBOSTAT_LOG=_DIR_ will auto-load and enable this Phoronix Test Suite module. The module will -- if turbostat is installed on the system and the user is root -- allow dumping of the TurboStat data to the specified directly on a per-test basis. This allows easily collecting of turbostat logs for each test being run. If the TURBOSTAT_LOG= value does not point to a directory, the TurboStat output will be appended to the test run log files.</p>
<p>This module utilizes the following environment variables: TURBOSTAT_LOG.</p>
<h2>Update Checker</h2>
<p>This module checks to see if the Phoronix Test Suite -- and its tests and suites -- are up to date plus also handles message of the day information.</p>
<h2>Utilize Wine On Linux Benchmarking</h2>
<p>This module when activated via the USE_WINE environment variable on Linux systems will override the test profile OS target to Windows and attempt to run the (Windows) tests under Wine, if installed on the system. USE_WINE can be either set to the name of the desired wine command or the absolute path to the wine binary you wish to use for benchmarking.</p>
<p>This module utilizes the following environment variables: USE_WINE.</p>
<h2>System Event Watchdog</h2>
<p>This module has support for stopping/interrupting tests if various system issues occur, like a temperature sensor exceeds a defined threshold.</p>
<p>This module utilizes the following environment variables: WATCHDOG_SENSOR, WATCHDOG_SENSOR_THRESHOLD, WATCHDOG_MAXIMUM_WAIT.</p>
</body>
</html>