Output Processors

cpustates

Process trace-cmd output to generate timelines and statistics of CPU power state (a.k.a P- and C-state) transitions in the trace.

The results will be written into a subdirectory called “power-stats” under the specified output_basedir.

The output directory will contain the following files:

power-state-stats.csv
Power state residency statistics for each CPU. Shows the percentage of time a CPU has spent in each of its available power states.
parallel-stats.csv
Parallel execution stats for each CPU cluster, and combined stats for the whole system.
power-state-timeline.csv
Timeline of CPU power states. Shows which power state each CPU is in at a point in time.
state-transitions-timeline.csv
Timeline of CPU power state transitions. Each entry shows a CPU’s transition from one power state to another.
utilzation-timeline.csv
Timeline of CPU utilizations.

Note

Timeline entries aren’t at regular intervals, but at times of power transition events.

Stats are generated by assembling a pipeline consisting of the following stages:

  1. Parse trace into trace events
  2. Filter trace events into power state transition events
  3. Record power state transitions
  4. Convert transitions into a power states.
  5. Collapse the power states into timestamped (C state, P state) tuples for each cpu.
  6. Update reporters/stats generators with cpu states.

parameters

use_ratios:

type: 'boolean'

By default proportional values will be reported as percentages, if this flag is enabled, they will be reported as ratios instead.

no_idle:

type: 'boolean'

Indicate that there will be no idle transitions in the trace. By default, a core will be reported as being in an “unknown” state until the first idle transtion for that core. Normally, this is not an issue, as cores are “nudged” as part of the setup to ensure that there is an idle transtion before the meassured region. However, if all idle states for the core have been disabled, or if the kernel does not have cpuidle, the nudge will not result in an idle transition, which would cause the cores to be reported to be in “unknown” state for the entire execution.

If this parameter is set to True, the processor will assume that cores are running prior to the begining of the issue, and they will leave unknown state on the first frequency transition.

split_wfi_states:

type: 'boolean'

WFI is a very shallow idle state. The core remains powered on when in this state, which means the power usage while in this state will depend on the current voltage, and therefore current frequency.

Setting this to True will track time spent in WFI at each frequency separately, allowing to gain the most accurate picture of energy usage.

csv

Creates a results.csv in the output directory containing results for all iterations in CSV format, each line containing a single metric.

parameters

use_all_classifiers:

type: 'boolean'

If set to True, this will add a column for every classifier that features in at least one collected metric.

Note

This cannot be True if extra_columns is set.

global alias: 'use_all_classifiers'

extra_columns:

type: 'list_of_strs'

List of classifiers to use as columns.

Note

This cannot be set if use_all_classifiers is True.

postgres

Stores results in a Postgresql database.

The structure of this database can easily be understood by examining the postgres_schema.sql file (the schema used to generate it): /home/docs/checkouts/readthedocs.org/user_builds/workload-automation/checkouts/stable/doc/source/../../wa/utils/../commands/postgres_schemas/postgres_schema.sql

parameters

username:

type: 'str'

This is the username that will be used to connect to the Postgresql database. Note that depending on whether the user has privileges to modify the database (normally only possible on localhost), the user may only be able to append entries.

default: 'postgres'

password:

type: 'str'

The password to be used to connect to the specified database with the specified username.

dbname:

type: 'str'

Name of the database that will be created or added to. Note, to override this, you can specify a value in your user wa configuration file.

default: 'wa'

host:

type: 'str'

The host where the Postgresql server is running. The default is localhost (i.e. the machine that wa is running on). This is useful for complex systems where multiple machines may be executing workloads and uploading their results to a remote, centralised database.

default: 'localhost'

port:

type: 'str'

The port the Postgresql server is running on, on the host. The default is Postgresql’s default, so do not change this unless you have modified the default port for Postgresql.

default: '5432'

sqlite

Stores results in an sqlite database.

This may be used to accumulate results of multiple runs in a single file.

parameters

database:

type: 'str'

Full path to the sqlite database to be used. If this is not specified then a new database file will be created in the output directory. This setting can be used to accumulate results from multiple runs in a single database. If the specified file does not exist, it will be created, however the directory of the file must exist.

Note

The value must resolve to an absolute path, relative paths are not allowed; however the value may contain environment variables and/or the home reference “~”.

global alias: 'sqlite_database'

overwrite:

type: 'boolean'

If True, this will overwrite the database file if it already exists. If False (the default) data will be added to the existing file (provided schema versions match – otherwise an error will be raised).

global alias: 'sqlite_overwrite'

status

Outputs a txt file containing general status information about which runs failed and which were successful

targz

Create a tarball of the output directory.

This will create a gzip-compressed tarball of the output directory. By default, it will be created at the same level and will have the same name as the output directory but with a .tar.gz extensions.

parameters

outfile:

type: 'str'

The name of the output file to be used. If this is not an absolute path, the file will be created realtive to the directory in which WA was invoked. If this contains subdirectories, they must already exist.

The name may contain named format specifiers. Any of the RunInfo fields can be named, resulting in the value of that filed (e.g. 'start_time') being formatted into the tarball name.

By default, the output file will be created at the same level, share the name of the WA output directory (but with .tar.gz extension).

delete_output:

type: 'boolean'

if set to True, WA output directory will be deleted after the tarball is created.

uxperf

Parse logcat for UX_PERF markers to produce performance metrics for workload actions using specified instrumentation. An action represents a series of UI interactions to capture. NOTE: The UX_PERF markers are turned off by default and must be enabled in a agenda file by setting markers_enabled for the workload to True.