Tsung High-Load Testing: Millions of Users with Erlang

Tsung High-Load Testing: Millions of Users with Erlang

Tsung is an Erlang-based load testing tool designed for extremely high concurrency—millions of simulated users on a single server. It uses XML configuration files for scenarios, supports HTTP, WebSocket, XMPP, PostgreSQL, and MySQL protocols, and generates HTML reports with performance graphs.

When you need to simulate millions of concurrent users without a fleet of machines, Tsung is one of the few tools that can do it. Built on Erlang/OTP—the same runtime that powers WhatsApp and Ericsson telecom switches—Tsung leverages Erlang's lightweight processes to run millions of coroutines on modest hardware. One Tsung node can handle 1M+ simultaneous connections where Java-based tools would exhaust thread pool limits at 10,000.

Why Tsung?

Tsung's differentiating characteristics:

  • Massive concurrency: Erlang processes are ~500 bytes each vs. OS threads at ~1MB. One machine with 16GB RAM can run millions of simulated users.
  • Multi-protocol: HTTP/HTTPS, WebSocket, XMPP, MQTT, PostgreSQL, MySQL, LDAP, Memcached. Most load tools support only HTTP.
  • Distributed by design: Multiple Tsung nodes coordinate through Erlang's distributed messaging. Adding capacity means adding Erlang nodes.
  • Session recording: Tsung proxy records browser sessions and generates XML scenarios from real user behavior.

Installation

# Ubuntu/Debian
sudo apt-get install tsung

# macOS (via Homebrew)
brew install tsung

# From source (requires Erlang)
wget http://tsung.erlang-projects.org/dist/tsung-1.8.0.tar.gz
tar xzf tsung-1.8.0.tar.gz
cd tsung-1.8.0
./configure && make && sudo make install

Verify: tsung -v should output the version.

Configuration File Structure

Tsung tests are configured in XML:

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

  <!-- Define client nodes (load generators) -->
  <clients>
    <client host="localhost" use_controller_vm="true" maxusers="5000"/>
  </clients>

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

  <!-- Load progression: users and arrival rate -->
  <load duration="10" unit="minute">
    <arrivalphase phase="1" duration="2" unit="minute">
      <users interarrival="0.01" unit="second"/>  <!-- 100 users/second -->
    </arrivalphase>
    <arrivalphase phase="2" duration="5" unit="minute">
      <users interarrival="0.005" unit="second"/>  <!-- 200 users/second -->
    </arrivalphase>
    <arrivalphase phase="3" duration="3" unit="minute">
      <users interarrival="0.001" unit="second"/>  <!-- 1000 users/second -->
    </arrivalphase>
  </load>

  <!-- Session definitions -->
  <sessions>
    <session name="http_test" probability="100" type="ts_http">

      <!-- Request with think time -->
      <request>
        <http url="/api/products" method="GET" version="1.1">
          <http_header name="Accept" value="application/json"/>
        </http>
      </request>

      <!-- Think time: simulate user pausing -->
      <thinktime value="2" random="true"/>

      <!-- Request with dynamic data -->
      <request>
        <http url="/api/products/%%product_id%%" method="GET" version="1.1"/>
      </request>

    </session>
  </sessions>

</tsung>

Load Phase Configuration

The <load> section defines how users arrive over time:

<load duration="15" unit="minute">
  <!-- Phase 1: Ramp up (2 minutes) -->
  <arrivalphase phase="1" duration="2" unit="minute">
    <users interarrival="0.1" unit="second"/>  <!-- 10 users/second -->
  </arrivalphase>

  <!-- Phase 2: Steady state (10 minutes) -->
  <arrivalphase phase="2" duration="10" unit="minute">
    <users interarrival="0.02" unit="second"/>  <!-- 50 users/second -->
  </arrivalphase>

  <!-- Phase 3: Peak spike (2 minutes) -->
  <arrivalphase phase="3" duration="2" unit="minute">
    <users interarrival="0.005" unit="second"/>  <!-- 200 users/second -->
  </arrivalphase>

  <!-- Phase 4: Cool down (1 minute) -->
  <arrivalphase phase="4" duration="1" unit="minute">
    <users interarrival="0.1" unit="second"/>
  </arrivalphase>
</load>

Alternatively, define total user count:

<arrivalphase phase="1" duration="5" unit="minute">
  <users maxnumber="10000" interarrival="0.005" unit="second"/>
</arrivalphase>

maxnumber="10000" caps total concurrent users at 10,000 regardless of arrival rate.

Dynamic Variables and Data Extraction

Extract values from responses and use them in subsequent requests:

<session name="checkout_flow" probability="100" type="ts_http">

  <!-- Browse products -->
  <request>
    <dyn_variable name="product_id" re="\"id\":([0-9]+)"/>
    <http url="/api/products" method="GET" version="1.1"/>
  </request>

  <thinktime value="1"/>

  <!-- Use extracted product_id -->
  <request>
    <http url="/api/products/%%product_id%%" method="GET" version="1.1"/>
  </request>

  <!-- POST with JSON body using extracted value -->
  <request>
    <http url="/api/cart" method="POST" version="1.1"
          contents='{"product_id": %%product_id%%, "qty": 1}'
          content_type="application/json"/>
  </request>

  <!-- Extract order ID from cart response -->
  <request>
    <dyn_variable name="order_id" re="\"order_id\":\"([^\"]+)\""/>
    <http url="/api/orders" method="POST" version="1.1"
          contents='{"payment": "card"}'
          content_type="application/json"/>
  </request>

  <thinktime value="2"/>

  <!-- Confirm order using extracted ID -->
  <request>
    <http url="/api/orders/%%order_id%%/confirm" method="POST" version="1.1"/>
  </request>

