.. Benchmarking Suite
.. Copyright 2014-2017 Engineering Ingegneria Informatica S.p.A.

.. Licensed under the Apache License, Version 2.0 (the "License");
.. you may not use this file except in compliance with the License.
.. You may obtain a copy of the License at
.. http://www.apache.org/licenses/LICENSE-2.0

.. Unless required by applicable law or agreed to in writing, software
.. distributed under the License is distributed on an "AS IS" BASIS,
.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
.. See the License for the specific language governing permissions and
.. limitations under the License.

.. Developed in the ARTIST EU project (www.artist-project.eu), the
.. CloudPerfect EU project (https://cloudperfect.eu/) and EasyCloud,
.. an innovation activity supported by EIT Digital 
.. (https://www.eitdigital.eu)

#################
Command line tool
#################


Install
=======

The Benchmarking Suite Command line tool can be installed with:

.. code-block:: bash

    pip install benchsuite.cli

If the installation was successful, the ``benchsuite`` command should be in your path.


Configuration
=============

The Benchmarking Suite has a configuration folder where the providers, benchmarks and storage backends configuration files are located. If not explicitly set, the configuration folder is the located in the system default configuration folder (e.g. ``/home/<user>/.config`` in Linux). It can be customized setting the ``BENCHSUITE_CONFIG_FOLDER`` env variable.


The Benchmarking Suite stores the active benchmarking sessions data on the filesystem. By default it is located under the system default data folder (e.g. ``/Home/<user>/.local/share`` in Linux). It can be customized setting the ``BENCHSUITE_DATA_FOLDER`` env variable.

Usage and Examples
==================

Create a new session
~~~~~~~~~~~~~~~~~~~~

To create a new session, the Benchmarking Suite needs two information: the provider configuration and the service type. The command line tool offers multiple options to specify these parameters.

**Provider Configuration**

There are different alternatives:

1. specify a name with the ``--provider`` option (e.g. ``--provider myamazon``). In this case, a provider configuration file named ``<name>.conf`` will be searched in the configuration path;

2. specify a filename in the ``--provider`` option (e.g. ``--provider /path/myamazon.conf``). The configuration file specified will be used;

3. store the provider configuration in the ``BENCHSUITE_PROVIDER`` environment variable.

As example, the following invocations load the same provider configuration:

.. code-block:: bash

    $ benchsuite new-session --provider my-amazon.conf ...


.. code-block:: bash

    $ benchsuite new-session --provider $BENCHSUITE_CONFIG_FOLDER/providers/my-amazon.conf ...


.. code-block:: bash

    $ export BENCHSUITE_PROVIDER=```cat $BENCHSUITE_CONFIG_FOLDER/providers/my-amazon.conf```
    $ benchsuite new-session ...


**Service Type**

The service type can be specified using the ``--service-type`` option (e.g. ``--service-type ubuntu_micro``). The value of the service type must be one of the ones defined in the provider configuration. Alternatively the ``BENCHSUITE_SERVICE_TYPE` enviornment variable can be used.

If neither the ``--service-type`` option nor the ``BENCHSUITE_SERVICE_TYPE` enviornment variable are specified and the provider configuration defines only ONE service type, that one will be used, otherwise the invocation will fail.

.. _cli_documentation:

Command Line Tool Documentation
===============================

This is an autogenerated documentation from the Python ``argparse`` options.

.. argparse::
   :ref: benchsuite.cli.argument_parser.get_options_parser
   :prog: benchsuite