openstack/stackviz
Code Issues Proposed changes

Restructure Stackviz docs

Browse Source 
This patch changes the format of Stackviz docs so that all information
is stored in the appropriate doc/source/ directory rather than all
in README.rst. README.rst now just uses the RST include directive to
get its text from doc/source/readme.rst. Usage and installation are
now in their own RST files for increased modularity, and are included
in doc/source/readme.rst.

Additional developer documentation has also been created at
doc/source/man/ and includes more information on stackviz-export
as well as the AngularJS front-end.

Change-Id: I1d37194add998cf83a66d380ec7390e31184bdb3
This commit is contained in:
Austin Clark 2016-03-10 11:36:04 -07:00
parent 146fa55933
commit f3848085e1
10 changed files with 290 additions and 114 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
CONTRIBUTING.rst
View File

@ -1,17 +1 @@
If you would like to contribute to the development of OpenStack, you must
follow the steps in this page:
http://docs.openstack.org/infra/manual/developers.html
If you already have a good understanding of how the system works and your
OpenStack accounts are set up, you can skip to the development workflow
section of this documentation to learn how changes to OpenStack should be
submitted for review via the Gerrit tool:
http://docs.openstack.org/infra/manual/developers.html#development-workflow
Pull requests submitted through GitHub will be ignored.
Bugs should be filed on Launchpad, not GitHub:
https://bugs.launchpad.net/stackviz
.. include:: ./doc/source/contributing.rst

78
README.rst
View File

@ -1,77 +1 @@
========
StackViz
========
A visualization utility to help analyze the performance of DevStack setup and
Tempest executions.
Installation - Frontend
=======================
Installation of the frontend requires Node.js and Gulp. On Ubuntu::
sudo apt-get install nodejs npm nodejs-legacy
sudo npm install -g gulp
Then, install the Node modules by running, from the project directory::
npm install
Installation - Processing
=========================
The data processor is a small Python module located in the same source tree. To
install, run::
sudo pip install .
Usage - Development
===================
A development server can be run as follows::
gulp dev
This will open a web browser and reload code automatically as it changes on the
filesystem.
If you have subunit and dstat logs, you can create a config.json to display
your runs::
stackviz-export -f <path/to/subunit> --dstat <path/to/dstat> app/data/
During :code:`gulp dev`, files written to :code:`app/data/` will be
automatically synchronized with the browser. Note that these files will *not* be
copied to :code:`build/` during :code:`gulp prod`, but you can copy them
manually using :code:`gulp data`.
Usage - Production
==================
The production application can be build using::
gulp prod
The result will be written to :code:`./build` and should be appropriate for
distribution. Note that all files are not required:
- Directory structure (:code:`js/`, :code:`css/`, :code:`fonts/`,
:code:`images/`): required.
- Static resources (:code:`fonts/`, :code:`images/`): required.
- Core files (:code:`index.html`, :code:`js/main.js`, :code:`css/main.css`):
required unless gzipped versions are used.
- Gzipped versions of core files (:code:`*.gz`): not required, but preferred.
Use instead of plain core files to save on disk usage and bandwidth.
- Source maps (:code:`js/main.js.map`, :code:`js/main.js.map.gz`): only required
for debugging purposes.
Data should be written to :code:`build/data/` using :code:`stackviz-export` like
above. Note that the static production code generated above is portable, and can
be generated anywhere and copied to another host to be combined with exported
data.
Testing
=======
* Python tests: :code:`tox -epy27`
* JavaScript unit tests: :code:`gulp unit`
* JavaScript E2E tests: :code:`gulp e2e`
Roadmap and Planning
====================
- Planning: https://etherpad.openstack.org/p/stackviz
- Gate integration planning: https://etherpad.openstack.org/p/BKgWlKIjgQ
.. include:: ./doc/source/readme.rst

19
doc/source/contributing.rst
View File

@ -1,4 +1,19 @@
============
Contributing
============
.. include:: ../../CONTRIBUTING.rst
If you would like to contribute to the development of OpenStack, you must
follow the steps in this page:
http://docs.openstack.org/infra/manual/developers.html
If you already have a good understanding of how the system works and your
OpenStack accounts are set up, you can skip to the development workflow
section of this documentation to learn how changes to OpenStack should be
submitted for review via the Gerrit tool:
http://docs.openstack.org/infra/manual/developers.html#development-workflow
Pull requests submitted through GitHub will be ignored.
Bugs should be filed on Launchpad, not GitHub:
https://bugs.launchpad.net/stackviz

23
doc/source/index.rst
View File