</session>

dyn_variable with re= extracts via regex. The captured group is stored in the named variable.

File-Based Data Sources

Feed realistic data from CSV files:

<!-- Define the file -->
<options>
  <option name="file_server" id="users" value="/etc/tsung/users.csv"/>
</options>

<sessions>
  <session name="authenticated" probability="100" type="ts_http">
    <!-- Read a row from the CSV -->
    <setdynvars sourcetype="file" fileid="users" delimiter=";" order="random">
      <var name="email"/>
      <var name="password"/>
    </setdynvars>

    <!-- Login with CSV data -->
    <request>
      <http url="/api/auth/login" method="POST" version="1.1"
            contents='{"email": "%%email%%", "password": "%%password%%"}'
            content_type="application/json"/>
    </request>
  </session>
</sessions>
# /etc/tsung/users.csv
user1@example.com;pass1
user2@example.com;pass2
user3@example.com;pass3

WebSocket Testing

<sessions>
  <session name="websocket_test" probability="100" type="ts_websocket">

    <!-- Connect to WebSocket server -->
    <request subst="true">
      <websocket type="connect" url="ws://ws.example.com/chat"/>
    </request>

    <!-- Send a message -->
    <request>
      <websocket type="message">
        <data format="json">{"type": "join", "room": "general"}</data>
      </websocket>
    </request>

    <!-- Wait for incoming messages -->
    <request>
      <websocket type="receive" timeout="5000">
        <match do="continue" when="match">joined</match>
      </websocket>
    </request>

    <thinktime value="3"/>

    <!-- Send chat message -->
    <request>
      <websocket type="message">
        <data format="json">{"type": "message", "content": "Hello from Tsung"}</data>
      </websocket>
    </request>

    <!-- Close connection -->
    <request>
      <websocket type="close"/>
    </request>

  </session>
</sessions>

Database Load Testing (PostgreSQL)

<clients>
  <client host="localhost" use_controller_vm="true"/>
</clients>

<servers>
  <server host="db.example.com" port="5432" type="tcp"/>
</servers>

<sessions>
  <session name="pg_test" probability="100" type="ts_pgsql">

    <!-- Execute SQL queries -->
    <request>
      <pgsql query="SELECT id, name, price FROM products WHERE category = 'electronics' LIMIT 20"/>
    </request>

    <thinktime value="1"/>

    <request>
      <pgsql query="INSERT INTO page_views (product_id, timestamp) VALUES (1, NOW())"/>
    </request>

  </session>
</sessions>

Distributed Load Generation

Add client nodes for higher scale:

<clients>
  <!-- Primary node (controller) -->
  <client host="tsung-master" cpu="4" use_controller_vm="false"/>

  <!-- Additional load generators -->
  <client host="tsung-agent-1" cpu="4" maxusers="100000"/>
  <client host="tsung-agent-2" cpu="4" maxusers="100000"/>
  <client host="tsung-agent-3" cpu="4" maxusers="100000"/>
</clients>

Requirements for distributed nodes:

  1. Erlang installed on all nodes
  2. Same Tsung version on all nodes
  3. SSH key-based authentication from master to agents
  4. Erlang node names resolvable (add to /etc/hosts or DNS)

Start the distributed test from the master:

tsung -f tsung-distributed.xml start

Tsung SSH-connects to agent nodes, starts Erlang processes, and coordinates the test automatically.

Running and Monitoring

# Start a test
tsung -f config.xml start

# List running tests
tsung status

# Stop a running test
tsung stop

Logs are stored in ~/.tsung/log/YYYYMMDD-HHmmSS/.

During the test, watch real-time stats:

tail -f ~/.tsung/log/*/tsung.log

Generating HTML Reports

# After test completion
cd ~/.tsung/log/20260527-103000/
/usr/lib/tsung/bin/tsung_stats.pl
# or
tsung_stats.pl --stats tsung.log

# Open the generated report
open report.html

The HTML report includes:

  • Users over time
  • Request rate (TPS)
  • Response time distribution
  • Error rate
  • Page graph (response times per page/request)

Running via Docker

docker run --rm \
  -v $(pwd)/tsung.xml:/etc/tsung/tsung.xml \
  -v $(pwd)/results:/root/.tsung/log \
  ddragosd/tsung \
  -f /etc/tsung/tsung.xml start

Tsung vs. Other High-Concurrency Tools

Aspect Tsung Gatling Locust
Max concurrency (1 server) 1M+ users ~50K users ~20K users
Configuration XML Scala DSL Python
Protocols HTTP, WS, XMPP, DB HTTP, JMS HTTP (custom clients)
Setup complexity Medium High (Scala) Low
Community Small Large Large

Tsung's Erlang foundation gives it genuine concurrency advantages. If your requirement is 500K+ concurrent connections on minimal hardware, Tsung is one of the few options. For more typical load testing (< 50K VUsers), Locust or Gatling offer better developer experience.

Summary

Tsung's Erlang runtime enables concurrency that Java and Python-based tools can't match at equivalent hardware cost. XML configuration is verbose but comprehensive—arrivalphases model complex load curves, dyn_variable extracts session data, file_server feeds realistic user data. For testing XMPP chat servers, high-volume WebSocket APIs, or database connection limits, Tsung covers protocols that most load tools ignore. When you need to simulate a million users and don't have a million dollars of AWS budget to do it, Tsung is worth the configuration overhead.

Start now free