The Grinder 3 Properties File

The Grinder worker and agent processes are controlled by setting properties in the file.

All properties have default values. If you start The Grinder agent process without a file it will communicate with the console using default addresses, use one worker process, one thread, and make one run through the test script found in the file This is not much use, so read on...

Table of properties

This table lists the properties understood by The Grinder engine.

Property Description Default
grinder.processes The number of worker processes the agent should start. 1
grinder.threads The number of worker threads that each worker process spawns. 1
grinder.runs The number of runs of the test script each thread performs. 0 means "run forever", and should be used when you are using the console to control your test runs. 1
grinder.processIncrement If set, the agent will ramp up the number of worker processes, starting the number specified every grinder.processesIncrementInterval milliseconds. The upper limit is set by grinder.processes. Start all worker processes together.
grinder.processIncrementInterval Used in conjunction with grinder.processIncrement, this property sets the interval in milliseconds at which the agent starts new worker processes. 60000 ms
grinder.initialProcesses Used in conjunction with grinder.processIncrement, this property sets the initial number of worker processes to start. The value of grinder.processIncrement.
grinder.duration The maximum length of time in milliseconds that each worker process should run for. grinder.duration can be specified in conjunction with grinder.runs, in which case the worker processes will terminate if either the duration time or the number of runs is exceeded. Run forever.
grinder.script The file name of the Jython script to run.
grinder.jvm Use an alternate JVM for worker processes. Defaults to java so you do not need to specify this if your PATH is sensible. java
grinder.jvm.classpath Use to adjust the classpath used for the worker process JVMs. Anything specified here will be prepended to the classpath used to start the Grinder processes.

Relative paths are evaluated based on the worker process working directory. Scripts distributed using the console can refer to libraries in the distribution directory by using relative paths in this property.

grinder.jvm.arguments Additional arguments to worker process JVMs.
grinder.logDirectory Directory to write log files to. Created if it doesn't already exist. The local directory.
grinder.hostID Override the "host" string used in log filenames and logs. The host name.
grinder.consoleHost The IP address or host name that the agent and worker processes use to contact the console. All the network interfaces of the local machine.
grinder.consolePort The IP port that the agent and worker processes use to contact the console. 6372
grinder.useConsole Set to false to set the agent and worker processes not to use the console. true
grinder.reportToConsole.interval For advanced use only. The period at which each process sends updates to the console. 500 ms
grinder.initialSleepTime The maximum time in milliseconds that each thread waits before starting. Unlike the sleep times specified in scripts, this is varied according to a flat random distribution. The actual sleep time will be a random value between 0 and the specified value. Affected by grinder.sleepTimeFactor, but not grinder.sleepTimeVariation. 0 ms
grinder.sleepTimeFactor Apply a factor to all the sleep times you've specified, either through a property of in a script. Setting this to 0.1 would run the script ten times as fast. 1
grinder.sleepTimeVariation The Grinder varies the sleep times specified in scripts according to a Normal distribution. This property specifies a fractional range within which nearly all (99.75%) of the times will lie. E.g., if the sleep time is specified as 1000 and the sleepTimeVariation is set to 0.1, then 99.75% of the actual sleep times will be between 900 and 1100 milliseconds. 0.2
grinder.reportTimesToConsole Set to false to disable reporting of timing information to the console; other statistics are still reported. true
grinder.debug.singleprocess If set to true, the agent process spawns engines in threads rather than processes, using special class loaders to isolate the engines. This allows the engine to be easily run in a debugger. This is primarily a tool for debugging The Grinder engine, but it might also be useful to advanced users. GrinderStone uses this property to allow interactive debugging.

If you want instrumentation to work, you must specify -javaagent:path/grinder-dcr-agent-version.jar on the command line. Here, path is the full path to the agent jar file that can be found in the lib directory, and version depends on the version of The Grinder.

grinder.debug.singleprocess.sharedclasses For advanced use only. Specifies a comma separated list of names of classes that should be shared between the worker engines when grinder.debug.singleprocess is true. Class names can end with a * wildcard. See bug 134 for more details.

Specifying properties on the command line

You can also specify these properties as Java system properties in the agent command line. For example, on UNIX systems the following command line can be used to generate log directories based on the current date.

java -Dgrinder.logDirectory="log/$(date +%y%m%d)" net.grinder.Grinder

Property values set as Java system properties override values set in the file. Only properties with names that start "grinder." are considered.