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 where gatling-special.conf is placed in src/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)

    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

    Edit this page on GitHub

    ← Assertions
    Operations →