add help infrastructure and initial stub to logs

in order to make it simpler for people to understand the results
of a devstack/tempest run, provide in line explanation for the
runs via an apache directive. This will let us sprinkle appropriate
help for different tests and directories on the log server.

DirectoryMatch fails to work with ReadmeName, but Directory with
creative globbing works (thanks to experiments by fungi).

Change-Id: I52e648dac6f13babd01ea245414ef54c243cdd36
Reviewed-on: https://review.openstack.org/33453
Reviewed-by: Jeremy Stanley <fungi@yuggoth.org>
Reviewed-by: Clark Boylan <clark.boylan@gmail.com>
Approved: Jeremy Stanley <fungi@yuggoth.org>
Tested-by: Jenkins

modules/openstack_project/files/logs/help/tempest-overview.html

@@ -0,0 +1,42 @@
+<h1>Guide to Tempest Results Runs<h1>
+<p>
+The directory here contains the full results of a devstack setup and
+tempest run for the OpenStack gate, as well as all the logs of all the
+relevant services that were running during that tempest test run. From
+them you should have enough information to debug.
+</p>
+<h2>File Overview</h2>
+<h3>console.html</h3>
+This file contains the stdout/stderr console of the devstack-gate
+job. The basic flow of the file goes as follows:
+<ul>
+  <li>Boot guest from base Linux image
+  <li>Use devstack to install all required packages (debs and pips)
+  <li>Use devstack to setup all the services from upstream master except
+    for the particular project being tested, which is pulled from
+    gerrit.
+  <li>Run devstack exercises (very basic sanity checking)
+  <li>Run tempest tests
+</ul>
+<p>
+  All the devstack setup is done under bash tracing, so
+  is <b>extremely</b> verbose. This is to ensure enough data is captured
+  so that you can debug failures in the gate with the information provided.
+</p>
+<p>
+  The tempest tests are the last 1% of the console.html. When looking
+  at failures it is typical best to start at the end of the file and
+  work backwards.
+</p>
+<h3>logs</h3>
+<p>
+  The <a href="logs">logs</a> directory contains all the screen logs
+  from all the services during the devstack-gate run.
+</p>
+
+<h2>About this Help</h2>
+<p>
+  This help file is part of the <a href="https://github.com/openstack-infra/config">openstack-infra/config</a> project, and
+  can be updated by pushing a review request to
+  <a href="https://github.com/openstack-infra/config/tree/master/modules/openstack_project/files/logs/help">https://github.com/openstack-infra/config/tree/master/modules/openstack_project/files/logs/help</a>
+</p>

modules/openstack_project/manifests/static.pp

@@ -97,6 +97,16 @@ class openstack_project::static (
     require => File['/srv/static/logs'],
   }
 
+  file { '/srv/static/logs/help':
+    ensure  => directory,
+    recurse => true,
+    owner   => 'root',
+    group   => 'root',
+    mode    => '0755',
+    source  => 'puppet:///modules/openstack_project/logs/help',
+    require => File['/srv/static/logs'],
+  }
+
   file { '/usr/local/sbin/log_archive_maintenance.sh':
     ensure => present,
     owner  => 'root',

modules/openstack_project/templates/logs.vhost.erb

@@ -27,6 +27,10 @@ NameVirtualHost <%= vhost_name %>:<%= port %>
     Order allow,deny
     allow from all
   </Directory>
+  <Directory <%= docroot %>/*/*/*/gate-tempest-devstack*/*>
+     ReadmeName /help/tempest-overview.html
+  </Directory>
+
   ErrorLog /var/log/apache2/<%= name %>_error.log
   LogLevel warn
   CustomLog /var/log/apache2/<%= name %>_access.log combined