Configuration
Configure the logs with logback.xml, the configuration with gatling.conf, and the zip bundle command options
Gatling can be configured and optimized in three ways:
- with configuration files, located in
conf
directory - with command line options
- with the
$JAVA_OPTS
environment variable
Configuration files
logback.xml
This file allows you to configure the log level of Gatling. For further information, you should have a look at the Logback Documentation.
gatling.conf
Gatling configuration is based on the great Typesafe Config library.
Gatling configuration files, such as the default configuration file, use the HOCON format.
Gatling uses a fallback strategy, where:
System properties > gatling.conf
> gatling-defaults.conf
gatling-defaults.conf
is shipped in the gatling-core jar and must not be tampered.
gatling.conf
is the default name of the user defined file. It’s resolved from the ClassLoader, not the filesystem, meaning it must be placed in src/test/resources
for a Maven, Gradle, or sbt project.
This file name can be changed with a System property named gatling.conf.file
, eg -Dgatling.conf.file=gatling-special.conf
. Again, beware it’s loaded from the ClassLoader, not the filesystem, eg:
-Dgatling.conf.file=src/test/resource/gatling-special.conf
is incorrect-Dgatling.conf.file=gatling-special.conf
wheregatling-special.conf
is placed insrc/test/resource
is correct
The bundle distribution and the Maven, Gradle, and sbt plugin demo projects contain an easy-to-edit gatling.conf
file with all the available properties commented with the default values.
If you want to override default values, you have two possibilities:
- change the value in
gatling.conf
. - set a System property (the name of the property must match the HOCON Path)
gatling.conf
, don’t forget to remove the leading #
that comments the line, otherwise your change will be ineffective.Command Line Options
Each distribution of Gatling comes with a CLI which can be used to select run time options. Use the following commands to access the full list of available options:
Build tool | Plugin or Package manager | Wrapper (Windows) | Wrapper (MacOS/Linux) |
---|---|---|---|
Maven (including the standalone bundle) | mvn gatling:help |
mvnw.cmd gatling:help |
./mvnw gatling:help |
NPM | npx gatling --help |
– | – |
Gradle | gradle tasks |
gradlew.bat tasks |
./gradlew tasks |
sbt | sbt help Gatling |
– | – |
Manage configuration values
Some Gatling functionalities require environment variables or Java system properties. This guide provides instructions for how you can apply specific values to your project. This guide does not cover setting environment variables permanently. If you wish to do this, you need to consult the documentation for your chosen shell.
All of the following examples demonstrate the API token use case.
Export or set an environment variable
This procedure exports (MacOS and Linux) or sets (Windows), an environment variable for the duration of your session. Once you close or terminate the terminal session, you need to set the environment variable again.
Setting environment variables works for each of the Gatling programming language SDKs.
In a shell session (MacOS and Linux) or CMD session (Windows) use the following command to set an environment variable:
export GATLING_ENTERPRISE_API_TOKEN=<API-token-value>
set GATLING_ENTERPRISE_API_TOKEN=<API-token-value>
You can confirm the environment variable is properly set with the following command:
echo $GATLING_ENTERPRISE_API_TOKEN
echo %GATLING_ENTERPRISE_API_TOKEN%
Pass a Java system property
To pass a Java system property, use -Dprop=value
with any of the JVM build tools. The following example passes and API token and starts a simulation on Gatling Enterprise:
Maven
./mvnw -Dgatling.enterprise.apiToken=<API-token-value> gatling:enterpriseStart
mvnw.cmd -Dgatling.enterprise.apiToken=<API-token-value> gatling:enterpriseStart
Gradle
./gradlew -Dgatling.enterprise.apiToken=<API-token-value> gatling:enterpriseStart
gradle.bat -Dgatling.enterprise.apiToken=<API-token-value> gatling:enterpriseStart
sbt
sbt -Dgatling.enterprise.apiToken=<API-token-value> Gatling/enterpriseStart
Pass a JavaScript parameter
The JavaScript and Typescript SDK allows you to pass command line arguments to set parameters such as an API token. To pass a parameter, use the appropriate flag and value. The following example is for an API token with the enterprise-deploy
command:
npx gatling enterprise-deploy --api-token <API-token-value>
$JAVA_OPTS
Default command line options for JAVA are set in the launch scripts. You can use the JAVA_OPTS environment variable to override those defaults, eg:
JAVA_OPTS="myAdditionalOption" bin/gatling.sh