tcpulse

tcpulse is a concurrent TCP/UDP load generator written in Go that provides fine-grained, flow-level control over connection establishment and data transfer.

Table of Contents

• What is tcpulse?
• Why use tcpulse?
• How it works
  • Persistent Connections
  • Ephemeral Connections
  • Key Features
• Installation
  • Pre-built Binaries
  • Build from Source
  • Verify Installation
• Usage
• Examples
  • Commands
  • Reports
• Use Cases
  • eBPF Kernel Tracer Overhead Measurement
  • L4 Load Balancer Distribution Verification
  • Firewall/Conntrack Table Exhaustion Testing
  • UDP Packet Rate Tolerance (Real-time Delivery Simulation)
  • Thread Pinning/IRQ Affinity Tuning Effect Measurement
  • Multi-target Infrastructure Validation
  • Usage Guidelines
• Comparison with Other Tools
  • Bandwidth Measurement Tools
  • tcpulse's Unique Positioning
  • tcpulse's Limitations
• License

What is tcpulse?

tcpulse is a specialized tool designed to generate load on network connections and analyze the performance characteristics of network traffic. It operates in two primary modes:

• Server mode (-s/--server): Acts as an echo server that accepts TCP/UDP connections and echoes back received data
• Client mode (-c/--client): Generates configurable load against target servers and measures connection performance metrics

Why use tcpulse?

Network performance testing is crucial for:

• Load testing: Validate server capacity and identify bottlenecks before production deployment
• Connection establishment performance: Measure how quickly new connections can be established (ephemeral mode)
• Sustained connection performance: Test throughput and latency of long-lived connections (persistent mode)
• Protocol comparison: Compare TCP vs UDP performance characteristics
• Infrastructure validation: Verify network infrastructure can handle expected traffic patterns
• Performance regression testing: Detect performance degradations in network services

How it works

tcpulse provides two distinct connection patterns to simulate real-world usage:

Persistent Connections

Maintains long-lived connections and sends multiple requests per connection. This simulates applications like web services with connection pooling or persistent database connections.

Ephemeral Connections

Creates new connections for each request, immediately closing them afterward. This simulates scenarios like HTTP/1.0 or testing connection establishment overhead.

Key Features

• Real-time metrics: Latency percentiles (90th, 95th, 99th), throughput, and connection counts
• Rate limiting: Control connection establishment rate to simulate realistic load patterns
• Multi-target support: Test multiple endpoints simultaneously and aggregate results
• Protocol support: Both TCP and UDP with optimized implementations
• Platform optimizations: Leverages Linux-specific optimizations (TCP_FASTOPEN, SO_REUSEPORT) when available
• JSON Lines output: Machine-readable output format for integration with monitoring and analysis tools

Installation

Pre-built Binaries

Download the latest pre-built binaries from the GitHub Releases page.

Build from Source

Requirements:

• Go 1.22+ (see go.mod for exact version requirements)
• Git

# Clone the repository
git clone https://github.com/yuuki/tcpulse.git
cd tcpulse

# Build using Make
make build

# Or build directly with Go
go build -o tcpulse .

# Install to $GOPATH/bin
go install .

Verify Installation

tcpulse --help

Usage

$ tcpulse --help
Usage: tcpulse [OPTIONS] <addresses...>

tcpulse is a concurrent TCP/UDP load generator that provides fine-grained, flow-level control

Modes:
  -c, --client    Run in client mode (connect to servers)
  -s, --server    Run in server mode (accept connections)

