From ed5e6f1876283d70f0de9193b035150100ce4d36 Mon Sep 17 00:00:00 2001 From: "mccasland, trevor (tm2086)" Date: Fri, 13 Jul 2018 16:34:18 -0500 Subject: [PATCH] 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 | 1 + doc/source/subunit2sql.rst | 92 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 93 insertions(+) create mode 100644 doc/source/subunit2sql.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index ecfed46c..b62c00e4 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -13,6 +13,7 @@ Contents: readme contributing + subunit2sql Indices and tables ================== diff --git a/doc/source/subunit2sql.rst b/doc/source/subunit2sql.rst new file mode 100644 index 00000000..a579c7bf --- /dev/null +++ b/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.