Tsung Getting Started: High-Performance Load Testing with Erlang

Tsung Getting Started: High-Performance Load Testing with Erlang

Tsung is an open-source, distributed load testing tool written in Erlang. It's built on Erlang's actor model, which means it can generate extremely high concurrent load from a single machine or a cluster of injector nodes — with lower resource overhead than Java-based alternatives like JMeter.

If you need to generate thousands of concurrent users from commodity hardware, Tsung deserves a look.

What Is Tsung?

Tsung supports load testing for:

  • HTTP / HTTPS
  • WebSockets
  • XMPP (Jabber)
  • PostgreSQL
  • MySQL
  • LDAP
  • Jabber/XMPP

This guide focuses on HTTP, which is the most common use case. Tsung scenarios are defined in XML, which is verbose but explicit — you know exactly what requests are being made.

Installation

Ubuntu/Debian

sudo apt-get install -y tsung

CentOS/RHEL

sudo yum install -y epel-release
sudo yum install -y tsung

Mac (via Homebrew)

brew install erlang
brew install tsung

From Source

# Install Erlang first
# Then:
git clone https://github.com/processone/tsung.git
cd tsung
./configure
make
sudo make install

Verify:

tsung -v
# Tsung version 1.7.0

Your First Tsung Scenario

Tsung scenarios are XML files. Create tsung.xml:

<?xml version="1.0"?>
<!DOCTYPE tsung SYSTEM "/usr/share/tsung/tsung-1.0.dtd">

<tsung loglevel="notice" version="1.0">

  <!-- Clients: injector machines -->
  <clients>
    <client host="localhost" use_controller_vm="true"/>
  </clients>

  <!-- Target server -->
  <servers>
    <server host="api.example.com" port="443" type="ssl"/>
  </servers>

  <!-- Load profile: ramp up over time -->
  <load duration="5" unit="minute">
    <arrivalphase phase="1" duration="1" unit="minute">
      <users interarrival="0.1" unit="second"/>
    </arrivalphase>
    <arrivalphase phase="2" duration="4" unit="minute">
      <users interarrival="0.01" unit="second"/>
    </arrivalphase>
  </load>

  <!-- Define sessions -->
  <sessions>
    <session name="http_test" probability="100" type="ts_http">
      
      <request>
        <http url="/api/health" method="GET" version="1.1">
          <http_header name="Accept" value="application/json"/>
        </http>
      </request>

      <thinktime value="1" random="true"/>

      <request>
        <http url="/api/users" method="GET" version="1.1">
          <http_header name="Authorization" value="Bearer mytoken"/>
        </http>
      </request>

    </session>
  </sessions>

</tsung>

Run the test:

tsung -f tsung.xml start

Understanding the Load Profile

The <load> section controls how virtual users arrive:

<load duration="10" unit="minute">
  <!-- Phase 1: warm-up — 10 users/second for 2 minutes -->
  <arrivalphase phase="1" duration="2" unit="minute">
    <users interarrival="0.1" unit="second"/>
  </arrivalphase>
  
  <!-- Phase 2: peak load — 100 users/second for 5 minutes -->
  <arrivalphase phase="2" duration="5" unit="minute">
    <users interarrival="0.01" unit="second"/>
  </arrivalphase>
  
  <!-- Phase 3: cool-down — 10 users/second for 3 minutes -->
  <arrivalphase phase="3" duration="3" unit="minute">
    <users interarrival="0.1" unit="second"/>
  </arrivalphase>
</load>

interarrival is the time between new user arrivals (in seconds):

  • 0.1 = 10 users/second
  • 0.01 = 100 users/second
  • 1.0 = 1 user/second

HTTP Scenarios

POST Requests with JSON Body

<request>
  <http url="/api/users" method="POST" version="1.1"
        contents='{"name":"Test User","email":"test@example.com"}'
        content_type="application/json">
    <http_header name="Authorization" value="Bearer %%token%%"/>
  </http>
