From 3927ee65356896a9fcb5c481e2e3b2a37478fc8f Mon Sep 17 00:00:00 2001
From: Sean Dague <sdague@linux.vnet.ibm.com>
Date: Tue, 18 Jun 2013 10:58:48 -0400
Subject: [PATCH] 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
---
 .../files/logs/help/tempest-overview.html     | 42 +++++++++++++++++++
 modules/openstack_project/manifests/static.pp | 10 +++++
 .../templates/logs.vhost.erb                  |  4 ++
 3 files changed, 56 insertions(+)
 create mode 100644 modules/openstack_project/files/logs/help/tempest-overview.html

diff --git a/modules/openstack_project/files/logs/help/tempest-overview.html b/modules/openstack_project/files/logs/help/tempest-overview.html
new file mode 100644
index 0000000000..c783be3120
--- /dev/null
+++ b/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>
diff --git a/modules/openstack_project/manifests/static.pp b/modules/openstack_project/manifests/static.pp
index 768394105e..2aeebd3e1f 100644
--- a/modules/openstack_project/manifests/static.pp
+++ b/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',
diff --git a/modules/openstack_project/templates/logs.vhost.erb b/modules/openstack_project/templates/logs.vhost.erb
index 4ee66e850f..53832ea4e0 100644
--- a/modules/openstack_project/templates/logs.vhost.erb
+++ b/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