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 tsungCentOS/RHEL
sudo yum install -y epel-release
sudo yum install -y tsungMac (via Homebrew)
brew install erlang
brew install tsungFrom Source
# Install Erlang first
# Then:
git clone https://github.com/processone/tsung.git
cd tsung
./configure
make
sudo make installVerify:
tsung -v
# Tsung version 1.7.0Your 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 startUnderstanding 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/second0.01= 100 users/second1.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;password3Extracting 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.logThis 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 65536Add to /etc/security/limits.conf for persistence:
* soft nofile 65536
* hard nofile 65536Verbose 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.