FrontLine User Guide

Gatling Corp

Version 1.8.2, 2019-09-11

Table of Contents
1. Developer Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1  

1.1. FrontLine Gatling Versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1  

1.2. Document Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1  

1.3. Configuring Gatling Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1  

1.3.1. Maven . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1  

1.3.2. SBT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2  

1.3.3. Gradle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4  

1.3.4. Multi-Module Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5  

1.4. Note on Feeders. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5  

1.5. Specific Gatling Features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5  

1.5.1. Load Sharding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5  

1.6. Resolving Injector Location in Simulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6  

1.7. Publishing Fatjars into Binary Repositories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6  

1.7.1. Maven . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6  

1.7.2. Gradle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7  

1.7.3. Sbt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
 

2. Dashboard User Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9  

2.1. Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9  

2.2. Login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9  

2.3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10  

2.4. Admin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 

2.4.1. Managing Teams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11  

2.4.2. Managing Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11  

2.4.3. Managing API Tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13  

2.4.4. Managing Private Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14  

2.4.5. Managing Repositories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15  

2.5. Accessing your profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17  

2.6. Pools. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
 

2.6.1. Warning about Private Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19  

2.6.2. On-premises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19  

2.6.3. AWS Pool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21  

2.6.4. GCE Pool (On-premises license only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23  

2.6.5. OpenStack Pool (On-premises license only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24  

2.6.6. Digital Ocean Pool (On-premises license only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26  

2.6.7. Microsoft Azure Pool (On-premises license only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27  

2.6.8. Kubernetes/OpenShift Pool. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29  

2.7. Simulations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31  

2.7.1. Global Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32  

 2.7.2. Creating a simulation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34  

2.7.3. Simulation table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42  

2.7.4. Useful tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

 

2.7.5. Run / Trends . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44  

2.7.6. Reports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
 

2.8. Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55  

2.9. About . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
 

3. Public APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
 
Chapter 1. Developer Guide
1.1. FrontLine Gatling Versions
FrontLine actually uses custom versions of the Gatling components. Those binaries are not open
sources and their usage is restricted to FrontLine. When you’ll be deploying tests with FrontLine, it
will replace your Gatling OSS dependencies with their custom counterparts.

1.2. Document Conventions

In this document, you’ll find several mentions to some placeholders in capital letters.

• REPLACE_WITH_YOUR_REPOSITORY_URL: the URL of the private repository that you were

given alongside with your license key

This placeholder only makes sense for on premise customers. AWS Marketplace
 customers spawn a pre-installed AMI and already have all the dependencies they
need.

• REPLACE_WITH_LATEST_GATLING_VERSION: compatible Gatling version, 3.2.1 at the time this

document was edited

1.3. Configuring Gatling Projects

1.3.1. Maven

In your pom.xml, you have to add in:

• pull Gatling dependencies

• add the maven plugin for Scala, so your code gets compiled

• add the maven plugin for FrontLine, so it can package your code into a deployable artifact

pom.xml:

<dependencies>
  <dependency>
  <groupId>io.gatling.highcharts</groupId>
  <artifactId>gatling-charts-highcharts</artifactId>
  <version>REPLACE_WITH_LATEST_GATLING_VERSION</version>
  <scope>test</scope>
  </dependency>
</dependencies>

<build>
  <plugins>
  <!-- so maven can compile your scala code -->
  <plugin>

1
   <groupId>net.alchim31.maven</groupId>
  <artifactId>scala-maven-plugin</artifactId>
  <version>4.2.0</version>
  <executions>
  <execution>
  <goals>
  <goal>testCompile</goal>
  </goals>
  <configuration>
  <recompileMode>all</recompileMode>
  <jvmArgs>
  <jvmArg>-Xss100M</jvmArg>
  </jvmArgs>
  <args>
  <arg>-target:jvm-1.8</arg>
  <arg>-deprecation</arg>
  <arg>-feature</arg>
  <arg>-unchecked</arg>
  <arg>-language:implicitConversions</arg>
  <arg>-language:postfixOps</arg>
  </args>
  </configuration>
  </execution>
  </executions>
  </plugin>

  <!-- so maven can build a package for FrontLine -->

  <plugin>
  <groupId>io.gatling.frontline</groupId>
  <artifactId>frontline-maven-plugin</artifactId>
  <version>1.0.3</version>
  <executions>
  <execution>
  <goals>
  <goal>package</goal>
  </goals>
  </execution>
  </executions>
  </plugin>
  </plugins>
</build>

You can run mvn package in your terminal and check you get a jar containing all the dependencies of
the simulation.

1.3.2. SBT

In a sbt project, you have to:

• pull Gatling dependencies

2
 • add the sbt plugin for FrontLine, so it can package your code into a deployable artifact

A build.sbt file should look like this:

build.sbt:

enablePlugins(GatlingPlugin, FrontLinePlugin)

scalaVersion := "2.12.9"
scalacOptions := Seq(
  "-encoding", "UTF-8", "-target:jvm-1.8", "-deprecation",
  "-feature", "-unchecked", "-language:implicitConversions", "-language:postfixOps")

val gatlingVersion = "REPLACE_WITH_LATEST_GATLING_VERSION"

libraryDependencies += "io.gatling.highcharts" % "gatling-charts-highcharts" %

gatlingVersion % "test"
// only required if you intend to use the gatling-sbt plugin
libraryDependencies += "io.gatling" % "gatling-test-framework" %
gatlingVersion % "test"

 Don’t forget to replace the UUID with the one you were given.

 We only support sbt 1+, not sbt 0.13.

INFO: The `gatling-test-framework`dependencies is only needed if you intend to run locally and
use the gatling-sbt plugin.

INFO: If you use very long method calls chains in your Gatling code, you might have to increase
sbt’s thread stack size:

$ export SBT_OPTS="-Xss100M"

You will also need the following lines in the project/plugins.sbt file:

project/plugins.sbt

// only if you intend to use the gatling-sbt plugin for running Gatling locally
addSbtPlugin("io.gatling" % "gatling-sbt" % "3.0.0")
// so sbt can build a package for FrontLine
addSbtPlugin("io.gatling.frontline" % "sbt-frontline" % "1.0.1")

You can run sbt test:assembly in your terminal and check you get a jar containing all the
dependencies of the simulation.

INFO: The gatling-sbt is optional.

3
1.3.3. Gradle

In a Gradle project, you have to:

• pull Gatling dependencies

• add the gradle plugin for FrontLine, so it can package your code into a deployable artifact

A build.gradle file should look like this:

build.gradle:

buildscript {
  repositories {
  mavenLocal()
  jcenter()
  }
  dependencies {
  classpath "io.gatling.frontline:frontline-gradle-plugin:1.0.0"
  }
}

repositories {
  mavenLocal()
  jcenter()
}

apply plugin: "java"

apply plugin: "scala"
// so gradle can build a package for FrontLine
apply plugin: "io.gatling.frontline.gradle"

sourceCompatibility = 1.8
targetCompatibility = 1.8

dependencies {
  testCompile "io.gatling.highcharts:gatling-charts-
highcharts:REPLACE_WITH_LATEST_GATLING_VERSION"
}

tasks.withType(ScalaCompile) {
  scalaCompileOptions.forkOptions.with {
  jvmArgs = ['-Xss100M']
  }
}

 Don’t forget to replace the UUID with the one you were given.

You can run gradle testJar in your terminal and check you get a jar containing all the
dependencies of the simulation.

4
1.3.4. Multi-Module Support

If your project is a multi-module one, make sure that only the one containing the Gatling
Simulations gets configured with the Gatling related plugins describes above. FrontLine will take
care of deploying all available jars so you can have Gatling module depend on the other ones.

1.4. Note on Feeders

A typically mistake with Gatling and FrontLine is to rely on having an exploded maven/gradle/sbt
project structure and try loading files from the project filesystem.

This filesystem structure will be gone once FrontLine will have compiled your project and uploaded
your binaries on the injectors.

If your feeder files are packaged with your test sources, you must resolve them from the classpath.
This way will always work, both locally and with FrontLine.

// incorrect
val feeder = csv("src/test/resources/foo.csv")

// correct
val feeder = csv("foo.csv")

1.5. Specific Gatling Features

1.5.1. Load Sharding

Injection rates and throttling rates are automatically distributed amongst nodes.

However, Feeders data is not automatically sharded, as it might not be the desired behavior.

If you want data to be unique cluster-wide, you have to explicitly tell Gatling to shard the data, e.g.:

val feeder = csv("foo.csv").shard

Assuming a CSV file contains 1000 entries, and 3 Gatling nodes, the entries will be distributed the
following way:

• First node will access the first 333 entries

• Second node will access the next 333 entries

• Third node will access the last 334 entries

shard is available in Gatling OSS DSL but is a noop there. It’s only effective when
 running tests with FrontLine.

5
1.6. Resolving Injector Location in Simulation
When running a distributed tests from multiple locations, you could be interested in knowing
where a given injector is deployed in order to trigger specific behaviors depending on location.

For example, you might want to hit https://mydomain.co.uk baseUrl if injector is deployed on AWS
London, and https://mydomain.com otherwise.

You can resolve in your simulation code the name of the pool a given injector is deployed on:

val poolName = System.getProperty("gatling.frontline.poolName")

val baseUrl = if (poolName == "London") "https://domain.co.uk" else
"https://domain.com"

This System property is only defined when deploying with FrontLine. It’s not
 defined when running locally with any Gatling OSS launcher.

1.7. Publishing Fatjars into Binary Repositories

Instead of building tests from sources, you have the option of building binaries upstream and
publishing them into a binary repository (Artifactory or Nexus) so FrontLine just has to download
them.

Please check your build tool documentation and the standards in your
 organization about the way to set credentials.

1.7.1. Maven

You’ll have to configure either repository or snapshotRepository block whether you want to deploy
releases or snapshots.

<distributionManagement>
  <repository>
  <id>your.releases.repository.id</id>
  <url>REPLACE_WITH_YOUR_RELEASES_REPOSITORY_URL</url>
  </repository>
  <snapshotRepository>
  <id>your.snapshots.repository.id</id>
  <url>REPLACE_WITH_YOUR_SNAPSHOTS_REPOSITORY_URL</url>
  </snapshotRepository>
</distributionManagement>

You’ll need frontline-maven-plugin version 1.0.3 at least. Fatjar artifact will be automatically
attached to your project and deployed with the shaded classifier.

6
 mvn deploy

1.7.2. Gradle

The main idea is to use the official maven publish plugin and ask it to use the task named testJar,
then define a repository:

apply plugin: "maven-publish"

publishing {
  publications {
  mavenJava(MavenPublication) {
  artifact testJar
  }
  }
  repositories {
  maven {
  if (project.version.endsWith("-SNAPSHOT")) {
  url "REPLACE_WITH_YOUR_SNAPSHOTS_REPOSITORY_URL"
  } else {
  url "REPLACE_WITH_YOUR_RELEASES_REPOSITORY_URL"
  }
  }
  }
}

You can deploy the test jar with the following command:

gradle publish

An artifact will be published will the tests classifier.

1.7.3. Sbt

packageBin in Test := (assembly in Test).value

publishArtifact in Test := true
publishTo :=
  (if (isSnapshot.value)
  Some("private repo" at "REPLACE_WITH_YOUR_SNAPSHOTS_REPOSITORY_URL")
  else
  Some("private repo" at "REPLACE_WITH_YOUR_RELEASES_REPOSITORY_URL")
)

sbt test:publish

7
An artifact will be published will the tests classifier.

8
Chapter 2. Dashboard User Guide
2.1. Configuration
The first step before using FrontLine is to configure your license key.

Once you’ve filled your license and clicked on the "Next" button you will get the credentials to
connect to the superAdmin account. You can change this password in the frontline.conf file.

Click on the "Next" button to finish the configuration step and restart FrontLine.

2.2. Login
Logging in is necessary to use FrontLine. FrontLine is accessible by default on port 10542.

If it is the first time you use FrontLine, you can use the super admin account with the following
credentials:

9
 • Login: superAdmin

• Password: generated by the configuration step or in the frontline.conf file. You can change it in
the frontline.conf file.

2.3. Overview
Once you are logged in, you are now able to navigate using the frontline navigation bar on the left
side.

FrontLine is composed of:

• The Profile section, letting a user manage his account settings (not accessible the the
superAdmin)

• The Admin section, letting administrators manage teams, users, API tokens, private keys and
binary repositories

• The Simulations section, where runs, trends and simulations can be seen and managed

• The Pools section, where you can configure your cloud and on-premises instances

• The Documentation section, displaying all documentation guides, the link to the Swagger for our
public API, and samples for your FrontLine tests

10
 • The About section, letting you know the current version of FrontLine and the expiration date of
your license key

We are now going to describe in depth each one of these sections.

2.4. Admin
2.4.1. Managing Teams

To access the Teams administration, click on Admin in the navigation bar, and choose Teams.

In the teams table, you can visualize the team name, and the number of associated users, pools and
simulations. You can also copy the team id by clicking on the  icon.

To create a team, click on the Create button.

You can edit the team by clicking on the  icon and delete them using the checkboxes on the table’s
right part.

2.4.2. Managing Users

To access the Users administration, click on Admin in the navigation bar, and choose Users.

Permissions

There are 3 different user roles in FrontLine:

• Administrator

• Team Manager

• Team Member

11
 Team Member Team Manager Administrator

 Access own profile 1   

 Access Reports Own team Own team 

and Trends

 Start Simulation Own team 

 Generate Public Links Own team 

 Create Simulation Own team 

 Access Pools Own team 

 Create and Edit Pools 

 Administrate Users, 
Teams, API Tokens,
Private Keys and
Binary Repositories

Administrator is a global role, whereas Team Manager and Member can be global or team-specific.

User administration

If you switch between FrontLine embedded user management system and LDAP
mode, or that there is a problem fetching your user data in LDAP, some users may
 be flagged invalid. For example, if a user created in FrontLine doesn’t exist in your
LDAP server, you won’t be able to connect with this user anymore.

To create a user, click on the Create button. Once the user is created, copy his password, as you
won’t be able to retrieve it again.

12
If you are using FrontLine with LDAP, you will only have to fill the username and permissions to
create a user, the other pieces of information come directly from the LDAP.

You can edit the user by clicking on the  icon and delete them using the checkboxes on the table’s
right part. To reset a user password, click on the  icon (only available in non-LDAP mode).

It should be noted that the superAdmin account can’t be deleted or even modified here.

2.4.3. Managing API Tokens

To access the API Tokens administration, click on Admin in the navigation bar, and choose API
token.

To create an API token, click on the Create button. Once the API token is created, copy the token, as
you won’t be able to retrieve it again.

13
There are three permissions available for an API Token:

• The Start permission, allowing to start simulations (typically useful in a CI like Jenkins)

• The Read permission, allowing to read all the data from runs (typically useful in Grafana)

• The All permission, combining both of the previous permissions

You can edit the API Token permissions by clicking on the  icon on the right part of the table. A
permission can be set globally or to a specific team. To regenerate a token, click on the  icon.

2.4.4. Managing Private Keys

To access the Private Keys administration, click on Admin in the navigation bar, and choose
Private Keys. A private key corresponds to the ssh key used to connect to your Git repository or
pool instances.

To create a Private Key, click on the Create button.

14
You have two possibilities to reference private keys:

• Upload them directly by drag-and-drop or click on the input to choose the file on your filesystem

• Locate a private key existing on FrontLine’s host. The private key permissions should be 600 or
400, and its owner should be the FrontLine process user

If you are using the AWS marketplace offer and wish to reference an existing
 private key, you must connect with the ec2-user user and then sudo to the frontline
user which is the one running the FrontLine process.

You can edit the private key by clicking on the  icon and delete them using the checkboxes on the
table’s right part.

2.4.5. Managing Repositories

To access the repositories administration, click on Admin in the navigation bar, and choose Binary
Repositories

To create a repository, click on the Create button.

15
 • Repository URL: the URL of the targeted repository

• Authentication settings: the key for the jar you want to download

◦ Username: the username of the user with sufficents permissions

◦ API Key: API key for the current user

 make sure to follow the Repository URL pattern as follow

• JFrog Artifactory : http[s]://<host>/<repository>

• Sonatype Nexus 2 : http[s]://<host>/nexus/content/repositories/<repository>

• Sonatype Nexus 3 : http[s]://<host>/repository/<repository>

How to find the repository URL?

• Artifactory :

16
 • Nexus :

Before saving, we advice to check the connection to the repository by clicking on the Check
Connection button.

You can edit the repository by clicking on the  icon and delete them using the checkboxes on the
table’s right part.

2.5. Accessing your profile

You can view your profile at any time by clicking on the My Profile button in the navigation bar.

17
The informations displayed are the following:

• Username

• First and Last name

• Mail address

• Different roles

To update your profile, modify the fields you want to change, then click on the button Update your
informations.

You can’t update your username, and your roles need to be updated by an admin on the Users
Admin page.

It should be noted that the superAdmin account doesn’t have a profile.

If you are using FrontLine with LDAP, profiles will be read-only since users information are
retrieved from the LDAP and not managed by FrontLine itself.

2.6. Pools
The Pools view is split by pool type, each in a different tab. There are currently 7 types of pool:

• On-premises: a pool which contains hosts configured manually

• AWS: used to spawn instances on a configured AWS account

• GCE: used to spawn instances on a configured GCE account

18
 • OpenStack: used to spawn instances on a configured OpenStack account

• Digital Ocean: used to spawn instances on a configured Digital Ocean account

• Microsoft Azure: used to spawn instances on a configured Microsoft Azure account

• Kubernetes: used to spawn instances through your configured Kubernetes/OpenShift.

If you are using the AWS marketplace offer, you will only have access to the On-premises, AWS, and
Kubernetes pools.

2.6.1. Warning about Private Keys

Every pool except Kubernetes will need to have a Private key configured. You won’t be able to
create one of these pools if you have not created a private key.

2.6.2. On-premises

Here you can create an On-premises pool which represents existing machines.

The pool is defined by a name and a team:

19
You can edit the name and set if the pool is global or owned by a team by clicking on the  icon of
that pool in the table. If you click on the name, it will highlight all the hosts which are in this pool in
the host table.

You can delete one or more pool by selecting them and click on the Delete button above the table.
The number of simulations associated to the pool is also displayed.

Now you need to create an host and assign it to the pool. To do so, you need to fill the following
form:

An host is basically a server where the FrontLine API will send the build project to use it as an
injector for the test.

• Hostname: the hostname of the server

• User: the username to use for the connection to the server

• Private Key: the private key used by the server for SSH authentication

• Pool: Choose the pool to assign the host. You can select Unassigned Hosts if you don’t want to put

20
 your host into a pool yet.

• Working Directory: Directory on the host where the code will be launched, it needs to be
executable

To be sure that FrontLine can access to the host you can click on the Check connection button.

You can edit your hosts by clicking on the  icon in the hosts table. You can duplicate an host to
quickly create an host with the same parameters by clicking on the  icon of the host on the table.

If you select one or more hosts, you will see a new button named Action appear on the search bar
above the table which allow you to delete all the selected hosts or to switch pool to another for all
selected hosts.

You can sort the pool table or the host table by clicking on their respective columns.

2.6.3. AWS Pool

An AWS Pool is a reference to the AWS account you want to use to spawn injectors to run the
simulation. To configure the type of instances you want to spawn, you need to fill the form below:

21
22
 • Team: Set if the pool is global or owned by a team

• Profile Name: Name of the AWS profile described in the AWS credentials file. If you want to use
System or Environment properties instead of this file, choose Use environment or system
variables
• Region: the region where to spawn your instances

• AMI: the AMI you want to use for your instances. You can use our certified AMI’s or the ID of
your custom AMI (the AMI should at least have JDK8 installed, a configured key pair without
password and the port 22 & 9999 should be open)

• Subnet: the subnet the instance will use

• Security Group: the security groups the instance will use

• Instance Type: the type of the instances you want to spawn

• Key Pair: the Key pair name used by your AMI

• User Name: the username used by your ssh command to connect to the instances. If you use
one of our certified AMIs, the username will be ec2-user

• Private Key: the previously added private key used by your AMI

• Use Elastic IP: Allow instances to use predefined Elastic IP

• Use private IP: FrontLine will use the injector private IP instead of the public one by default. If
unchecked, the private IP remains a fallback if a public IP is missing. This option should be used
only when the FrontLine host and the injector are both on AWS on the same network.

• IAM Instance Profile: optional step, you can specify an IAM instance profile to grant injectors
permissions

• AWS tags: optional step, the tags will be visible in your AWS interface, hence you will be able to
monitor them

2.6.4. GCE Pool (On-premises license only)

Like the AWS Pool, a GCE Pool is a reference to the GCE account you want to use to spawn injectors
to run the simulation. To configure the type of instances you want to spawn, you need to fill the
form below:

23
 • Team: Set if the pool is global or owned by a team

• If your service account key is a JSON file, you’ll need to specify its absolute path on the
FrontLine’s host. Otherwise, you’ll need to specify the GCE Project ID, the service account ID,
and the absolute path to the account private key

• Username: the username used by your ssh command to connect to the instances

• Private Key: the previously added private key used by your Template

• Region: the region where you want to spawn your instances

• Template: the template used for your instances, the template should at least have JDK8
installed, a configured key pair without password and the port 22 & 9999 should be open

2.6.5. OpenStack Pool (On-premises license only)

Like the others pools, an OpenStack Pool is a reference to the OpenStack account you want to use to
spawn injectors to run the simulation. To configure the type of instances you want to spawn, you

24
need to fill the form below:

25
 • Team: Set if the pool is global or owned by a team

• Keystone Version: version of Keystone, the identity manager for OpenStack. We support
Keystone version 2.0 and 3

• Identity Endpoint: complete url of your OpenStack API (eg: https://auth.cloud.ovh.net/v2.0)

• Identity: your OpenStack identity → for Keystone v3: domain:username, for Keystone v2.0:
tenantName:username
• Credentials: Account password

• Scope: if you chose keystone v3, you can use scoped authentication (eg: project:myprojectname)

• Region: the region where to spawn your instances

• Key Pair: the Key pair name use by your image

• Image: the image used for your instances (the image should at least have jdk8 installed and a
configured key pair without password and the port 22 & 9999 should be open)

• Flavor: the flavor used for your instances

• Security Group: the security group of your account

• Username: the username used by your ssh command to connect to the instances

• Private Key: the previously added private key used by your images

• Availability Zone: the optional availability zone

2.6.6. Digital Ocean Pool (On-premises license only)

A Digital Ocean pool is a reference to the Digital Ocean account you want to use to spawn injectors
to run the simulation. To configure the type of instances you want to spawn, you need to fill the
form below:

26
 • Team: Set if the pool is global or owned by a team

• Token: API token created in Digital Ocean, in the menu API

• Image: the image used for your instances (the image should at least have jdk8 installed and port
22 & 9999 should be open)

• Ssh Key: the ssh key without password used to connect to the image

• Size: the size of the droplets you want to create

• User Name: the username used by your ssh command to connect to the instances

• Private Key: the previously added private key used by your images

2.6.7. Microsoft Azure Pool (On-premises license only)

A Microsoft Azure Pool is a reference to the Azure account you can use to spawn injectors to run
the simulation. Only Linux virtual machines are supported.

27
To configure the type of instances you want to spawn, you need to fill the form below:

• Team: Set if the pool is global or owned by a team

• Subscription ID: the Azure subscription you want to use, check https://www.inkoop.io/blog/
how-to-get-azure-api-credentials/ to retrieve it

• Tenant ID: the Azure tenant you want to use

28
 • Client ID: the id of the Azure client you want to authenticate with

• Client Secret: the key used to authenticate

• Region: the region where you want to spawn your instances

• Size: the size of the instances

• Network: the network configured on your Microsoft Azure account you want to use

• Subnet: the subnet you want to use

• Image URL: the url of the image you want to use. To create an image, refer to the Azure
documentation

• Public Key: the public ssh key to connect to your instances

• Username: the username used by your ssh command to connect to the instances

• Private Key: the previously added private key associated with the public ssh key

2.6.8. Kubernetes/OpenShift Pool

A Kubernetes/OpenShift Pool is a reference to your Kubernetes infrastructure.

To configure the type of instances you want to spawn, you need to fill the form below:

29
 • Team: Set if the pool is global or owned by a team

• Kubernetes Url: The url of your Kubernetes API with the protocol

• Service Account Token: The token of your service account which has edit permissions on the
namespace below

• Namespace: The namespace/project name in which injectors will be spawned

• Injector Image: name and version of the docker image that will be used for injectors. You
should use the default one if your kubernetes have access to Docker Hub, or build your own
with https://github.com/gatling/frontline-injector-docker-image. The default image name is
gatling/frontline-injector:2.0

• Specify Pod resources: If you want to fix your requirements and limit for resources (optional
but highly recommended). It will activate the fields below.

30
 • Minimum number of cores: The minimum number of cores that you need for each one of your
injector, express as cpus

• Maximum Number of Cores: The limit of cores that you don’t want your injector pod to
exceed, express as cpus

• Minimum Memory: The minimum memory that you need for each one of your injector,
express as megabytes

If your FrontLine instance belongs to a Kubernetes cluster, you don’t have to

provide a Kubernetes Url and a Service Account Token. You can still choose to
 configure it, for example to create a pool in another cluster, by unticking Use local
cluster.

2.7. Simulations
To access the Simulations section, click on Simulation in the navbar.

The Simulations view contains all the simulations you have configured and the result of their last
run.

31
If you don’t have any simulations configured yet and don’t know how to start, you can download
some FrontLine pre-configured projects by clicking on the "Download sample simulations" green
button.

Those samples are ready to use maven, sbt and gradle projects with proper configuration for
FrontLine. You can also download those samples with the download link in the Documentation
section.

Back to the Simulation section, at the top, there is an action bar which allow several actions:

• Create a simulation

• Search by simulation name

• Edit global settings

• Delete selected simulations

2.7.1. Global Settings

Global settings contains every JVM arguments and system properties used by all of your
simulations by default. Editing those settings will be propagated to all the simulations.

32
In case you don’t want theses, you will be allowed to ignore those settings by checking the Override
Global Properties box when creating or editing a simulation:

33
2.7.2. Creating a simulation

In order to create a simulation click on the "Create" button in the simulations table. There are 6
steps to create a simulation, 3 of which are optional.

Step 1: General

• Name: the name that will appear on the simulations table.

• Team: the team which owns the simulation.

• Class name: the package and the name of your simulation scala class in the project that you

34
 want to start.

Step 2: Build configuration

Option 1: Build from sources

In this step, you’ll describe how FrontLine will fetch a source repository, compile and package it.

• Download sources: the way you want to retrieve your sources.

◦ Clone a git repository

◦ Use a project on FrontLine’s filesystem

◦ Check out from Source Code Control System (if you need to use a really specific git command
or if you use another scm)

• Build command: the command to build your project. Three common commands are built-in for
projects whose build tools configuration follow our installation guide:

◦ mvn clean package -DskipTests --quiet for maven project

◦ sbt ;clean;test:assembly --error for sbt project

◦ gradle clean testJar -quiet for gradle project

If you need a specific command to build your project, choose Use custom build command.

35
 FrontLine API supposes that, in this case, sbt, git, and ssh are installed and
 available.

You can provide optional settings if you toggle Advanced build configuration.

• Relative path: the path to you simulation project in your repository (eg the Gatling simulation
is not at the root of your git)

• Build variables: the environment variables to be used along the build command. You can add
as many environment variables as you want

When building from a git repository:

• Git SSH key: the previously added private key when you are targeting a private repository

• Git branch: the branch on which you want to retrieve your sources, master by default

When building from a project on FrontLine’s filesystem:

36
When building from a check out from Source Code Control System:

• Repository variables: the environment variables to be used along the fetching Repository
command. You can add as many environment variables as you want.

37
Option 2: Download binary from repository

In this step, you’ll describe how FrontLine will download a jar deployed in an previously added
repository. This jar must have been built with the same maven/sbt/gradle configuration as
described in the Developer section in this guide.

• Repository: the previously added repository where your jar is uploaded

• Artifact Maven coordinates: the maven coordinates of the desired artifact. version markers are
not supported

Option 3: Download binary from AWS S3

In this step, you’ll describe how FrontLine will download a jar deployed in an AWS S3 bucket. This
jar must have been built with the same maven/sbt/gradle configuration as described in the
Developer section in this guide.

38
 • Profile: the AWS profile from ~/.aws/credentials, or using permissions granted to the EC2
instance FrontLine is deployed on

• Region: the region where you created your bucket

• Bucket name: the region where you created your bucket

• Key: the key for the jar you want to download

Step 3: Pools configuration

In this step, you’ll configure the pools used for the FrontLine injectors.

39
 • Weight distribution: on even, every injector will produce the same load. On custom, you have
to set the weight in % of each pool (eg the first pool does 20% of the requests, and the second
does 80%). The sum of the weight should be 100%.

• Pools: defines the pools to be used when initiating the FrontLine injectors, see the section about
pools. You can add many pools with a different number of hosts to run your simulation. If you
have more hosts than needed on your Pool, the hosts will be chosen randomly between all hosts
available in this Pool.

After this step, you can save the simulation, or click on More options to access optional
configuration.

Step 4 & 5: JVM arguments & system properites

These steps allows you to defines JVM arguments and system properties used when running this
particular simulation. You can choose to override the global properties.

40
 System and JVM properties will be saved in a snapshot that will be available in the
 run. This information will be visible by anyone who has read access. You can
exclude some properties from being copied if you prefix them with sensitive..

Step 6: Time window

Configuring a ramp up or ramp down means that the start and end of your simulation won’t be
used for calculating metrics and assertions.

41
 • Ramp Up: the number of seconds you want to exclude at the beginning of the run.

• Ramp Down: the number of seconds you want to exclude at the end of the run.

Ramps parameters will only be applied if the run duration is longer than the sum
 of the two.

2.7.3. Simulation table

Now that you have created a simulation, you can start it by clicking on the  icon in the Start
column of the table.

A run have the following life cycle:

• Building: in which it will download and build the simulation from the sources, preparing the
hosts if needed

• Deploying: in which it will deploy the simulation to run on all the hosts

• Injecting: in which the simulation is running and viewable from the Reports

By clicking on the  icon in the Build Start column, Frontline will display the build logs of the
simulation. There is a limit of 1000 logs for a run.

42
You can click on the  icon next to the status (if there is one) to display the assertions of the run.
Assertions are the assumptions made at the beginning of the simulation to be verified at the end:

2.7.4. Useful tips

• You can edit the simulation by clicking on the  icon next to his name

• You can search a simulation by his name

• You can sort the simulations by any column except the Start one

• A Delete button will appear on the action bar when you select a simulation, you will be able to
delete all the selected simulations

• When a simulation is running, you can abort the run by clicking on the Abort button

• You can copy a simulation ID by clicking on the  icon next to his name

Be aware that deleting a simulation will delete all the associated runs.

43
2.7.5. Run / Trends

Runs list and trends can be accessed by clicking on the  icon in the simulations table.

This view contains the list of your simulation’s runs which can be filtered by name and/or status
and the Trends which are displaying information between those runs.

Runs table

Like the result of the latest run in the simulations table you have access to the logs of the run by
clicking on the  icon and you can sort the table by each columns.

If there is one, You can click on the  icon next to the status to display the assertions of the run. You
can delete runs by selecting them and click on the Delete button in the action bar above the table.

44
You can comment a run by clicking on the  icon on the right side of the table.

You can also click on the  icon to see a snapshot of the run configuration. The system properties
beginning with sensitive. are not displayed.

Run Comparison

45
You can compare the results of two runs if you click on the "Compare runs" button in the table. It
allows you to compare the response time and errors of the two runs for each request.

You can choose the specific metric you want to compare by clicking on the metric name, and the
specific run you want to compare by clicking on the run number.

The delta and variance will be displayed, so you can check if there is a progression or a degradation
in performance.

Trends charts

The trends are charts that will display some globals statistics for each runs (eg: requests count) so
that you can easily see how well your runs went compared to each other. Each run is represented
by his number in the chart and the chart won’t display the statistics of a failed run (eg: Timeout,
broken, etc..).

You can filter the statistics shown by filtering through scenarios, groups or requests that are
involved in each runs. You can chose how many runs will be compared by changing the limit (10,
25, 50, 100):

46
2.7.6. Reports

The reports can be accessed by clicking on the  icon in the simulation table or in the runs table.

This view introduce all the metrics available for a specific run. This page consists of:

• The top navigation bar

• The timeline

• Tabs

• The run bar

• Charts area

• The summary (only for requests and groups tabs)

• Export PDF

Top Navigation Bar

The navigation bar enable you to choose the simulation time range.

47
Timeline

The timeline contains metrics of the full run providing an overview of the run. Global informations
are available such as the resolution and the simulation name.

You can change the time range with control buttons or by selecting a region on the timeline:

Assertions

The label below is used to display the status of the simulation (Ongoing, successful, timeout…). If
your simulation has assertions, this label will be clickable to show the assertions results. You can
comment the run run by clicking on the  icon.

Tabs

Below the navigator chart, there are tabs to switch charts. Each tab has the same structure except
the summary that is available only for requests and groups tabs.

Run Bar

This bar is a combination of buttons:

• Start / Abort: Use this button to start a new run of the simulation, or stop the ongoing run
(administrator & manager only)

• Grafana: Link to the Grafana dashboard if you have filled in the configuration in frontline.conf

• Generate public link: To create a public link

48
 • Switch to Summary: Switch to summary view for Requests & Groups tabs

• buttons to filter the metrics drawn in the charts area

Generate Public Links

A public link is a link of the current reports which will be accessible to anyone, without having to
log-in to FrontLine. To generate a public link, click on the Generate public link button and choose
the expiration date of your link.

The maximum allowed lifetime for a public link is 1 year.

Once you have chosen an expiration date, you can proceed by clicking on the generate button.

You can copy the public link to share your reports to non-FrontLine users, or click on the "Go"
Button to access it yourself. You can click on the "OK" button to close this modal.

Charts

Each charts in FrontLine are connected to each other, so if you select a time window on a chart it
will automatically change it for all other charts. Metrics are drawn in multiple charts.

49
Some of them have a icon to update the chart settings:

Moreover, histograms and pies are hidden behind each counts charts, accessible by clicking their
top right corner icon below.

If your kernel version is too low (around below 3.10) you might not be able to get
 data from the TCP connection by state graph on the Connections tab. If you want to
be able to get these data, you should upgrade your kernel.

Summary (Requests and Groups only)

This view is available only from requests and groups tabs. It is a summary of metrics drawn in the
charts, and has two modes: flat, by default, and hierarchy. The summary is also connected to the
timeline and the time window selected, so if you change the time window the summary will refresh
his data to match the time window.

On Flat mode you can filter the data by clicking any column name of the table.

Export PDF

When clicking on the green button in the navigation bar, you will have access to a page where you
can configure and then export a PDF report of a specific simulation.

This report is initialized with:

50
 • a title element with the date of the run you were coming from

• the run status

• the run comments

• the run assertions

• the run requests summary

• 3 charts of the run:

◦ Requests and Responses per second

◦ Responses per Second by Status

◦ Response Time Percentiles

This page is a configurable list of different elements that will be displayed in the report. You can
click on the blue add button under every element to add another one.

Every element can be moved up or down by clicking on the blue arrow on the top right of the
element, or be removed by clicking on the red dash.

Those elements are composed of:

• Title: add a title element.

• Text Area: add an editable text element.

• New Page: allow you to skip a page in the report.

• Run:

◦ Status: add an editable text element with a predefined text set to the status of the selected
run.

◦ Comments: add an editable text element with a predefined text set to the comments of the
selected run.

◦ Assertions: add a table with the assertions of the selected run.

51
 ◦ Summary: add the summary table of the selected run in a new landscape page.

• Chart: add a chart element that you can interact with before exporting it to PDF.

• Counts: add a count chart element that you can interact with before exporting it to PDF.

As you can see below, every charts (or other elements) can be interact with individually. You can
zoom on it, or select the run, the scenario, the group, etc.. whose you want your data to be fetch.
You do not need to have the same settings for each element.

After adding all desired elements in the report you can click on the Export PDF button on the top
right to get your PDF file.

There are two more actions you can do:

• Save: save the current Export configuration:

◦ as a template: this option will save the element list without the content

◦ as a save: this option will save everything, including the content of the Text Area and the
configuration of the graphs

• Load: load a previously saved template or save. You can also import a json template created by
FrontLine 1.7.x

Useful Tips

52
Zoom

You can reset zoom by double clicking on a chart. It is possible to change the time range window by
the following actions:

• Clicking zoom icons of the control buttons

• Select a zone in any charts and timeline

• Select a range time from the top navigation bar

Markers

To ease your analysis, you can create markers on all the charts by right clicking on them. And click
on the top of the marker to delete it.

Multiple Highlights

In the top right menu, you can activate the Multiple Highlights setting which allows the tooltip to
be displayed on every chart at the same time.

53
Percentiles Mask

In the top right menu, you can click on the Percentiles setting to be able to chose what percentiles
to display in the chart.

Date Time / Elapsed Time

In the top right menu, you can activate the Date Time setting to be able to switch from elapsed time
to date time.

54
Highlight Legend

By hovering the label on the percentiles chart legend, you will be able to highlight the curve on the
chart, leading to a better view of that curve. The highlight legend options is enable to every "non
stacked" graph.

2.8. Documentation
You can click on the Documentation icon in the navigation bar on the bottom left of the screen to
diplay every link to the FrontLine documentation and samples.

2.9. About
You can click on the About icon in the navigation bar to display the informations about your
FrontLine version and your license expiration date.

55
56
Chapter 3. Public APIs
The FrontLine API server also exposes a public API that you can use to trigger runs or fetch run
results and metrics.

We also use this API for our Continuous Integration plugins and our Grafana datasource.

This API is protected with tokens generated by FrontLine administrators through the Admin > API
Tokens tab.

You can access the Swagger documentation using the link FrontLine API documentation on the
Documentation modal accessible on the sidenav (bottom left of the screen).

Some information before using the public API:

• Simulations ID are available on the Simulations Table, at the left of the simulation name.

• Runs ID are available on the Runs Table: Simulations > Runs history. To copy the id, click on the
 icon at the right of the run number.

• You can retrieve a team ID by clicking on the ID column inside the teams table.

• You have to provide the run ID as a query parameter to fetch other run metadata (injectors,
remotes, hostnames, scenarios, groups, requests)

• The from and to query parameters from the /series endpoint are the lower and upper
timestamp bounds of the time window you want to query. You can fetch the total run time
window from the /runs endpoint (injectStart, injectEnd).

57