This page contains a lot of useful information about how to use Ginpex.

Using Ginpex

Running the Ginpex Controller: Creating an Experiment Script

To create an experiment script, launch the Ginpex controller.
In the launched eclipse instance, create a new project in which the files are to be stored.
To execute an experiment based on a manually defined experiment script, an experiment script and an experiment definition have to be created.
Create a new experiment definition model:
- Click on the icon "Create a new Ginpex Experiment Definition from scratch.".
- In the wizard, specify a location and file name, and click "Finish".
- The experiment definition model file is being created and can be edited with the EMF tree editor.
Create a new experiment script model:
- Click on the icon "Create a new Ginpex Experiment Script from scratch.".
- In the wizard, specify a location and file name, and click "Finish".
- The experiment script model file is being created and can be edited with the EMF tree editor.

Referencing Experiment Definition Elements from an Experiment Script

When creating an ExperimentScript model and an ExperimentDefinition model, you have to reference experiment definition elements from the experiment script. For example, the ExperimentScript's experimentDefinition element directly references the ExperimentDefinition model, and MachineMapping elements in the experiment script have to reference MachineReferences from the experiment definition.

To specify such references, the ExperimentScript has to know the ExperimentDefinition. To achieve this, right-click somewhere in the experiment script EMF tree editor and select "Load Resources..".
In the opening dialog, click "Browse File System..." or "Browse Workspace..." to open a file browse dialog.
In the browse dialog, browse to the experiment definition model file and select the file.
After closing the dialog, you can select experiment definition elements in the experiment script EMF tree editor.

Running the Ginpex Controller: Executing an Experiment Script

Prerequistes:
- An experiment script referencing an ExperimentDefinition model; All ExperimentDefinition MachineReferences have to be referenced from the ExperimentScript by MachineDescription/MachineMapping elements.
- A Load Driver is running on each machine that is specified in the MachineDescription elements of the experiment script.

Select menu "Window"->"Preferences" .
In the category "Ginpex", select the sub-category "System Adapter".
Specify an IP and a port for the SystemAdapter on the Controller machine.
- Specify an IP that is accessible for the Load Driver. You can click "Detect IP..." for automatically detecting the system's IP. This does not always work under Linux.
- Specify a free port.
Click "Apply" and close the Preferences page.

Select menu "Run"->"Run Configurations..." .
In the category "Ginpex", add a new launch configuration.
In the first tab, select "Provide Experiment Script" and specify the path to the experiment script in the text field.
If needed, specify locations of the SensorFramework results, the result CSV files and the generated code in the "Measurement Results Storage" tab.
In the "Ginpex Configuration Tab", you can specify additional Ginpex settings, such as calibration accuracy for generated load, or experiment completion notifications.
Save the launch configuration and launch it by clicking on "Run".
The measurement script is being executed now. Check the console output for details.

Experiment Definition How-To

Put load on a machine

To put load on a machine, different types of load tasks exist that have to be specified inside a MachineTaskSet . The MachineTaskSet references the machine on which the load is to be generated.

Issue CPU load

Create a CpuLoadTask