Options:
      --addrs-file                 [client mode] enable to pass a file including a pair of addresses and ports to an argument
  -c, --client                     run in client mode
      --connections int32          [client mode] Number of concurrent connections to keep (only for 'persistent') (default 10)
      --duration duration          [client mode] measurement period (default 10s)
      --enable-pprof               [client mode] enable pprof profiling
      --flavor string              [client mode] connect behavior type 'persistent' or 'ephemeral' (default "persistent")
  -h, --help                       show help information
      --interval duration          [client mode] interval for printing stats (default 5s)
      --jsonlines                  [client mode] output results in JSON Lines format
      --listen-addrs-file string   [server mode] enable to pass a file including a pair of addresses and ports
      --merge-results-each-host    [client mode] merge results of each host (with --show-only-results)
      --message-bytes int32        [client mode] TCP/UDP message size (bytes) (default 64)
      --pprof-addr string          [client mode] pprof listening address:port (default "localhost:6060")
      --proto string               [client mode] protocol (tcp or udp) (default "tcp")
      --protocol string            [server mode] listening protocol ('tcp' or 'udp') (default "all")
      --rate int32                 [client mode] Message throughput per connection (/s) (for 'persistent' and UDP) or new connections throughput (/s) (for 'ephemeral'). Total messages (CNT) = rate * duration * connections (for 'persistent') or rate * duration (for 'ephemeral') (default 100)
  -s, --server                     run in server mode
      --show-only-results          [client mode] print only results of measurement stats
      --version                    show version information

Output Format (Client Mode):
  CNT: Total number of messages/requests sent (not connections)
  For persistent mode: CNT = rate × duration × connections
  For ephemeral mode:  CNT = rate × duration

Examples:
  tcpulse -s                          # Start server on default port 9100
  tcpulse -s 0.0.0.0:8080             # Start server on port 8080
  tcpulse -c localhost:9100           # Connect to server as client
  tcpulse -c --connections 50 host:port # Connect with 50 connections
  tcpulse -c --connections 1 --rate 1 --duration 1s host:port # Send exactly 1 message

Examples

Commands

Run as a server.

$ tcpulse -s 127.0.0.1:9100

Run as a client to put a load on the server.

$ tcpulse -c --flavor ephemeral --rate 1000 --duration 15s 127.0.0.1:9100

$ tcpulse -c --flavor persistent --connections 1000 --duration 15s 127.0.0.1:9100

Run as a UDP client.

$ tcpulse -c --proto udp --rate 1000 --duration 15s 127.0.0.1:9100

Output results in JSON Lines format for integration with monitoring tools.

$ tcpulse -c --jsonlines --rate 1000 --duration 10s 127.0.0.1:9100
{"peer":"127.0.0.1:9100","count":9998,"latency_max_us":2156,"latency_min_us":145,"latency_mean_us":234,"latency_90p_us":289,"latency_95p_us":321,"latency_99p_us":456,"rate_per_sec":999.8,"timestamp":"2025-01-07T10:30:00Z"}

Reports

Standard Output Format

The standard output format includes the following columns:

• CNT: Total number of messages/requests sent (not connections)
• For persistent mode: CNT = rate × duration × connections
• For ephemeral mode: CNT = rate × duration

$ tcpulse -c --proto tcp --flavor ephemeral --rate 1000 --duration 15s 10.0.150.2:9200 10.0.150.2:9300
PEER                 CNT        LAT_MAX(µs)     LAT_MIN(µs)     LAT_MEAN(µs)    LAT_90p(µs)     LAT_95p(µs)     LAT_99p(µs)     RATE(/s)
10.0.150.2:9200      4996       4108            212             367             446             492             773             999.00
10.0.150.2:9300      4999       10294           219             389             435             470             1595            999.40
10.0.150.2:9200      4998       3884            209             369             448             489             950             999.40
10.0.150.2:9300      4998       3057            220             356             426             473             1030            999.40
10.0.150.2:9200      4802       22838           219             784             1030            2692            10264           0.00
10.0.150.2:9300      4808       18730           219             801             1033            2382            13412           0.00
--- A result during total execution time ---
10.0.150.2:9200      14799      13736           223             530             501             953             5989            996.00
10.0.150.2:9300      14809      18023           212             542             492             1110            5849            996.47

JSON Lines Output Format

$ tcpulse -c --jsonlines --proto tcp --flavor ephemeral