Overview¶

The below describes the required steps to get started with using Concertio Optimizer Runtime software.
While Optimizer Runtime can run under any modern Linux distribution, the directions below have been tested on recent Ubuntu CentOS releases.

Activating Your License¶

Prior to using Optimizer Runtime, you'll have to activate your license. In order to do so you'll need to use the optimizer-runtime-license tool:

$ optimizer-runtime-license

Concertio Optimizer Runtime License Handling Tool

Online documentation is available at https://www.concertio.com/docs/ 

Usage: optimizer-runtime-license ACTION [--verbose]

Supported ACTIONs:

  --help                           Display this help message
  --provider LICENSE PROVIDER      Choose the provider of your license key [cryptlex (default) | synopsys]
  --activate PRODUCT KEY           Online Activation of your installation using the product key [PRODUCT KEY]
  --deactivate                     Online Deactivation of your installation
  --activation-request PRODUCT KEY Generate an offline activation request file named <activation.req> using the product key [PRODUCT KEY]
  --activate-offline PATH          Offline activation using the activation response file [PATH]
  --deactivate-offline             Generate an offline deactivation request file <deactivation.req>
  --show                           Display license information

Optional:

  --verbose                        Detailed output.

If your system is connected to the internet you can use the online activation:

$ optimizer-runtime-license --activate XXXXXX-XXXXXX-XXXXXX-XXXXXX-XXXXXX-XXXXXX

(XXXXXX-XXXXXX-XXXXXX-XXXXXX-XXXXXX-XXXXXX is the license key you received when you purchased Optimizer Runtime or Studio).

Otherwise, if your system is offline the procedure is as follows:

First you'll need to generate a request file:

$ optimizer-runtime-license --activation-request XXXXXX-XXXXXX-XXXXXX-XXXXXX-XXXXXX-XXXXXX

This will generate a request file named activation.req, you should copy this file and send it as attachment by email to Synopsys ([email protected]).

Next, in a reply email you'll receive an activation file. You should copy the file to your system and execute the command:

$ optimizer-runtime-license --activate-offline FILE_PATH

(FILE_PATH is the file path of your activation file).

NOTE: you can use --provider cryptlex action, but cryptlex license provider set as a default, so it is not mandatory.

If you use Synopsys licensing you can activate the product in two ways:

Using online activation:

$ optimizer-runtime-license --provider synopsys --activate <PORT@SERVER>

(PORT number and SERVER ip is the license server location you received when you purchased Optimizer Runtime from Synopsys).

Using license file:

$ optimizer-runtime-license --provider synopsys --activate FILE_PATH

(FILE_PATH is the file path of the activation file).

The SCL data (<PORT>@<SERVER> or /path/to/file.lic) will be saved in ~/.concertio/credentials.yaml file.

Deactivation¶

In case you wish to deactivate your license (for example, if you wish to use your license on a different system), you should use the following command (if your system is online):

$ optimizer-runtime-license --deactivate

NOTE: For Synopsys licensing, this command will deactivate both types of licenses, online licenses and licenses that were activated by file.

Alternatively, if your system is offline, you should use:

$ optimizer-runtime-license deactivate-offline

This will generate a deactivation request file named deactivation.req. You should email this file to Concertio.

Usage¶

For a brief description of available command line switches, issue:

$ optimizer-runtime --help

Operating Modes¶

Optimizer Runtime has three main operating modes activated by --mode=MODE command line switch:

--mode=tune command line switch activates continuous study of the system. In this operating mode, Optimizer Runtime continuously studies the system and explores different knob settings. Optimizer Runtime gradually transitions from aggressive exploration of different knob settings to stable settings that are best for each workload class.
--mode=best command line switch dynamically applies the best settings available for each workload class. In this operating mode, Optimizer Runtime applies the best knob settings achieved throughout the continuous study mode, not attempting to further explore additional knob settings.
--mode=static-best command line switch statically applies the best settings calculated across multiple workload classes. This operating mode is invoked when continuous study and monitoring are not desired. In this operating mode, Optimizer Runtime calculates the best settings across the workloads encountered throughout the last 4 hours of the continuous study mode, and exits. In this mode Optimizer Runtime does not consume any CPU resources.

Running¶

Optimizer Runtime daemon is activated automatically upon installation, and each time upon OS boot.
Optimizer Runtime's default operating mode is continuous study.
Note, that the studied optimization data is saved in a file, and will be loaded back upon restart, so that a restart would not lead to optimization data loss.

Optimizer Runtime can be stopped and started manually by issuing one of the commands below respectively:

$ sudo systemctl stop optimizer-runtime
$ sudo systemctl start optimizer-runtime

Switching Operating Modes¶

The operating mode of Optimizer Runtime can be changed by issuing:

