docs: add info about subunit2SQL usage

This document summarizes the required subunit2SQL usage to produce
run metadata, and additional arguments this program uses in code to
display data on test results.

Change-Id: Ieb1b3bf4cc63ad73b210db0275fde284277900a4

doc/source/index.rst

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

doc/source/subunit2sql.rst

@@ -0,0 +1,92 @@
+=================
+subunit2SQL Usage
+=================
+openstack-health relies on `subunit2SQL`_ to process subunit streams and store
+the stream’s 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.