Add new information to zaqar-bench tutorial

New changes to zaqar-bench were introduced by
I0a7aaeaeac6da1b2c9f08fbfdddd467de5747a28 patch.

This patch adds the information about new '-api' option and about using
Keystone authentication to 'Running benchmark' tutorial.

Also this patch fixes the information about verbose mode, because now
verbose mode is the default in zaqar-bench. This change wasn't
introduced by any patch to zaqar-bench.

Change-Id: Ie07928a4625caf1d79b44e28b6b82296b224f2cc
Partial-Implements: blueprint contributor-docs-refactoring

doc/source/running_benchmark.rst

@@ -76,8 +76,8 @@ Usage
 
    You can override these defaults in the config file or on the command line
    using a variety of options. For example, the following command runs a
-   performance test for 30 seconds using 4 producer processes with 20
+   performance test for 30 seconds using 4 producer processes with 20 workers
-   workers each, plus 4 consumer processes with 20 workers each.
+   each, plus 4 consumer processes with 20 workers each.
 
    Note that the observer role is also disabled in this example by setting its
    number of workers to zero:
@@ -86,30 +86,99 @@ Usage
 
      $ zaqar-bench -pp 4 -pw 10 -cp 4 -cw 20 -ow 0 -t 30
 
-   By default, the results are in JSON.
+   By default, the results are in human-readable format. For JSON output add
-   For more human-readable output add the :option:`--verbose` flag.
+   the :option:`--noverbose` flag. The non-verbose output looks similar to the
-   Verbose output looks similar to the following:
+   following:
 
    .. code-block:: console
 
-     $ zaqar-bench --verbose
+     $ zaqar-bench --noverbose
+     Using 'envvars' credentials
+     Using 'keystone' authentication method
+     Benchmarking Zaqar API v2...
+     {"params": {"consumer": {"processes": 1, "workers": 0}, "observer": {"processes": 1, "workers": 5}, "producer": {"processes": 1, "workers": 10}}, "consumer": {"claim_total_requests": 0, "ms_per_claim": 0, "total_reqs": 0, "reqs_per_sec": 0, "successful_reqs": 0, "duration_sec": 0, "ms_per_delete": 0, "messages_processed": 0}, "producer": {"duration_sec": 8.569170951843262, "ms_per_req": 201.715140507139, "total_reqs": 29, "successful_reqs": 29, "reqs_per_sec": 3.384224700729303}, "observer": {"duration_sec": 8.481178045272827, "ms_per_req": 407.40778711107043, "total_reqs": 18, "successful_reqs": 18, "reqs_per_sec": 2.122346672115049}}
 
-     Starting producer (pp=1 , pw=10)...
+   By default, zaqar-bench is benchmarking Zaqar API version 2. To run
+   benchmark against other API versions use :option:`-api` parameter. For
+   example:
 
-     Starting observer (op=1 , ow=5)...
+   .. code-block:: console
 
-     Producer
+     $ zaqar-bench -api 1.1
-     ========
-     duration_sec: 5.1
-     ms_per_req: 2.9
-     reqs_per_sec: 344.5
-     successful_reqs: 1742.0
-     total_reqs: 1742.0
 
-     Observer
+Configuring zaqar-bench to use Keystone authentication
-     ========
+######################################################
-     duration_sec: 5.0
+
-     ms_per_req: 2.9
+It's possible to use zaqar-bench with Keystone authentication, if your Zaqar is
-     reqs_per_sec: 339.3
+configured to use Keystone authentication method and the Keystone service is
-     successful_reqs: 1706.0
+running. For example, this is always true when running DevStack_ with
-     total_reqs: 1706.0
+unmodified ``zaqar.conf``.
+
+Let's configure zaqar-bench too to use Keystone:
+
+#. Set zaqar-bench's authentication method to Keystone.
+
+   By default zaqar-bench is using ``noauth`` method. This can be changed by
+   setting the environment variable ``OS_AUTH_STRATEGY`` to ``keystone``.
+
+   To set this environment variable:
+
+   * temporarily, run:
+
+        .. code-block:: console
+
+           $ export OS_AUTH_STRATEGY=keystone
+
+   * permanently, add this line to your ``~/bashrc`` file:
+
+        .. code-block:: bash
+
+           export OS_AUTH_STRATEGY=keystone
+
+     Reboot your computer or just run in the terminal where you will start
+     zaqar-bench:
+
+        .. code-block:: console
+
+           $ source ~/.bashrc
+
+#. Set Keystone credentials for zaqar-bench.
+
+   * If you're running Zaqar under DevStack, **you can omit this step**,
+     because zaqar-bench will automatically get administrator or user
+     credentials from the one of the files created by DevStack: either from
+     ``/etc/openstack/clouds.yaml`` file or from
+     ``~/.config/openstack/clouds.yaml`` file, if it exists.
+
+   * If you're running manually configured Zaqar with manually configured
+     Keystone (not under DevStack):
+
+     Add these lines to your ``~/.bashrc`` file and specify the valid Keystone
+     credentials:
+
+        .. code-block:: bash
+
+           export OS_AUTH_URL=http://<your keystone endpoint>/v2.0
+           export OS_USERNAME=<keystone user name>
+           export OS_PASSWORD=<the user's password>
+           export OS_PROJECT_NAME=<keystone project name for the user>
+
+     Reboot your computer or just run in the terminal where you will start
+     zaqar-bench:
+
+        .. code-block:: console
+
+           $ source ~/.bashrc
+
+#. Run zaqar-bench as usual, for example:
+
+   .. code-block:: console
+
+     $ zaqar-bench
+
+   If everything is properly configured, zaqar-bench must show the line
+   ``Using 'keystone' authentication method`` and execute without
+   authentication errors.
+
+
+.. _DevStack: http://docs.openstack.org/developer/devstack/