From 123bdfbb16a00e8e3abea9d84c72cdbe580e5046 Mon Sep 17 00:00:00 2001
From: Matthew Treinish <mtreinish@kortar.org>
Date: Wed, 26 Apr 2017 17:38:29 -0400
Subject: [PATCH] Add subunit gearman worker mqtt info to firehose docs

This commit adds the schema info for the subunit gearman workers to the
firehose docs.

Change-Id: Id98b1f7e735cee8a9932776520884b19c25649a7
---
 doc/source/firehose.rst        | 20 +++++++++----------
 doc/source/firehose_schema.rst | 35 ++++++++++++++++++++++++++++++++++
 2 files changed, 45 insertions(+), 10 deletions(-)

diff --git a/doc/source/firehose.rst b/doc/source/firehose.rst
index a4cf91830b..4234c86db1 100644
--- a/doc/source/firehose.rst
+++ b/doc/source/firehose.rst
@@ -73,19 +73,19 @@ Services Publishing to firehose
 
 As of right now the following services publish messages to the firehose:
 
-+-----------+------------+-------------------------+
-| Service   | Base Topic | Source of Messages      |
-+===========+============+=========================+
-| gerrit    | gerrit     | `germqtt`_              |
-+-----------+------------+-------------------------+
-| launchpad | launchpad  | `lpmqtt`_               |
-+-----------+------------+-------------------------+
-+ logstash  | logstash   | `logstash-output-mqtt`_ |
-+-----------+------------+-------------------------+
++----------------+-----------------+---------------------------+
+| Service        | Base Topic      | Source of Messages        |
++================+=================+===========================+
+| gerrit         | gerrit          | `germqtt`_                |
++----------------+-----------------+---------------------------+
+| launchpad      | launchpad       | `lpmqtt`_                 |
++----------------+-----------------+---------------------------+
+| subunit worker | gearman-subunit | `subunit-gearman-worker`_ |
++----------------+-----------------+---------------------------+
 
 .. _germqtt: http://git.openstack.org/cgit/openstack-infra/germqtt/
 .. _lpmqtt: http://git.openstack.org/cgit/openstack-infra/lpmqtt/
-.. _logstash-output-mqtt: https://github.com/kompa3/logstash-output-mqtt
+.. _subunit-gearman-worker: http://git.openstack.org/cgit/openstack-infra/puppet-subunit2sql/tree/files/subunit-gearman-worker.py
 
 For a full schema description see :ref:`firehose_schema`
 
diff --git a/doc/source/firehose_schema.rst b/doc/source/firehose_schema.rst
index 00425618fe..9f64da77a5 100644
--- a/doc/source/firehose_schema.rst
+++ b/doc/source/firehose_schema.rst
@@ -114,3 +114,38 @@ payload (with the body trimmed) for a bug is::
     "bug-modifier": "Full Name (username)",
     "body": "notification body, often is just bug comment or summary",
   }
+
+Subunit Workers
+===============
+
+The messages for the subunit workers are generated directly in the
+`subunit gearman worker scripts`_.
+
+.. _subunit gearman worker scripts: http://git.openstack.org/cgit/openstack-infra/puppet-subunit2sql/tree/files/subunit-gearman-worker.py
+
+Topics
+------
+
+The topics for the subunit workers follow a simple pattern::
+
+    gearman-subunit/<worker hostname>/<git namespace/<repo name>/<change number>
+
+Where  ``worker hostname`` is the host which processed the subunit file, as
+of right now there are 2, subunit-worker01 and subunit-worker02, but there may
+be more (or fewer) in the future. The ``git namespace`` and ``repo name`` are
+pretty self explanatory, and are just for the git repo under test that the
+subunit was emitted from. ``change number`` is the gerrit change number for the
+job that launched the tests the subunit is for.
+
+Payload
+-------
+The payload for the messages from the subunit workers is pretty straightforward
+json that contains 3 fields: ``status``, ``build_uuid``, and ``source_url``.
+
+An example is::
+
+    {
+        'status': 'success',
+        'build_uuid': '45f7c1ddbfd74c6aba94662623bd61b8'
+        'source_url': 'A url',
+    }