Purpose of this article

This article will cover the steps needed to migrate from a load-testing simulation done in Gatling Open-Source to Gatling FrontLine, our Enterprise version.

If you want to go further with Gatling and use Gatling FrontLine within a few minutes, this guide is made for you!

We will see in this article how to run and configure Gatling FrontLine in order to run your Gatling simulations and check your reports.

The Gatling simulation that I am using in this article is hosted here.

What is Gatling FrontLine?

Gatling FrontLine is a management interface for Gatling, developed by Gatling Corp, the team behind Gatling Open-Source. It includes live reports accessible by your whole team, advanced metrics, and advanced features for integration and automation. Check our website for the complete list of features.

Launch Gatling FrontLine

There are 2 ways to evaluate FrontLine:

For this article, we will use the free trial on the AWS Marketplace.

Check out the Part 1 here to launch your Gatling FrontLine instance in the AWS Marketplace! When you are done launching your Gatling FrontLine instance, you can move to the next step!

Build tool configuration

To use Gatling with Gatling FrontLine, you’ll need a build tool, like Maven, Sbt or Gradle. If you didn’t use one with Gatling Open-Source, a build tool describes how to build your application automatically. We’ll use Maven in this article, as it is the most common one.

Maven configuration is stored in a file named pom.xml, and it needs a specific directory structure, take a look at our official demo: https://github.com/gatling/gatling-maven-plugin-demo. We just need to do one small modification for it to work with Gatling FrontLine: add the following plugin tag inside the tag <plugins></plugins>:

<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>

If you want to see what the resulting pom.xml will look like, check the one I used for this article at. If you want to use another build tool, check our documentation.

Simulation Configuration

If you followed the part 1 of this series here, you should have an instance of FrontLine already up.

Once connected to this instance, you’ll arrive to the simulations table. This page references all your Gatling simulations, with direct links to their reports and trends. Feel free to have a glance at their configuration and reports to see all the interesting features of Gatling FrontLine!

If you chose Gatling FrontLine as a free trial on AWS, you’ll need to delete the existing simulations to create your own. Indeed, you have a limit of one simulation with this offer. If you want more simulations, you’ll need to choose another offer. To delete a simulation, select it with its checkbox, then click on the delete button.

Now click on the button to begin the simulation configuration. We’ll choose My Simulation as the name and the default Gatling team. The Class name is the package and name of your simulation class, in my case: com.ccousseran.gatling.BasicSimulation.

Click on Next to configure the build. We use a git repository, so the two first selected are to remain unchanged. On the Git Repository URL, just enter your repository URL, mine is: https://github.com/ccedric/GatlingArticles.git. As my simulation is a Maven simulation, I chose Maven project as build command.

Click on Next to arrive to the last step. In this step, we’ll configure on which pools the injection will start. Choose Local (Demo Purpose Only) and click on Save to finish the simulation configuration.

 

Reports and Trends

Now that the simulation is set up, we can run it by clicking on . You can see the logs of the compilation by clicking on . Once the injection starts, you can see the results live with.

This reports page has all the metrics and data about your run. You can find the same metrics as in Gatling Open-Source and even more! The default tab shows you all the data about the requests, but you can change tab to have data about the other kind of metrics: Groups, Users, Connections, DNS, Bandwidth and Injectors. Take a few minutes to explore everything, and don’t forget that you can choose the data displayed in every charts and zoom in/out of them.

If you run this simulation a few more times, you’ll also be able to access the trends page by clicking on in the simulations table. The trends show you the evolution of your results between the different runs, and any regression at the same time. You can also click on to compare each run more precisely.

Advanced Gatling FrontLine configuration

The configuration we just did was a basic one to get things work quickly. We will now see some configuration you may need to do later:

Connection to a private git repository

We chose to host our simulation publicly on Github. However, in your case, you may want to host it on a private git repository (eg: Gitlab, private Github repository). The easiest way to authenticate with a private repository is to create a ssh key pair.

To get this work, you’ll need to create a new ssh key pair and add it to your private git repository. It can be done easily with Gitlab or Github. A read access to the repository is enough for Gatling FrontLine.

Once the private key is configured on your git repository, we’ll need to add the private ssh key file to Gatling FrontLine. On the Gatling FrontLine interface, navigate from Admin on the left navigation bar to Private Keys.

You can now create a new private key by clicking on  . We’ll leave the team as global, and then upload the private key, by drag-and-dropping the file in the Private Key field.

Once the private key is saved, we can use it in our Git simulation. In the Simulation build step, click on Git SSH key, and choose the private key you just created. Now Gatling FrontLine can clone your private Git simulation.

AWS pool configuration

In our first test, we chose to run the simulation locally on Gatling FrontLine’s host. If we want to use multiple real injectors, we will need to configure a pool. A pool in Gatling FrontLine is a configuration of computers which will be used as injectors for the load-test. These injectors can be on-premises (computers on your infrastructure dedicated to load-testing), on a Kubernetes cluster, or on a cloud provider (eg: Amazon EC2, Google Cloud, Microsoft Azure).

We will create a new AWS pool, as Gatling FrontLine is already hosted on AWS (and other cloud providers are not accessible if you bought Gatling FrontLine on the AWS marketplace). The easiest way to configure an AWS account on Gatling FrontLine is to add an IAM role on the Gatling FrontLine instance from the AWS EC2 interface. To do that, select the instance, then Attach/Replace IAM Role. Gatling FrontLine needs the following permissions (or grant AmazonECFullAccess if you don’t care about fine-grained permissions):

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Action": [
        "ec2:Describe*",
        "ec2:CreateTags",
        "ec2:RunInstances",
        "ec2:TerminateInstances",
        "ec2:AllocateAddress",
        "ec2:AssociateAddress"
      ],
      "Effect": "Allow",
      "Resource": "*"
    }
  ]
}

