{"id":31630945,"url":"https://github.com/yuuki/tcpulse","last_synced_at":"2025-10-06T22:34:18.095Z","repository":{"id":50753246,"uuid":"328703454","full_name":"yuuki/tcpulse","owner":"yuuki","description":"A TCP/UDP load generator that provides fine-grained, flow-level control in Go.","archived":false,"fork":false,"pushed_at":"2025-06-24T13:51:04.000Z","size":5963,"stargazers_count":144,"open_issues_count":1,"forks_count":5,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-06-24T14:46:47.670Z","etag":null,"topics":["benchmark","go","golang","load-generator","load-testing","network","performance-testing","tcp","udp"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yuuki.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-01-11T15:13:00.000Z","updated_at":"2025-06-24T13:50:57.000Z","dependencies_parsed_at":"2025-06-10T20:52:59.348Z","dependency_job_id":"74492c36-a293-4b63-8c7a-074f27ca01b2","html_url":"https://github.com/yuuki/tcpulse","commit_stats":null,"previous_names":["yuuki/tcpulse","yuuki/connperf"],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/yuuki/tcpulse","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yuuki%2Ftcpulse","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yuuki%2Ftcpulse/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yuuki%2Ftcpulse/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yuuki%2Ftcpulse/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yuuki","download_url":"https://codeload.github.com/yuuki/tcpulse/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yuuki%2Ftcpulse/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278692013,"owners_count":26029380,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-06T02:00:05.630Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["benchmark","go","golang","load-generator","load-testing","network","performance-testing","tcp","udp"],"created_at":"2025-10-06T22:34:12.401Z","updated_at":"2025-10-06T22:34:18.085Z","avatar_url":"https://github.com/yuuki.png","language":"Go","readme":"# tcpulse\n\n[![Test](https://github.com/yuuki/tcpulse/actions/workflows/test.yml/badge.svg)](https://github.com/yuuki/tcpulse/actions/workflows/test.yml)\n[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/yuuki/tcpulse)\n\ntcpulse is a concurrent TCP/UDP load generator written in Go that provides fine-grained, flow-level control over connection establishment and data transfer.\n\n## Table of Contents\n\n- [What is tcpulse?](#what-is-tcpulse)\n- [Why use tcpulse?](#why-use-tcpulse)\n- [How it works](#how-it-works)\n  - [Persistent Connections](#persistent-connections)\n  - [Ephemeral Connections](#ephemeral-connections)\n  - [Key Features](#key-features)\n- [Installation](#installation)\n  - [Pre-built Binaries](#pre-built-binaries)\n  - [Build from Source](#build-from-source)\n  - [Verify Installation](#verify-installation)\n- [Usage](#usage)\n- [Examples](#examples)\n  - [Commands](#commands)\n  - [Reports](#reports)\n- [Use Cases](#use-cases)\n  - [eBPF Kernel Tracer Overhead Measurement](#ebpf-kernel-tracer-overhead-measurement)\n  - [L4 Load Balancer Distribution Verification](#l4-load-balancer-distribution-verification)\n  - [Firewall/Conntrack Table Exhaustion Testing](#firewallconntrack-table-exhaustion-testing)\n  - [UDP Packet Rate Tolerance (Real-time Delivery Simulation)](#udp-packet-rate-tolerance-real-time-delivery-simulation)\n  - [Thread Pinning/IRQ Affinity Tuning Effect Measurement](#thread-pinningirq-affinity-tuning-effect-measurement)\n  - [Multi-target Infrastructure Validation](#multi-target-infrastructure-validation)\n  - [Usage Guidelines](#usage-guidelines)\n- [Comparison with Other Tools](#comparison-with-other-tools)\n  - [Bandwidth Measurement Tools](#bandwidth-measurement-tools)\n  - [tcpulse's Unique Positioning](#tcpulses-unique-positioning)\n  - [tcpulse's Limitations](#tcpulses-limitations)\n- [License](#license)\n\n## What is tcpulse?\n\ntcpulse 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:\n\n- **Server mode (`-s/--server`)**: Acts as an echo server that accepts TCP/UDP connections and echoes back received data\n- **Client mode (`-c/--client`)**: Generates configurable load against target servers and measures connection performance metrics\n\n## Why use tcpulse?\n\nNetwork performance testing is crucial for:\n\n- **Load testing**: Validate server capacity and identify bottlenecks before production deployment\n- **Connection establishment performance**: Measure how quickly new connections can be established (ephemeral mode)\n- **Sustained connection performance**: Test throughput and latency of long-lived connections (persistent mode)\n- **Protocol comparison**: Compare TCP vs UDP performance characteristics\n- **Infrastructure validation**: Verify network infrastructure can handle expected traffic patterns\n- **Performance regression testing**: Detect performance degradations in network services\n\n## How it works\n\ntcpulse provides two distinct connection patterns to simulate real-world usage:\n\n### Persistent Connections\nMaintains long-lived connections and sends multiple requests per connection. This simulates applications like web services with connection pooling or persistent database connections.\n\n### Ephemeral Connections\nCreates new connections for each request, immediately closing them afterward. This simulates scenarios like HTTP/1.0 or testing connection establishment overhead.\n\n### Key Features\n\n- **Real-time metrics**: Latency percentiles (90th, 95th, 99th), throughput, and connection counts\n- **Rate limiting**: Control connection establishment rate to simulate realistic load patterns\n- **Multi-target support**: Test multiple endpoints simultaneously and aggregate results\n- **Protocol support**: Both TCP and UDP with optimized implementations\n- **Platform optimizations**: Leverages Linux-specific optimizations (TCP_FASTOPEN, SO_REUSEPORT) when available\n- **JSON Lines output**: Machine-readable output format for integration with monitoring and analysis tools\n\n## Installation\n\n### Pre-built Binaries\n\nDownload the latest pre-built binaries from the [GitHub Releases](https://github.com/yuuki/tcpulse/releases) page.\n\n### Build from Source\n\nRequirements:\n- Go 1.22+ (see [go.mod](go.mod) for exact version requirements)\n- Git\n\n```bash\n# Clone the repository\ngit clone https://github.com/yuuki/tcpulse.git\ncd tcpulse\n\n# Build using Make\nmake build\n\n# Or build directly with Go\ngo build -o tcpulse .\n\n# Install to $GOPATH/bin\ngo install .\n```\n\n### Verify Installation\n\n```bash\ntcpulse --help\n```\n\n## Usage\n\n```shell-session\n$ tcpulse --help\nUsage: tcpulse [OPTIONS] \u003caddresses...\u003e\n\ntcpulse is a concurrent TCP/UDP load generator that provides fine-grained, flow-level control\n\nModes:\n  -c, --client    Run in client mode (connect to servers)\n  -s, --server    Run in server mode (accept connections)\n\nOptions:\n      --addrs-file                 [client mode] enable to pass a file including a pair of addresses and ports to an argument\n  -c, --client                     run in client mode\n      --connections int32          [client mode] Number of concurrent connections to keep (only for 'persistent') (default 10)\n      --duration duration          [client mode] measurement period (default 10s)\n      --enable-pprof               [client mode] enable pprof profiling\n      --flavor string              [client mode] connect behavior type 'persistent' or 'ephemeral' (default \"persistent\")\n  -h, --help                       show help information\n      --interval duration          [client mode] interval for printing stats (default 5s)\n      --jsonlines                  [client mode] output results in JSON Lines format\n      --listen-addrs-file string   [server mode] enable to pass a file including a pair of addresses and ports\n      --merge-results-each-host    [client mode] merge results of each host (with --show-only-results)\n      --message-bytes int32        [client mode] TCP/UDP message size (bytes) (default 64)\n      --pprof-addr string          [client mode] pprof listening address:port (default \"localhost:6060\")\n      --proto string               [client mode] protocol (tcp or udp) (default \"tcp\")\n      --protocol string            [server mode] listening protocol ('tcp' or 'udp') (default \"all\")\n      --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)\n  -s, --server                     run in server mode\n      --show-only-results          [client mode] print only results of measurement stats\n      --version                    show version information\n\nOutput Format (Client Mode):\n  CNT: Total number of messages/requests sent (not connections)\n  For persistent mode: CNT = rate × duration × connections\n  For ephemeral mode:  CNT = rate × duration\n\nExamples:\n  tcpulse -s                          # Start server on default port 9100\n  tcpulse -s 0.0.0.0:8080             # Start server on port 8080\n  tcpulse -c localhost:9100           # Connect to server as client\n  tcpulse -c --connections 50 host:port # Connect with 50 connections\n  tcpulse -c --connections 1 --rate 1 --duration 1s host:port # Send exactly 1 message\n```\n\n## Examples\n\n### Commands\n\nRun as a server.\n\n```shell-session\n$ tcpulse -s 127.0.0.1:9100\n```\n\nRun as a client to put a load on the server.\n\n```shell-session\n$ tcpulse -c --flavor ephemeral --rate 1000 --duration 15s 127.0.0.1:9100\n```\n\n```shell-session\n$ tcpulse -c --flavor persistent --connections 1000 --duration 15s 127.0.0.1:9100\n```\n\nRun as a UDP client.\n\n```shell-session\n$ tcpulse -c --proto udp --rate 1000 --duration 15s 127.0.0.1:9100\n```\n\nOutput results in JSON Lines format for integration with monitoring tools.\n\n```shell-session\n$ tcpulse -c --jsonlines --rate 1000 --duration 10s 127.0.0.1:9100\n{\"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\"}\n```\n\n### Reports\n\n#### Standard Output Format\n\nThe standard output format includes the following columns:\n- `CNT`: Total number of messages/requests sent (not connections)\n- For persistent mode: CNT = rate × duration × connections  \n- For ephemeral mode: CNT = rate × duration\n\n```shell-session\n$ tcpulse -c --proto tcp --flavor ephemeral --rate 1000 --duration 15s 10.0.150.2:9200 10.0.150.2:9300\nPEER                 CNT        LAT_MAX(µs)     LAT_MIN(µs)     LAT_MEAN(µs)    LAT_90p(µs)     LAT_95p(µs)     LAT_99p(µs)     RATE(/s)\n10.0.150.2:9200      4996       4108            212             367             446             492             773             999.00\n10.0.150.2:9300      4999       10294           219             389             435             470             1595            999.40\n10.0.150.2:9200      4998       3884            209             369             448             489             950             999.40\n10.0.150.2:9300      4998       3057            220             356             426             473             1030            999.40\n10.0.150.2:9200      4802       22838           219             784             1030            2692            10264           0.00\n10.0.150.2:9300      4808       18730           219             801             1033            2382            13412           0.00\n--- A result during total execution time ---\n10.0.150.2:9200      14799      13736           223             530             501             953             5989            996.00\n10.0.150.2:9300      14809      18023           212             542             492             1110            5849            996.47\n```\n\n#### JSON Lines Output Format\n\n```shell-session\n$ tcpulse -c --jsonlines --proto tcp --flavor ephemeral --rate 1000 --duration 15s 10.0.150.2:9200 10.0.150.2:9300\n{\"peer\":\"10.0.150.2:9200\",\"count\":14799,\"latency_max_us\":13736,\"latency_min_us\":223,\"latency_mean_us\":530,\"latency_90p_us\":501,\"latency_95p_us\":953,\"latency_99p_us\":5989,\"rate_per_sec\":996.0,\"timestamp\":\"2025-01-07T10:30:00Z\"}\n{\"peer\":\"10.0.150.2:9300\",\"count\":14809,\"latency_max_us\":18023,\"latency_min_us\":212,\"latency_mean_us\":542,\"latency_90p_us\":492,\"latency_95p_us\":1110,\"latency_99p_us\":5849,\"rate_per_sec\":996.47,\"timestamp\":\"2025-01-07T10:30:00Z\"}\n```\n\nThe JSON Lines format includes the following fields:\n- `peer`: Target server address\n- `count`: Total number of messages/requests sent (CNT in standard output)\n- `latency_max_us`: Maximum latency in microseconds\n- `latency_min_us`: Minimum latency in microseconds\n- `latency_mean_us`: Mean latency in microseconds\n- `latency_90p_us`: 90th percentile latency in microseconds\n- `latency_95p_us`: 95th percentile latency in microseconds\n- `latency_99p_us`: 99th percentile latency in microseconds\n- `rate_per_sec`: Average request rate per second\n- `timestamp`: ISO 8601 timestamp when the measurement was completed\n\n## Use Cases\n\ntcpulse is particularly well-suited for performance validation of network devices and middlewares that relay end-to-end communications. Below are typical experimental scenarios that can be completed with tcpulse alone, which would be difficult to reproduce with iperf/netperf.\n\n### eBPF Kernel Tracer Overhead Measurement\n\nQuantify additional latency in the kernel TCP stack when numerous kprobe/tracepoints are active. Use persistent mode to maintain 10k connections and continuously echo for 1 minute, observing how many microseconds the `p99_latency` increases when eBPF is enabled vs disabled.\n\n```bash\ntcpulse -c --flavor persistent --connections 10000 --duration 60s 10.0.0.2:9100\n```\n\n### L4 Load Balancer Distribution Verification\n\nVerify that an L4 LB can evenly distribute connections across N backends. Generate 10k CPS (connections per second) using ephemeral mode against the L4 LB's VIP (Virtual IP) address, while collecting connection counts on the backend side to calculate standard deviation.\n\n```bash\ntcpulse -c --flavor ephemeral --rate 10000 --duration 30s 10.0.0.2:9100\n```\n\n### Firewall/Conntrack Table Exhaustion Testing\n\nInvestigate the \"new connections per second capacity\" of stateful FW/NAT and behavior when tables are exhausted. Place tcpulse client behind NAT, execute ephemeral mode at 40k CPS for 2 minutes, while simultaneously collecting NAT router memory usage and packet loss statistics.\n\n```bash\ntcpulse -c --flavor ephemeral --rate 40000 --duration 120s 192.0.2.10:9100\n```\n\n### UDP Packet Rate Tolerance (Real-time Delivery Simulation)\n\nVerify that QoS policing and NIC interrupt tuning don't break under VoIP/Gaming-style traffic. Execute UDP at 25k * 2 pps for 10 minutes with 64-byte payload fixed to observe jitter.\n\n```bash\ntcpulse -c --proto udp --rate 25000 --duration 10m --message-bytes 64 198.51.100.5:9100\n```\n\n### Thread Pinning/IRQ Affinity Tuning Effect Measurement\n\nMeasure how throughput and latency change when NIC interrupts are pinned to specific CPU cores. Use persistent 5k connections, measuring continuously for 5 minutes before and after affinity changes.\n\n```bash\ntcpulse -c --flavor persistent --connections 5000 --duration 300s 10.1.1.50:9100\n```\n\n### Multi-target Infrastructure Validation\n\nTest multiple endpoints simultaneously to validate distributed system performance under realistic load patterns:\n\n```bash\n# Test multiple services with different load patterns\ntcpulse -c --flavor ephemeral --rate 5000 --duration 60s \\\n  service1.example.com:9100 \\\n  service2.example.com:9200 \\\n  service3.example.com:9300\n```\n\n### Usage Guidelines\n\n| Requirement | tcpulse | iperf3 / netperf |\n|---|---|---|\n| **Fixed CPS/pps Control** | ✅ | △ (coarse with `-b` only) |\n| **Maintain 10k+ Concurrent Flows** | ✅ (`persistent`) | △ (`-P` limit ~128) |\n| **Multi-target Support** | ✅ (`--addrs-file`) | ❌ |\n| **Automatic Percentile Statistics (p95/p99)** | ✅ | △ (netperf: mean/max only) |\n| **Integrated Control \u0026 Measurement** | ✅ | ✅/○ |\n\n## Comparison with Other Tools\n\nNetwork performance testing and load generation tools serve different purposes. Here's how tcpulse compares to popular alternatives:\n\n### Bandwidth Measurement Tools\n\n**[iperf3](https://iperf.fr/)** is one of the most widely used network performance measurement tools. It supports both TCP and UDP protocols and provides JSON output and multi-stream capabilities. Its primary purpose is **measuring maximum network bandwidth** - answering \"What's the maximum Mbps this network can achieve?\" While UDP mode allows coarse message rate control via the `-b` option, and multi-target testing can be achieved through external script parallelization, the tool is fundamentally designed for 1-to-1 communication.\n\n**[netperf](https://github.com/HewlettPackard/netperf)** is a comprehensive network performance benchmark tool that targets both bulk data transfer and request/response performance. It offers various test types including TCP_STREAM, UDP_STREAM, TCP_RR, and UDP_RR with extensive parameter tuning capabilities. The `*_RR` tests provide microsecond-level latency statistics (min/mean/p90/p99, etc.) as standard output, emphasizing not just throughput but also latency measurement. It excels in network equipment performance evaluation and comparing different network configurations.\n\n**[nuttcp](https://nuttcp.net/)** specializes in high-speed UDP testing with features like burst mode and CPU core selection, making it suitable for performance measurement of networks exceeding 10Gbps.\n\n### tcpulse's Unique Positioning\n\n**tcpulse** is designed to answer \"How does the network or application behave under specified load conditions?\" Specifically:\n\n**Load Pattern Control**: Ephemeral mode precisely controls new connection generation rates, while persistent mode controls concurrent connection counts. This enables analysis like \"CPU usage changes when applying 1000 connections/second load for 30 minutes.\" While iperf3's UDP mode allows coarse control via bitrate specification, precise connection generation rate control for TCP or long-term precise load maintenance is challenging with existing tools.\n\n**Experiment Reproducibility**: Running with the same parameters reproduces identical load patterns, making it effective for comparative experiments under different conditions and problem reproduction.\n\n**Distributed System Support**: Provides multi-server simultaneous load generation capability within a single tool. Existing tools often require external script-based parallel execution.\n\nThese characteristics make tcpulse particularly suitable for **operational validation under realistic load conditions** rather than exploring system performance limits.\n\n### tcpulse's Limitations\n\nHowever, tcpulse has certain limitations:\n\n**Not Suitable for Maximum Throughput Measurement**: For pure bandwidth measurement like \"What's the maximum Gbps this network can achieve?\", iperf3 is more appropriate. tcpulse focuses on load control and isn't optimized for maximum performance exploration.\n\n**Overkill for Health Monitoring**: For simply checking if a server is alive or measuring basic latency, ping or curl is sufficient. tcpulse's multi-functionality can be overly complex for simple tests.\n\n**No High-Layer Protocol Support**: Doesn't directly support L7 protocols like HTTP, HTTP/2, or QUIC. Verifying protocol-specific performance characteristics requires dedicated tools or libraries (e.g. [wrk](https://github.com/wg/wrk), [vegeta](https://github.com/tsenart/vegeta), [hey](https://github.com/rakyll/hey), etc.).\n\n**Limited Network Diagnostic Features**: Detailed packet content analysis or network path problem identification requires separate packet capture tools like [Wireshark](https://www.wireshark.org/) or [tcpdump](https://www.tcpdump.org/).\n\n## License\n\nThis project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyuuki%2Ftcpulse","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyuuki%2Ftcpulse","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyuuki%2Ftcpulse/lists"}