@ -1,20 +1,28 @@
.. stackviz documentation master file, created by
sphinx-quickstart on Tue Jul 9 22:26:36 2013.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to stackviz's documentation!
Welcome to Stackviz's documentation!
========================================================
Contents:
Stackviz is a visualization utility to help analyze the performance of DevStack
setup and Tempest test runs. The following documentation details the procedures
for installing Stackviz on your local machine to view local runs, as well as
how to use Stackviz to view upstream runs. For more information on how
Stackviz runs, see the manual pages.
Local Stackviz:
---------------
.. toctree::
:maxdepth: 2
readme
installation
usage
contributing
Manual Pages:
-------------
.. toctree::
:maxdepth: 1
man/*
Indices and tables
==================
@ -22,4 +30,3 @@ Indices and tables
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

20
doc/source/installation.rst
View File

@ -1,12 +1,20 @@
============
Installation
============
At the command line::
Installation - Frontend
-----------------------
Installation of the frontend requires Node.js and Gulp. On Ubuntu::
$ pip install stackviz
sudo apt-get install nodejs npm nodejs-legacy
sudo npm install -g gulp
Or, if you have virtualenvwrapper installed::
Then, install the Node modules by running, from the project directory::
$ mkvirtualenv stackviz
$ pip install stackviz
npm install
Installation - Processing
-------------------------
The data processor is a small Python module located in the same source tree. To
install, run::
sudo pip install .

28
doc/source/man/index.rst Normal file
View File

@ -0,0 +1,28 @@
Welcome to Stackviz's Manuals!
========================================================
In this directory, you will find detailed documentation describing Stackviz
components and how they work together.
Stackviz is broken up into two distinct components: a Python processing module
(stackviz/stackviz) and an AngularJS front-end (stackviz/app). Stackviz also
uses Gulp to manage various tasks including building sites and running tests.
For information on each of these components, see their corresponding RST entry.
Below is a listing of each major subdirectory in Stackviz.
Directories:
------------
- :code:`./app/`: AngularJS front-end.
- :code:`./doc/`: Stackviz's documentation.
- :code:`./gulp/`: Gulp used for task management.
- :code:`./stackviz/`: Python processing module.
- :code:`./test/`: Unit and e2e tests.
Documentation for the Python processing module and AngularJS front-end:
.. toctree::
:maxdepth: 1
stackviz-export
stackviz-front

47
doc/source/man/stackviz-export.rst Normal file
View File

@ -0,0 +1,47 @@
===============================================
Python Data-Processing Module (stackviz-export)
===============================================
The main purpose of :code:`stackviz-export` is to parse subunit and dstat logs
in order to generate configuration files for the AngularJS front-end.
Installation
============
Once Stackviz has been cloned into a suitable directory, setting up the module
is as simple as::
sudo pip install .
Usage
=====
:code:`stackviz-export [options] <DEST>`
Where DEST is the output directory of the module. If DEST does not exist, a new
directory will be created. One of the following input options must be chosen:
**-f, --streamfile FILE**
Specifies a subunit stream file to be used with the exporter. This
argument can be used multiple times to specify additional subunit files.
**-i, --stdin**
Instructs stackviz-export to read a subunit stream from stdin.
**-r, --repository REPOSITORY**
Specifies a :code:`.testrepository` to read subunit streams from. This
argument can be used multiple times to specify additional repositories.
Stackviz also visualizes machine utilization statistics using dstat. To attach
a dstat.csv log to the subunit output, specify the following option:
**--dstat FILE**
Specifies a csv-formatted dstat log file that corresponds with the
provided subunit stream file.
Additional options:
**-h --help**
Print help message.
**-z --gzip**
Enables gzip compression for data files.

96
doc/source/man/stackviz-front.rst Normal file
View File

@ -0,0 +1,96 @@
===================
AngularJS Front-end
===================
The AngularJS front-end uses config files generated by :code:`stackviz-export`
to display a variety of information regarding test runs. This document breaks
down the various components of the Stackviz Angular app.
Pages
=====
----
Home
----
:Path: <host>/#/
:Directive: :code:`./app/views/home.html`
:Controller: :code:`./app/js/controllers/home.js`
The landing page for Stackviz consists of two elements. The first is a summary
panel that shows statistics for the run including runtime (MM:SS), total number
of tests run, number of failed tests, and number of skipped tests. The button
in the footer of this panel links to the timeline, where individual tests can
be browsed further. The second element is a panel showing all of the failures
for the current run, including the last few lines of their tracebacks. The test
divs here link to their corresponding Test Details page.
--------
Timeline
--------
:Path: <host>/#/<run>/timeline?test=<test>/
:Directive: :code:`./app/views/timeline.html`
:Controller: :code:`./app/js/controllers/timeline.js`
The Timeline provides an overview of all the tests that were executed as part
of a run. Each lane in the timeline corresponds to one worker thread on the
host machine. Each rectangle in the timeline represents one test. When a
rectangle is selected, the details panel below the timeline is populated with
information about the test. Each test rectangle is also color-coordinated:
green is passing, blue is skipped, and red is failed.
The details panel below the timeline shows information pertaining to the
current test (it is empty if no test is selected): test class, test module,
which worker executed it, the duration, and start & finish timestamps. The
footer contains a button that links to the test details page for the selected
test.
------------
Test Details
------------
:Path: <host>/#/<run>/test-details/<test>/
:Directive: :code:`./app/views/test-details.html`
:Controller: :code:`./app/js/controllers/home.js`
The test details page consists of one panel that displays various log info
from one test. The first tab contains summary information similar to the info
found on the test panel on the timeline. Additional tabs in this panel
are dependent upon the logs that the test kept. Each of these tabs provides
additional information to aid debugging. The most common tabs include:
**pythonlogging**
Contains logs for API calls that were used in the test. This
log is often quite large, as it contains full headers for every request
at INFO, DEBUG, WARNING, and ERROR levels. To make searching these logs
easier, the test details page has a built in filter for parsing by log
level. In the header of the test details page, the magnifying glass
can be clicked to only show pythonlogging lines that correspond to a
certain level of detail. To find errors in pythonlogging quickly, it is
advisable to only select the WARNING and ERROR levels for display.
**reason**
Only available for skipped tests. Lists the reason for skipping the test,
usually to avoid triggering an outstanding bug.
**traceback**
Only available for failed tests. Shows the full traceback of the test
runner's error output when the test failed. This is useful in quickly
isolating the cause of a failure. There can be multiple traceback logs
(e.g. traceback, traceback1) for one test.
When enough information has been gleaned from more detailed logs, the button
in the panel filter can be used to quickly navigate back to the timeline page.
Controllers
===========
Directives
==========
Filters
=======
Services
========
Util
====

31
doc/source/readme.rst
View File

@ -1 +1,30 @@
.. include:: ../../README.rst
========
StackViz
========
A visualization utility to help analyze the performance of DevStack setup and
Tempest executions. This repository can be cloned and built to use Stackviz
with local run data. Stackviz is currently in the process of being implemented
upstream (see Roadmap and Planning). To use Stackviz with upstream gate runs,
please see the server deployment project at:
https://github.com/timothyb89/stackviz-deployer
.. include:: ./installation.rst
.. include:: ./usage.rst
Testing
=======
* Python tests: :code:`tox -epy27`
* JavaScript unit tests: :code:`gulp unit`
* JavaScript E2E tests: :code:`gulp e2e`
Manuals & Developer Docs
========================
For more detailed information on how Stackviz works, please see the manuals
located at doc/source/man/
Roadmap and Planning
====================
- Planning: https://etherpad.openstack.org/p/stackviz
- Gate integration planning: https://etherpad.openstack.org/p/BKgWlKIjgQ

44
doc/source/usage.rst
View File

@ -1,7 +1,45 @@
========
Usage
========
To use stackviz in a project::
Usage - Development
-------------------
A development server can be run as follows::
import stackviz
gulp dev
This will open a web browser and reload code automatically as it changes on the
filesystem.
If you have subunit and dstat logs, you can create a config.json to display
your runs::
stackviz-export -f <path/to/subunit> --dstat <path/to/dstat> app/data/
During :code:`gulp dev`, files written to :code:`app/data/` will be
automatically synchronized with the browser. Note that these files will *not* be
copied to :code:`build/` during :code:`gulp prod`, but you can copy them
manually using :code:`gulp data`.
Usage - Production
------------------
The production application can be build using::
gulp prod
The result will be written to :code:`./build` and should be appropriate for
distribution. Note that all files are not required:
- Directory structure (:code:`js/`, :code:`css/`, :code:`fonts/`,
:code:`images/`): required.
- Static resources (:code:`fonts/`, :code:`images/`): required.
- Core files (:code:`index.html`, :code:`js/main.js`, :code:`css/main.css`):
required unless gzipped versions are used.
- Gzipped versions of core files (:code:`*.gz`): not required, but preferred.
Use instead of plain core files to save on disk usage and bandwidth.
- Source maps (:code:`js/main.js.map`, :code:`js/main.js.map.gz`): only required
for debugging purposes.
Data should be written to :code:`build/data/` using :code:`stackviz-export` like
above. Note that the static production code generated above is portable, and can
be generated anywhere and copied to another host to be combined with exported
data.