Merge "docs: add info about subunit2SQL usage"

This commit is contained in:
Zuul 2018-08-01 22:56:46 +00:00 committed by Gerrit Code Review
commit 7c21193511
2 changed files with 93 additions and 0 deletions

View File

@ -13,6 +13,7 @@ Contents:
readme
contributing
subunit2sql
Indices and tables
==================

View File

@ -0,0 +1,92 @@
=================
subunit2SQL Usage
=================
openstack-health relies on `subunit2SQL`_ to process subunit streams and store
the streams test results in a remote repository. This document aims to outline
the desired usage of the program in order to use all of the features
openstack-health provides.
.. _subunit2SQL: https://github.com/openstack-infra/subunit2sql/blob/master/README.rst
For details on how to create a run with the ``run_meta`` argument and
additional arguments see `subunit2SQL's usage pattern`_
.. _subunit2SQL's usage pattern: https://docs.openstack.org/subunit2sql/latest/reference/api.html#parsing-subunit-stream-and-storing-it-in-a-db
Run Metadata
============
When creating runs with subunit2SQL and trying to display the test results with
openstack-health, there are a number of run metadata parameters that are
expected to be included with the runs via the ``run_meta`` argument. Each of
these parameters, along with the benefit provided, are explained below.
project
-------
``project`` is the default dropdown value for openstack-health. It's used
to describe what code is being tested. If you have a repository name, this
would be an ideal value. However, It's not necessary to provide this data to
enable any features, just know that a user will have to select a metadata item
from the ``Grouping`` dropdown on the home page to display results.
build_name
----------
``build_name`` will be used to represent the name of the job that was ran to
produce the subunit stream. This value will be used to aggregate your runs.
.. important:: This parameter is required for the openstack-health dashboard to
operate without errors.
build_uuid
----------
``build_uuid`` will be used to represent the uuid of the job that was ran to
produce the subunit stream.
.. important:: This parameter is required for the openstack-health dashboard to
operate without errors.
build_queue
-----------
``build_queue`` is used to determine what kind of queue was used to produce the
subunit stream. openstack-health only checks for the value of ``gate`` and
provides a fresh-check service as described below.
fresh-check
^^^^^^^^^^^
When you provide the ``build_queue`` key, the fresh-check service is enabled.
The latest run with the value of ``gate`` will be used to warn users that the
data collection may not be working correctly. This warning will be displayed if
the last run's ``run_at`` datetime was more than 24 hours ago.
node_provider
-------------
``node_provider`` is used to determine what host was used to produce the subunit
stream. The value of this key will be populated for you in the
``Recent Failures`` table in the tests view.
Additional Arguments
====================
This section is for arguments that are **NOT** ``run_meta`` parameters but are
included here because they are subunit2SQL arguments and provide additional
data about the run in openstack-health when used properly.
.. note:: Each of the following arguments must be set on the CLI or overridden
with the API like in `subunit2SQL's usage pattern`_.
artifacts
---------
``artifacts`` is used to provide a URL in order to show additional run details
to the user like run logs for example. This will be linked with runs in the
following tables:
* ``Failed Tests in Last 10 Failed Runs`` on the home page in the
``Artifacts`` column
* ``Recent Runs`` on the job, and grouping page in the ``Link`` column.
* ``Recent Failures`` on the test page in the ``Link`` column.
run_at
------
``run_at`` is used to provide the date and time the tests were executed.
.. note:: If no value is provided, the time the run was entered into the
database will be used.