The buildbot.status.html.WebStatus status target runs a small
web server inside the buildmaster. You can point a browser at this web
server and retrieve information about every build the buildbot knows
about, as well as find out what the buildbot is currently working on.
The first page you will see is the “Welcome Page”, which contains links to all the other useful pages. This page is simply served from the public_html/index.html file in the buildmaster's base directory, where it is created by the buildbot create-master command along with the rest of the buildmaster.
One of the most complex resource provided by WebStatus is the
“Waterfall Display”, which shows a time-based chart of events. This
somewhat-busy display provides detailed information about all steps of all
recent builds, and provides hyperlinks to look at individual build logs and
source changes. By simply reloading this page on a regular basis, you will see
a complete description of everything the buildbot is currently working on.
A similar, but more developer-oriented display is the "Grid" display. This arranges builds by SourceStamp (horizontal axis) and builder (vertical axis), and can provide quick information as to which revisions are passing or failing on which builders.
There are also pages with more specialized information. For example, there is a page which shows the last 20 builds performed by the buildbot, one line each. Each line is a link to detailed information about that build. By adding query arguments to the URL used to reach this page, you can narrow the display to builds that involved certain branches, or which ran on certain Builders. These pages are described in great detail below.
When the buildmaster is created, a subdirectory named
public_html/ is created in its base directory. By default, WebStatus
will serve files from this directory: for example, when a user points
their browser at the buildbot's WebStatus URL, they will see
the contents of the public_html/index.html file. Likewise,
public_html/robots.txt, public_html/buildbot.css, and
public_html/favicon.ico are all useful things to have in there.
The first time a buildmaster is created, the public_html
directory is populated with some sample files, which you will probably
want to customize for your own project. These files are all static:
the buildbot does not modify them in any way as it serves them to HTTP
clients.
from buildbot.status.html import WebStatus
c['status'].append(WebStatus(8080))
Note that the initial robots.txt file has Disallow lines for all of the dynamically-generated buildbot pages, to discourage web spiders and search engines from consuming a lot of CPU time as they crawl through the entire history of your buildbot. If you are running the buildbot behind a reverse proxy, you'll probably need to put the robots.txt file somewhere else (at the top level of the parent web server), and replace the URL prefixes in it with more suitable values.
If you would like to use an alternative root directory, add the
public_html=.. option to the WebStatus creation:
c['status'].append(WebStatus(8080, public_html="/var/www/buildbot"))
In addition, if you are familiar with twisted.web Resource
Trees, you can write code to add additional pages at places inside
this web space. Just use webstatus.putChild to place these
resources.
The following section describes the special URLs and the status views they provide.