Installation - mgm-tp/perfload GitHub Wiki

The various perfLoad components need to be installed on the participating hosts. All components must be installed under a common directory on each host, which will subsequently be referred to as PERFLOAD_HOME. An environment variable with this name is, however, not necessary.

• Installing the components always involves unzipping a distribution. It is advisable to unzip the distributions directly on the target systems. This avoids file corruption during SCP transfer of unzipped distributions (e. g. *.dll and *.so file in perfMon) and creates execute permissions for shell scripts automatically.
• It is always safe to unzip a newer version over an existing installation. All files that require user changes have .default in their names and must be renamed upon installation. So you can always diff your adapted config files with the default ones after an update and make necessary adjustments, if need be.

• Requires Java 7
• Unzip the perfLoad Client distribution to PERFLOAD_HOME on all client hosts.
• Unzip the perfLoad Daemon distribution to PERFLOAD_HOME on all client hosts.
• JAVA_HOME must be set to a Java 7 (JDK or JRE). A setenv.cmd / setenv.sh may be added to the daemon directory in order to set JAVA_HOME. It will be picked up if present.

• Requires Java 6
• Unzip the perfMon distribution to PERFLOAD_HOME on all hosts where you wish to run perfMon during load tests.
• JAVA_HOME must be set to a Java 6 or higher (JDK or JRE). A setenv.cmd / setenv.sh may be added to the daemon directory in order to set JAVA_HOME. It will be picked up if present.

• Requires Java 7
• Unzip the perfLoad Console distribution to PERFLOAD_HOME on the controller host.
• JAVA_HOME must be set to a Java 7 (JDK or JRE). A setenv.cmd / setenv.sh may be added to the daemon directory in order to set JAVA_HOME. It will be picked up if present.
• Copy the driver jar and any additional dependencies to the folder test-lib.
• Copy testplan files to the folder testplans.
• Copy load profile events files to the folder testplans/loadprofiles.

• Requires Java 6
• Unzip the perfLoad Agent distribution to PERFLOAD_HOME on the application server hosts.
• Rename perfload-agent.default.json to perfload-agent.json and edit it as specified below.

For each method to be measured, add a JSON object to the file, the key being the fully classified class name of the class that contains methods to measure. Each class name JSON object must in turn contain any number of JSON objects for methods to measure, the keys being the method names and the values being lists of JSON arrays with method parameters. Specifying method parameters allows to distinguish between overloaded methods. If an empty list is specified, any, potentially overloaded, method with the name of the key is instrumented.

The agent can also instrument entry points of Web applications, i. e. servlets or filter. This enables the agent to match client requests and server-side measurings because perfLoad sends custom HTTP headers which the agent can extract. If your application has multiple entry points (e. g. multiple filters that are chained), only the first entry point relevant for a request should be instrumented. It is suggested the entry points be always configured.

Sample for an agent config file

	{
		'entryPoints': {
			'servlets': ['com.foo.web.FooServlet'],
			'filters': ['com.foo.web.FooFilter']
		},
		'instrumentations': {
			'com.foo.web.Foo': {
			'doSomething': [[], ['int'], ['long', 'long']],
			'doSomethingElse': []
		}
			'com.foo.web.Bar': {
				'doIt': [[java.lang.Integer]],
				'doItAgain': []
			}
		}
	}

In order to activate the agent in your application server, add the following VM-Parameter:

	-javaagent:/path/to/agent/perfload-agent.jar

• Requires Java 7
• Unzip the perfLoad Supervisor distribution to PERFLOAD_HOME on the controller host. Note, the Supervisor must be installed on the same host as the Console.
• JAVA_HOME must be set to a Java 7 (JDK or JRE). A setenv.cmd / setenv.sh may be added to the daemon directory in order to set JAVA_HOME. It will be picked up if present.
• Rename all files in directory conf matching the pattern *.default.* by removing ".default" from the file name.
• Edit the config files in the folder conf as described below.

Editing SupervisorConfig.groovy

The file SupervisorConfig.groovy contains settings for the Supervisor that are not specific to load tests. The file is in a format that can be read by Groovy's ConfigSlurper. The following table lists all properties for this file. Note that, unlike Java properties, the values are real types, not just strings.

Editing LoadTestConfig.groovy

The file LoadTestConfig.groovy contains configurations for all hosts participating in load tests. The file is in a format that can be read by Groovy's ConfigSlurper. The following table lists the properties for this file. Note that, unlike Java properties, the values are real types, not just strings. As the configuration is structured as nested maps, the table also shows parent-child relationships.

The following example should make this clearer:

Example for LoadTestConfig.groovy

	hostConfigs {
		myClientHost1 {
			user = 'myuser'
			password = 'mypass'
			perfLoadHome = '/home/myuser/perfload'
			osfamily = 'unix'
			daemonId = 1
			perfmon = true
		}
		myClientHost2 {
			user = 'myuser'
			password = 'mypass'
			perfLoadHome = '/home/myuser/perfload'
			osfamily = 'unix'
			daemonId = 2
			perfmon = true
		}
		myAppServerHost1 {
			user = 'myuser'
			password = 'mypass'
			perfLoadHome = '/home/myuser/perfload'
			osfamily = 'unix'
			perfmon = true
			startup = [[dir: '/dir/to/appserver/bin', executable: './myapp.sh'], args: ['start']]
			shutdown = [[dir: '/dir/to/appserver/bin', executable: './myapp.sh', args: ['shutdown']]
			archiving {
				appServerLogs {
					dir = '/dir/to/appserver/logs'
					files = '*.log'
					zipName = 'appserver-logs.zip'
					cleanup = true
				}
			}
		}
		myAppServerHost2 {
			user = 'myuser'
			password = 'mypass'
			perfLoadHome = '/home/myuser/perfload'
			osfamily = 'unix'
			perfmon = true
			startup = [[dir: '/dir/to/appserver/bin', executable: './startup.sh']]
			shutdown = [[dir: '/dir/to/appserver/bin', executable: './shutdown.sh']]
			archiving {
				appServerLogs {
					dir = '/dir/to/appserver/logs'
					files = '*.log'
					zipName = 'appserver-logs.zip'
					cleanup = true
				}
			}
		}
		myDbHost {
			user = 'myuser'
			password = 'mypass'
			perfLoadHome = '/home/myuser/perfload'
			osfamily = 'unix'
			perfmon = true
		}
	}

Adding project-specific targets

The Supervisor can execute project-specific tasks before and after a load test. The file ProjectTargets.gradle must be placed in the Supervisor's installation directory. It must contain the tasks before, after, and performSystemCheck. The latter one can be used to check the availability of the system, e. g. by calling a URL.

	// custom config object, if necessary
	// myProjectConfig = SupervisorUtils.loadConfig(tenant, 'ProjectTasksconfig.groovy')

	task before(description: 'Executes project-specific tasks before the load test') << {

	}

	task after(description: 'Executes project-specific tasks after the load test') << {

	}

	task performSystemCheck(description: 'Checks that everything is up and running') << {
		/*
		 * In order to fail this task, e. g. ant.fail() may be called
		 */
	}

Note: An upcoming version of the Supervisor will be able to distribute all components to the participating hosts so that everything can be configured in one central place and then be installed automatically.

• Requires Java 7
• Unzip the perfLoad Load Profile Editor distribution to PERFLOAD_HOME on the controller host.
• JAVA_HOME must be set to a Java 7 (JDK or JRE). A setenv.cmd / setenv.sh may be added to the daemon directory in order to set JAVA_HOME. It will be picked up if present.