opendev/subunit2sql
Code Issues Proposed changes
Tooling for converting subunit streams into a SQL DB
77 Commits 1 Branch 31 Tags 6.1 MiB
Python 99.4%
Shell 0.5%
Mako 0.1%
743db8ee56
Go to file
Matthew Treinish 743db8ee56 Add a contributing file 
This commit adds a contributing.rst file to outline how to contribute
to the project.

Change-Id: I1d3af6f9bfd2b6dad79415a113adce41fd5ea100
2014-12-15 23:19:05 -05:00
config-generator Add sample config files for commands 2014-10-06 20:29:49 +00:00
doc/source Add section on the basic data model 2014-11-20 03:42:48 +00:00
etc Add sample config files for commands 2014-10-06 20:29:49 +00:00
subunit2sql Merge "Add cli option to subunit2sql to specify run_id" 2014-12-04 18:54:21 +00:00
.gitignore Add sample config files for commands 2014-10-06 20:29:49 +00:00
.gitreview Add a .gitreview file 2014-07-12 12:48:23 -04:00
.testr.conf Add basic unit tests 2014-06-24 20:14:18 -04:00
CONTRIBUTING.rst Add a contributing file 2014-12-15 23:19:05 -05:00
LICENSE Initial commit 2014-06-12 23:59:00 -04:00
MANIFEST.in Add manifest file to include base alembic config 2014-09-30 14:44:46 -04:00
README.rst Fix misspelled words in docs and comments 2014-11-07 14:07:03 +01:00
requirements.txt Bump oslo.config version 2014-07-23 22:53:16 +00:00
setup.cfg Remove unneeded version string from setup.cfg 2014-12-04 23:40:55 -05:00
setup.py Initial commit 2014-06-12 23:59:00 -04:00
test-requirements.txt Add migration tests with data 2014-09-30 21:07:06 -04:00
TODO.rst Add migration tests with data 2014-09-30 21:07:06 -04:00
tox.ini Merge "Add migration to populate run_time where needed" 2014-10-07 21:27:38 +00:00

README.rst

subunit2SQL README

subunit2SQL like it's name implies is a tool used for converting subunit streams to data in a SQL database. The motivation is that for multiple distributed test runs that are generating subunit output it is useful to store the results in a unified repository. This is the motivation for the testrepository project which does a good job for centralizing the results from multiple test runs.

However, imagine something like the OpenStack CI system where the same basic test suite is normally run several hundreds of times a day. To provide useful introspection on the data from those runs and to build trends over time the test results need to be stored in a format that allows for easy querying. Using a SQL database makes a lot of sense for doing this.

subunit2SQL uses alembic migrations to setup a DB schema that can then be used by the subunit2sql binary to parse subunit streams and populate the DB. Additionally, it provides a DB API that can be used to query information from the results stored to build other tooling.

Usage

DB Setup

The usage of subunit2sql is split into 2 stages. First you need to prepare a database with the proper schema; subunit2sql-db-manage should be used to do this. The utility requires db connection info which can be specified on the command or with a config file. Obviously the sql connector type, user, password, address, and database name should be specific to your environment. subunit2sql-db-manage will use alembic to setup the db schema. You can run the db migrations with the command:

subunit2sql-db-manage --database-connection mysql://subunit:pass@127.0.0.1/subunit upgrade head

or with a config file:

subunit2sql-db-manage --config-file subunit2sql.conf upgrade head

This will bring the DB schema up to the latest version for subunit2sql. Also, it is worth noting that the schema migrations used in subunit2sql do not currently support sqlite. While it is possible to fix this, sqlite only supports a subset of the necessary sql calls used by the migration scripts. As such, maintaining support for sqlite will be a continual extra effort, so if support is added back in the future, it is no guarantee that it will remain. In addition, the performance of running, even in a testing capacity, subunit2sql with MySQL or Postgres make it worth the effort of setting up one of them to use subunit2sql.

Running subunit2sql

Once you have a database setup with the proper database schema you can then use the subunit2sql command to populate the database with data from your test runs. subunit2sql takes in a subunit v2 either through stdin or by passing it file paths as positional arguments to the script. If only a subunit v1 stream is available, it can be converted to a subunit v2 stream using the subunit-1to2 utility.

There are several options for running subunit2sql, they can be listed with:

subunit2sql --help

The only required options are the state_path and the database-connections. These options and the other can either be used on the CLI, or put in a config file. If a config file is used you need to specify the location on the CLI.

Most of the optional arguments deal with how subunit2sql interacts with the SQL DB. However, it is worth pointing out that the artifacts option and the run_meta option are used to pass additional metadata into the database for the run(s) being added. The artifacts option should be used to pass in a url or path that points to any logs or other external test artifacts related to the run being added. The run_meta option takes in a dictionary which will be added to the database as key value pairs associated with the run being added.

Creating a v2 Subunit Stream from the DB

The sql2subunit utility is used for taking a run_id and creating a subunit v2 stream from the data in the DB about that run. To create a new subunit stream run:

sql2subunit $RUN_ID

along with any options that you would normally use to either specify a config file or the DB connection info. Running this command will print to stdout the subunit v2 stream for the run specified by $RUN_ID, unless the --out_path argument is specified to write it to a file instead.