Specify the type of load (attribute demand: MandelbrotDemand, FibonacciDemand, CalculatePrimesDemand (CPU-bound); SortArrayDemand (memory-bound).
Specify the duration of the load in milliseconds (attribute duration). To generate load according to the specified duration, the Load Driver will perform a calibration, of no calibration has been performed before.
Add a sensor if needed (right-click on the task, then select a sensor under "Add/Remove Sensors...".

Issue Hard Disk load

Create a DiskReadTask or DiskWriteTask , depending on the kind of disk access needed.

Specify the filesize in bytes that is to be used for accessing the disk (attribute filesize). In case of a DiskReadTask, the file is initialized with random bytes prior to task execution. In case of a DiskWriteTask, random bytes are written to the file during task execution.
Specify the amount in bytes that is going to be transferred to/from disk during one task execution (attribute amount). The amount must not be larger than the specified file size. If the amount is smaller than the file size, a random position in the file is chosen as start position for transfer.
Add a sensor if needed (right-click on the task, then select a sensor under "Add/Remove Sensors...".

Issue Network load

Network load involves two Load Driver instances. Load is being transferred from one Load Driver instance to another over a network protocol (RMI or Sockets). Thus, two different MachineReferences have to be present in the ExperimentDefinition. Network load can be issued by specifying a NetworkLoadTask inside a MachineTaskSet. This is the MachineTaskSet of the MachineReference from which load will be generated.

Create a NetworkLoadTask

Specify the communication type (attribute communicationType, RMI or Sockets).
Specify the load in bytes that is going to be transferred during one task execution (attribute load).
Specify the MachineReference of the target machine (attribute targetMachine; must be different from the MachineReference that is used be the MachineTaskSet the NetworkLoadTask is nested in).
Add a sensor if needed (right-click on the task, then select a sensor under "Add/Remove Sensors...". Sensor measurements are taken on the MachineTaskSet's machine, not on the target machine.

Get status updates during long-running experiments

Sometimes, especially during long-running experiments, it can be useful to inform the user about the current status (or progress) of the experiment. For this, a StatusTask can be modeled at appropriate points in the control flow of the ExperimentDefinition. When the control flow of the experiment reaches the status task, a status update is being reported. The status update report depends on the specification of the StatusTask. For this, the StatusTask has an attribute statusReport which can be chosen from the StatusReport enumeration.

The following types of StatusReport are currently available:

NextTaskToExecute: Prints the next task that is to be executed, i.e. the task following the StatusTask in the ExperimentDefinition. Currently, the StatusTask has to reside in a SequenceTask.
ProgressPercentage: Prints the percentage of executed tasks (number of executed tasks compared to the total number of tasks). Currently, the StatusTask must not reside in a ForkTask.
AudioSignal: Issues an audio signal. This can for example be used as the very last task of an experiment to indicate experiment completion if the user does not want to monitor the console all the time.

By default, status reports are issued on the Controller machine. In certain cases, it might be necessary to issue the report on the load driver machine (in this case, the StatusTask must be nested inside a MachineTaskSet). This might be the case if

synchronous communication to the Load Drivers is specified (i.e. the Load Driver cannot call the Controller machine directly, but has to be polled), or
the console of the Load Driver should print the status reports instead of the Controller machine console.

To issue status reports on the Load Driver machine, set the reportStatusOnControllerMachine attribute of the StatusTask to false.

Communication between Controller and Load Driver

Using the Load Driver on a machine with restricted network access

Sometimes e.g. when using the Load Driver on a machine in a VPN network, there may be difficulties during the communication between the Controller machine and the Load Driver. Usually, the Load Driver cannot connect to the Controller machine's RMI server (however, the opposite direction is usually possible).

In this case, you can run experiments with synchronous communication i.e. the Load Driver does not actively call the Controller machine upon experiment completion, but the Controller machine polls the Load Driver. To enable synchronous communication, enable the checkbox "Use synchronous communication to Load Drivers" in the "Ginpex configuration tab" of a Ginpex run configuration. You can either poll the Load Driver manually (by clicking a button during the experiment run), or specify a time interval in which the Load Driver is polled automatically.

Additional features

Using experiment snapshots in long-running experiments

If long-running experiments fail or are aborted at some time, one does not want to repeat all experiment runs that have already been executed. For this, Ginpex is able to save snapshots between experiment runs of an experiment. If an experiment is restarted, a snapshot can be used to skip the experiment runs that have already been executed. Since an ExperimentScript is executed as one experiment run, snapshots only make sense when running predefined experiments, as multiple experiment runs are only possible in this scenario.

To use snapshots, activate the checkbox "Activate experiment snapshots" in the tab "Ginpex Configuration" in a Ginpex run configuration. In this tab, you also have to specify a folder where snapshot files are saved. Make sure to store experiment results in a persistent way (file instead of memory). This way, experiment results can be looked up in a later experiment when using snapshots. To store experiment results in a persistent way, use a File Datasource in the SensorFramework, or store the results in CSV files.

If you want to repeat an experiment using snapshots, a dialog appears that asks the user if the snapshot file should be used. If you expect such a dialog page, but no one appears, this can be due to one of the following reasons:

No snapshot file is available for the specified experiment, or the file is corrupt. Note that the snapshot has to match the experiment and the specified machines for the experiment.
The snapshot file is a available at a different location. Specify the corresponding location folder in the Ginpex run configuration.
The experiment has a different set of input parameter values as the experiment which has created a snapshot. Adapt the input parameters for the experiment.

Extending Ginpex

Ginpex is being developed with a strong focus on extension.

You can easily

add predefined experiments (requires writing some Java code)
add a new experiment domain that groups experiments (requires specifying an eclipse extension)
insert external library logic into experiment ExperimentDefinition execution (requires writing some Java code), using the ExecuteLibraryTask

By using established standards and framework, Ginpex even allows you to provide fundamental extensions such as

enhancing the experiment metamodel (requires adapting the EMF metamodel)
enhancing the experiment code generation (requires adapting the oAW XPand code generation templates)
- Ginpex currently uses code generation techniques to generate experiment Java code. By providing an appropriate transformation, you can use the experiment model instance to generate different language code for the experiments.

Adding a new experiment domain

An experiment domain groups experiments that belong to the same domain, i.e. experiment that aim at detecting properties of a certain part of the infrastructure.

An experiment domain is defined as an Eclipse extension to the experiment domain extension point.

Using external libraries for generating load

The ExecuteLibraryTask provides functionality to specify any logic in a JAR library that is executed in an ExperimentDefinition when the corresponding ExecuteLibraryTask is specified. This allows for executing task logic without extending the metamodel or code-generation templates.

The jar file has to provide a Java class that implements the ExternalJarTaskInterface. This interface is provided in the edu.kit.ipd.sdq.ginpex.loaddriver.api plugin available in the Ginpex SVN.

This class acts as a facade for library access. Any java logic can be executed from within a ExecuteLibraryTask, as long as it is available in one or multiple JAR files.

When specifying an external library task, the following attributes have to be specified: libraryPath: A set of full qualified system paths to the external library JAR files. The jars have to reside on the controller machine and are transferred to the corresponding Load Driver prior to experiment execution. className: The fully qualified class name (e.g. fully.qualified.packages.ClassName) of the class implementing the ExternalJarTaskInterface. The class has to reside in one of the specified JAR files.

Implementing the library

If you are not working with an Eclipse that has the Ginpex plugins installed, checkout the project edu.kit.ipd.sdq.ginpex.loaddriver.api from https://svnserver.informatik.kit.edu/i43/svn/code/Ginpex/trunk/edu.kit.ipd.sdq.ginpex.loaddriver.api

In this project, you find the interface ExternalJarTaskInterface.jar:

package edu.kit.ipd.sdq.ginpex.loaddriver.api;

public interface ExternalJarTaskInterface {
	
	/**
	 * Perform initial preparation logic.
	 * The prepare() method is called exactly once for each modeled instance of the task 
	 * prior to the execution phase of all tasks.
	 * If a task is being executed multiple times (for example, because it is nested
	 * in a LoopTask), the method is still called only once.
	 * 
	 * @return true if preparation succeeded.
	 */
	public boolean prepare();
	
	/**
	 * Perform the actual logic of the task.
	 */
	public void execute();
	
	/**
	 * Perform cleanup logic of the task.
	 * The cleanup() method is called exactly once for each modeled instance of the task.
	 * after all experiment tasks have been executed.
	 * If a task is being executed multiple times (for example, because it is nested
	 * in a LoopTask), the method is still called only once.
	 */
	public void cleanup();

}

If you have checked out the API project:
Create a new Java project and add a reference to the edu.kit.ipd.sdq.ginpex.loaddriver.api project.

If you are working with an Eclipse that has the Ginpex plugins installed:
Create a new plug-in project by using the "New Plzug-in Project wizard" (File->New->"Other..."->Plug-in Project). In the third wizard page, select the template "New Ginpex External Library Project Wizard".

In the new project, write a Java class that implements the ExternalJarTaskInterface (see method documentation above). This is the class that will be called by the Ginpex Load Driver, when it is specified in an ExecuteLibraryTask in the experiment definition.

Finally, create a JAR from this project. Put this JAR somewhere on your controller machine, as you want to specify the JAR location in your ExperimentDefinition.

Specifying the library call in an ExperimentDefinition

In the ExperimentDefinition, you can add an ExecuteLibraryTask at the places in the experiment where you want the library call to happen:

You can put the ExecuteLibraryTask in LoopTasks, add sensors to the task, etc. As the ExecuteLibraryTask is a MachineTask, it has to be nested inside a MachineTaskSet. Finally, set the ExecuteLibraryTask attributes libraryPath (the absolute path to the JAR file on the Controller Machine) and className (the fully qualified name of the class in the JAR file) as specified above.

If the implemented library needs to access additional JAR libraries, add the location of those libraries to the libraryPath attribute as well.

Troubleshooting

Ginpex run fails with "Failed to start RMI server, please make sure the java.rmi.server.codebase system property is set correctly"

For Ginpex communication with the Load Driver, Ginpex requires internet access to a common jar file that defines the RMI codebase. This file hosted is hosted at http://sdqweb.ipd.kit.edu/eclipse/ginpex/rmi.jar and accessed during a Ginpex run. If internet access during a Ginpex run is not available, you can provide the file to Ginpex by saving it on the local file system and adding ' -Djava.rmi.server.codebase=file:$path_to_rmi.jar_file ' in the eclipse.ini file.

Example (on a Windows machine):
-Djava.rmi.server.codebase=file:C:\ginpex\rmi.jar

Memory problems

Long-running experiments or experiment series may collect a large amount of measurement data. In such a case, the SensorFramework's Memory DataSource might not be the appropriate way to store measurement results, as it stores all results in main memory. Use a File DataSource instead, or save all results in CSV files only.