</request>

Dynamic Variables from CSV

Use CSV files to inject different data per user:

<!-- In header section -->
<options>
  <option name="file_server" id="userdata" value="users.csv"/>
</options>

<!-- In session -->
<setdynvars sourcetype="file" fileid="userdata" delimiter=";">
  <var name="email"/>
  <var name="password"/>
</setdynvars>

<request>
  <http url="/api/login" method="POST" version="1.1"
        contents='{"email":"%%_email%%","password":"%%_password%%"}'
        content_type="application/json"/>
</request>

users.csv format:

user1@example.com;password1
user2@example.com;password2
user3@example.com;password3

Extracting Values from Responses

<!-- Login and capture the auth token -->
<request>
  <dyn_variable name="auth_token" re='"token":"([^"]+)"'/>
  <http url="/api/login" method="POST" version="1.1"
        contents='{"email":"user@example.com","password":"secret"}'
        content_type="application/json"/>
</request>

<!-- Use the token in subsequent requests -->
<request>
  <http url="/api/profile" method="GET" version="1.1">
    <http_header name="Authorization" value="Bearer %%_auth_token%%"/>
  </http>
</request>

Think Time

Think time simulates the pause between user actions:

<!-- Fixed think time: 2 seconds -->
<thinktime value="2"/>

<!-- Random think time: between 1 and 5 seconds -->
<thinktime value="5" random="true"/>

Analyzing Results

After the test, Tsung generates logs in ~/.tsung/log/TIMESTAMP/. Generate an HTML report:

cd ~/.tsung/log/20240115-143022/
/usr/lib/tsung/bin/tsung_stats.pl
# or on some systems:
tsung_stats.pl --stats tsung.log

This creates tsung.html with charts showing:

  • Requests per second
  • Response time distribution (mean, 95th percentile)
  • Error rates
  • User count over time
  • Concurrent users

Open tsung.html in a browser to review the charts.

Key Metrics to Watch

Response time mean and 95th percentile: The average is misleading under load. Focus on the 95th percentile — if that stays under your SLA, most users have a good experience.

Error rate: Should stay near zero. Any HTTP 5xx errors indicate server overload or bugs under load.

Requests/second plateau: The maximum throughput your server sustains. When errors start appearing or response times spike, you've found the ceiling.

Concurrent users: How many simultaneous sessions the server supports before degradation.

Configuration Tips

Increase Open File Limit

Tsung needs many open sockets. On Linux:

ulimit -n 65536

Add to /etc/security/limits.conf for persistence:

* soft nofile 65536
* hard nofile 65536

Verbose Logging

<tsung loglevel="debug" version="1.0">

Debug logging is useful during scenario development but slows execution — disable for actual load tests.

Timeouts

<options>
  <option name="connect_timeout" value="5000"/>   <!-- 5 seconds -->
  <option name="max_retries" value="3"/>
</options>

When to Use Tsung

Tsung is a good fit when:

  • You need to push very high concurrency from a single machine
  • Your team is comfortable with XML configuration
  • You want distributed load generation with minimal infrastructure overhead
  • You're testing non-HTTP protocols (XMPP, PostgreSQL, etc.)

Consider alternatives when:

  • You need a visual GUI for test creation (use Gatling or BlazeMeter)
  • Your team is more comfortable with code (use k6 or Locust)
  • You need cloud-based load generation without managing injectors (use BlazeMeter, k6 Cloud)

Summary

Tsung's Erlang foundation gives it a genuine throughput advantage at the low end of the hardware budget. A single Tsung node can sustain concurrent loads that require multiple JMeter nodes to match.

The XML scenario format is verbose but readable once you understand the structure. The built-in reporting is basic but sufficient for identifying throughput ceilings and response time degradation.

For teams that need high-volume load testing without a large infrastructure budget, Tsung remains a viable and actively maintained option.

Read more

Start now free