You’ll also need to create a key pair on the AWS interface, and upload the private key to Gatling FrontLine (see private key section). Now that the configuration on AWS is done, go back to the Gatling FrontLine interface and navigate from Pools on the left navigation bar to Amazon EC2.

Choose to begin the pool configuration. If you set up the IAM role to the Gatling FrontLine instance, you can choose [Use environment or system variables] as Profile Name. Then choose the Region where you want to spawn the injectors, and choose a certified AMI. Select the subnet, security group and instance type you wish to use. For the Key Pair use the one you created on the AWS interface, and choose the corresponding private Key.

You can now save to finish the pool configuration. If you go back to the simulations page and edit your simulation, you will be able to choose the AWS pool we just configured. You can now launch the injection on a more powerful computer, and even choose to distribute the load against multiple injectors by increasing the number (NOTE: the basic offer on AWS limits your injector number to 1).

Integrations with other services

Gatling FrontLine can fully integrate your CI/CD pipeline. For that purpose, you can use the public API (you can see the corresponding swagger if you click on Documentation in the bottom-left). We already have many official plugins: Jenkins, Bamboo, Teamcity, Grafana …

To interact with this API, you’ll need an API Token. You can manage those by clicking on Admin on the top-left, then API Tokens.

Let’s create an API Token by clicking on . You can set up the permissions of the token globally, or by team. If you want to use the API Token in a CI, you’ll need the All permission. Don’t forget to copy the token after creating it, as you won’t be able to retrieve it later.

You can download our plugins if you click on Plugins in the bottom-left. Then you just need to upload them into your CI, which will then be able to start a Gatling FrontLine simulation, and query all the data from the reports. If you use a CI service not listed in our plugins, we also provide a script in the Plugins guide which provides the same behavior as the other plugin.

Thanks

Thanks you for reading this detailed article. I hope it helped you see how easy it was to migrate to Gatling FrontLine and the benefits of switching to the Enterprise version. Of course, there are still plenty of features of Gatling FrontLine we didn’t cover in this article, which will maybe be covered in another one.

If you want to discover those other features by yourself, check out our website: https://gatling.io/gatling-frontline/ and our documentations (click on Documentation on the bottom-left of the screen).

If you have more questions about the licensing or the product, you can send us an e-mail at contact@gatling.io !

 

A template engine is a way to include some logic in your document/JSON, by putting keywords which will be interpreted and replaced when the simulation is launched.

Expression Language templating

Before Gatling 3, there was only one way to use dynamic variables inside a request body, the Expression Language (also named EL). Expression Language supports basic operations, like fetching an attribute in the session (memory case of a user) and some functions. In the following example, ${id} and ${name} will be replaced by the “id” and “name” attributes in the session.

{
  "id": ${id},
  "name": "${name}",
  "numberOfChildren": 2,
  "children": [{
    "id": 1002,
    "name": "Paul Smith"
  }, {
    "id": 1003,
    "name": "Jessica Smith"
  }]
}

Pebble templating

We introduced in Gatling 3 a new way to craft request bodies, Pebble templating. Pebble is a logic-full templating engine, with several interesting features missing in EL: filters, if, loop, import…

No specific import is needed to use this feature.

Let’s see how we can modify the following JSON file to use the attributes defined in the session: the id/name of the user, and an array of children.

{
  "id": 1000,
  "name": "John Smith",
  "numberOfChildren": 2,
  "children": [{
    "id": 1002,
    "name": "Paul Smith"
  }, {
    "id": 1003,
    "name": "Jessica Smith"
  }]
}

The first step is to replace the id and name by the ones in the session. Gatling will replace {{id}} and {{name}} by the attributes named “id” and “name” in the session .

{
  "id": {{id}},
  "name": "{{name}}",
  "numberOfChildren": 2,
  "children": [{
    "id": 1002,
    "name": "Paul Smith"
  }, {
    "id": 1003,
    "name": "Jessica Smith"
  }]
}

The second step is to compute the length of our array of children. We can use the filter “length” available in Pebble.

The final step is to loop over our children to query their id and name. Our loop begins with “{% for %}” and ends at “{% endfor % }”, displaying the id and name of each current child.  We’re not displaying the comma for the last element of the array thanks to an if condition.

{
  "id": {{id}},
  "name": "{{name}}",
  "numberOfChildren": {{children|length}},
  "children": [
  {% for child in children %}
      {
        "id": {{child.id}},
        "name": "{{child.name}}"
      }{% if loop.last %}{% else %},{% endif %}
  {% endfor %}
  ]
}

Once you’ve created your Pebble template, you can use it in Gatling:

.body(PebbleStringBody(""" file body as String """)).asJson
// or
// myFileBody.json is a file that contains our JSON
.body(PebbleFileBody("myFileBody.json")).asJson

Expression Language vs Pebble

Expression Language is faster and simpler than Pebble, however Pebble has more advanced features. I recommend using EL if your needs are simple. If your needs are more complicated, you can consider using Pebble or EL with a bit of Scala.

We’ll continue to maintain both Pebble and the Expression Language, so be sure to use the option which fits your needs!

 

Thanks for reading this article about Pebble templating in Gatling, check Pebble documentation or Gatling documentation for more examples.

Cédric for the Gatling team