workload-automation/doc/source/developer_reference/APIs.rst

APIs
====

.. _output_processing_api:

Output Processing API
---------------------

WA3 now has an output API that can be used to post process a runs
:ref:`Output Directory Structure <output_directory>` which can be performed by using WA's
:class:`RunOutput` object.

This object provides a simple way to access the various aspects of the run. A
few of the most useful attributes of the ``RunOutput`` object are as follows:

- :confval:`jobs` - A list of all the job outputs that were generated for the
  run. These can be used to used to access more detailed information about
  individual jobs for example their ``status``, any ``metrics`` or ``artifacts``
  that were generated etc.
- :confval:`run_config` - A :ref:`RunConfiguration <run-configuration>` object
  that can be used to access all the configuration of the run itself, for
  example the ``reboot_policy``, ``execution_order``, ``device_config`` etc.
- :confval:`target_info` - A :ref:`TargetInfo <target-info-api>` object which can be used to
  access various information about the target that was used during the run for
  example it's ``abi``, ``hostname``, ``os`` etc.
- :confval:`info` - A :ref:`RunInfo <run-info-api>` object that contains
  information about the run itself for example it's duration, name, uuid etc.
- :confval:`settings` - The :ref:`Meta Configuration <meta-configuration>` used
  during the run.
- :confval:`status` - The overall status of the run.
- :confval:`artifacts` - A list containing any run level artifacts (for example
  logs, output generated by output processors etc.).
- :confval:`metrics` - A list of :ref:`Metrics <metrics>` that were generated
  for the overall run.
- :confval:`classifiers` - A dict mapping of any run level
  :ref:`classifiers  <classifiers>`.
- :confval:`augmentations` - A list of the augmentations that were enabled
  during the run.
- :confval:`event_summary` - A condensed summary of any events that occurred
  during the run.
- :confval:`events` - A list of any events that occurred during the run like job
  failures etc.
- :confval:`basepath` - The name of the base WA output directory.
- :confval:`configfile` - The relative file path to the config file generated
  for the run.
- :confval:`failed_dir` - The relative file path to the directory containing any
  failed jobs during the run.
- :confval:`infofile` - The file location of the json serialized file of the
  :class:`RunInfo` object.
- :confval:`list_workloads()` - A method that generated a list of the workload
  names that were executed during the run.
- :confval:`logfile` - A relative file path to the run log.
- :confval:`metadir` - A relative file path to the metadata directory.
- :confval:`targetfile` - The file location of the json serialized file of the
  :class:`TargetInfo` object.

.. include:: developer_reference/output_processing_example.rst

---------------------

.. _target-info-api:

TargetInfo API
---------------

The :class:`TargetInfo` class is designed to provide an easy way of presenting
various pieces of information about the target device. An instance of this class
will be instantiated and populated automatically from the devlib
`target <http://devlib.readthedocs.io/en/latest/target.html>`_ created
during a WA run and serialized to a json file as part of the metadata exported
by WA at the end of a run.

The available attributes of the class are as follows:

- :confval:`target` - The name of the target that was created. E.g.
  AndroidTarget, LinuxTarget etc.
- :confval:`cpus` - A list of the unique cpu types that have been detected on
  the target. E.g. 'A53', 'A72' etc.
- :confval:`os` - The OS that the target was running.
- :confval:`os_version` - A dict that contains a mapping of OS version elements
  to their values. This mapping is OS-specific.
- :confval:`abi` - The ABI of the target device.
- :confval:`hostname` - The hostname of the the device the run was executed on.
- :confval:`is_rooted` - A boolean value specifying whether root was detected on
  the device.
- :confval:`kernel_version` - The version of the kernel on the target device.
  This returns a :class:`KernelVersion` instance that has separate version and
  release fields.
- :confval:`kernel_config` - A :class:`KernelConfig` instance that contains
  parsed kernel config from the target device. This may be ``None`` if the
  kernel config could not be extracted.
- :confval:`sched_features` - A list of the available tweaks to the scheduler,
  if available from the device.
- :confval:`hostid` - The unique identifier of the particular device the WA run
  was executed on.

---------------------

.. _run-info-api:

Run Info API
------------

The :class:`RunInfo` can be used to provide information about the run in
general. The available attributes of the class are as follows:


- :confval:`uuid` - A unique identifier for that particular run.
- :confval:`run_name` - The name of the run (if provided)
- :confval:`project` - The name of the project the run belongs to (if provided)
- :confval:`project_stage` - The project stage the run is associated with (if provided)
- :confval:`duration` - The length of time the run took to complete.
- :confval:`start_time` - The time the run was stared.
- :confval:`end_time` - The time at which the run finished.