$ optimizer-runtime --mode=<new mode>

For instance, to switch to best settings mode, after the system has been studied, issue:

$ optimizer-runtime --mode=best

The operating mode is saved along with optimization data upon exit, so that when Optimizer Runtime restarts, it will run in the same mode as in the previous run. In case the optimization data file is not available, the continuous study mode (tune) will be set by default.

Static Tuning¶

It is possible to tune a server for a pre-defined set of representative applications, without continuously running Optimizer Runtime in the background.
This can be achieved as follows:

Run Optimizer Runtime in continuous study mode:

$ optimizer-runtime --mode=tune

Run the representative application in the background, for at least four hours.
Switch to static-best mode:

$ optimizer-runtime --mode=static-best

At this point Optimizer Runtime will apply the best settings for the workloads it had encountered in the past 4 hours. Optimizer Runtime will exit after applying these settings. These settings will be applied again after reboot or when the Optimizer Runtime daemon runs again.

Training for two or more representative applications is done in a similar way, except that all the representative applications need to run in the 4-hour time frame. Each application should run for the relative portion of time it is expected to run in the production environment.

Reset Optimization Data¶

Optimizer Runtime saves the optimization data learned throughout the continuous study phase in a file. In order to start from a clean database, reset gathered optimization data by stopping the Optimizer Runtime process and erasing the optimization database file, as follows

$ sudo systemctl stop optimizer-runtime
$ sudo rm -f /root/.concertio/opt.data
$ sudo systemctl start optimizer-runtime

Restoring default system settings¶

In case Optimizer Runtime has performed an emergency exit, such as been killed by an unhandled signal, or experienced a software bug, the system might be left in an unclean, non-optimal state. Assuming a valid optimization data file exists, the default system settings will be recovered upon restart of Optimizer Runtime. Alternatively, the default system settings can be recovered by:

$ sudo optimizer-runtime --apply-baseline

Optimizer Runtime stores optimization data acquired throughout continuous study phase in a file. As this process takes time, it makes sense to share the optimization data file among identical servers, in order to either speed up the deployment process, or to use it with Optimizer Runtime installations running in static-best operating mode.
In order to aid with the process of sharing optimization data file the optimizer-package-db script is provided within the Optimizer Runtime software package.

To display a brief help screen, issue

$ sudo optimizer-package-db --help

Usage: optimizer-package-db --collect --out=</out/path/optimization-db-package> [/src/path/opt-data-file]
       optimizer-package-db --install [/dest/path/opt-data-file]
       optimizer-package-db --help

Concertio Optimizer optimization data file manipulation tool.
Boosting server performance and energy efficiency.

Command line options:
--collect        create ready for distribution (self-extracting) optimization data package
  --out=PATH     path to opt. data package output file
  OPT-DATA-FILE  path to (optional) source opt. data file. When not provided, a fallback path is be used.
--install        install optimization data file
  OPT-DATA-FILE  path to (optional) destination opt. data file. When not provided, a fallback path is be used.
--help           display this screen and exit

Below is an example of sharing optimization data for running in static best operating mode.

Source server¶

Install Optimizer Runtime on a test server
Train Optimizer Runtime by running several benchmarks representing the expected characteristic workload. It is recommended, that different benchmarks are run in a round robin manner.
Switch Optimizer Runtime to the static best operating mode by issuing

bash $ sudo optimizer-runtime --mode=static-best

Collect optimization data file by issuing

$ sudo optimizer-package-db --collect --out=/path/to/custom-opt-data

The newly generated custom-opt-data file is a self-extracting archive, that should be transferred to the destination server.

Destination server¶

Copy custom-opt-data to the destination server.
As custom-opt-data is a self-extracting archive, make sure it has execution permissions.
It is recommended to save a copy of custom-opt-data file, as it might be required in the future for recovery purposes.
Install Optimizer Runtime on a destination server
Install custom-opt-data by issuing

$ /path/to/custom-opt-data --install

As the optimization data file contains the operating mode, Optimizer Runtime will operate in static best mode upon restart.

Replaying optimization samples¶

It is possible to replay an experiment according to CSV dump generated throughout the experiment.
In order to be able to do so, enable dumping the optimization data summary to CSV file:

global_settings:
  metrics_csv_filename: <metrics-file>.csv

In order to replay the experiment, invoke Optimizer Runtime in import mode:

$ optimizer-runtime --knobs=<knobs>.yaml --mode=import --http-port=8421 --reset

In a separate terminal, invoke the CSV replay tool (that accesses Optimizer Runtime over HTTP), then remotely switch Optimizer Runtime to tune mode in order to continue the optimization normally:

$ optimizer-runtime-replaycsv --send-stop <metrics-file>.csv
$ optimizer-runtime --forward --mode=tune