resp-benchmark 0.2.0__cp313-cp313t-manylinux_2_17_armv7l.manylinux2014_armv7l.whl

resp_benchmark/__init__.py

@@ -0,0 +1,3 @@
+from .wrapper import Benchmark, Result
+
+__all__ = ["Benchmark", "Result"]

resp_benchmark/cli.py

@@ -0,0 +1,44 @@
+import argparse
+from importlib.metadata import version
+
+from resp_benchmark.wrapper import Benchmark
+
+
+def parse_args():
+    parser = argparse.ArgumentParser(
+        description="RESP Benchmark Tool",
+        add_help=False,
+    )
+
+    parser.add_argument("-h", metavar="host", default="127.0.0.1", help="Server hostname (default 127.0.0.1)")
+    parser.add_argument("-p", metavar="port", type=int, default=6379, help="Server port (default 6379)")
+    parser.add_argument("-u", metavar="username", type=str, default="", help="Used to send ACL style \"AUTH username pass\". Needs -a.")
+    parser.add_argument("-a", metavar="password", type=str, default="", help="Password for Redis Auth")
+    parser.add_argument("-c", metavar="clients", type=int, default=0, help="Number of parallel connections (0 for auto, default: 0)")
+    parser.add_argument("--cores", type=str, default=f"", help="Comma-separated list of CPU cores to use (default all)")
+    parser.add_argument("--cluster", action="store_true", help="Use cluster mode (default false)")
+    parser.add_argument("-n", metavar="requests", type=int, default=0, help="Total number of requests (default 0), 0 for unlimited.")
+    parser.add_argument("-t", metavar="target", type=int, default=0, help="Target number of requests per second, 0 for unlimited, recommended to be multiple of 100.")
+    parser.add_argument("-s", metavar="seconds", type=int, default=0, help="Total time in seconds (default 0), 0 for unlimited.")
+    parser.add_argument("-P", metavar="pipeline", type=int, default=1, help="Pipeline <numreq> requests. Default 1 (no pipeline).")
+    # parser.add_argument("--tls", action="store_true", help="Use TLS for connection (default false)")
+    parser.add_argument("--load", action="store_true", help="Only load data to Redis, no benchmark.")
+    parser.add_argument('-v', '--version', action='version', version=version('resp_benchmark'))
+    parser.add_argument("--help", action="help", help="Output this help and exit.")
+    parser.add_argument("command", type=str, default="SET {key uniform 100000} {value 64}", nargs="?", help="The Redis command to benchmark (default SET {key uniform 100000} {value 64})")
+
+    args = parser.parse_args()
+    return args
+
+
+def main():
+    args = parse_args()
+    bm = Benchmark(host=args.h, port=args.p, username=args.u, password=args.a, cluster=args.cluster, cores=args.cores, timeout=30)
+    if args.load:
+        bm.load_data(command=args.command, connections=args.c, pipeline=args.P, count=args.n, target=args.t)
+    else:
+        bm.bench(command=args.command, connections=args.c, pipeline=args.P, count=args.n, target=args.t, seconds=args.s)
+
+
+if __name__ == "__main__":
+    main()

resp_benchmark/cores.py

@@ -0,0 +1,24 @@
+import sys
+from itertools import chain
+from typing import List
+import multiprocessing
+
+
+def parse_range_list(rl):
+    def parse_range(r):
+        if len(r) == 0:
+            return []
+        parts = r.split("-")
+        if len(parts) > 2:
+            raise ValueError("Invalid range: {}".format(r))
+        return range(int(parts[0]), int(parts[-1]) + 1)
+
+    return sorted(set(chain.from_iterable(map(parse_range, rl.split(",")))))
+
+
+def parse_cores_string(cores) -> List[int]:
+    try:
+        return parse_range_list(cores)
+    except ValueError:
+        print(f"Invalid cores range: {cores}.")
+        sys.exit(1)

resp_benchmark/wrapper.py

@@ -0,0 +1,158 @@
+import multiprocessing
+from dataclasses import dataclass
+from typing import List
+
+import pydantic
+import redis
+
+from .cores import parse_cores_string
+
+
+@dataclass
+class Result:
+    """
+    Represents the overall result of a benchmark.
+
+    Attributes:
+        qps (float): Average queries per second.
+        avg_latency_ms (float): Average latency in milliseconds.
+        p99_latency_ms (float): 99th percentile latency in milliseconds.
+        connections (int): The number of parallel connections.
+    """
+    qps: float
+    avg_latency_ms: float
+    p99_latency_ms: float
+    connections: int
+
+
+class Benchmark:
+    """
+    A class to perform and manage benchmark tests on a Redis server.
+
+    Attributes:
+        host (str): The host address of the Redis server.
+        port (int): The port number of the Redis server.
+        username (str): The username for authentication.
+        password (str): The password for authentication.
+        cluster (bool): Whether to connect to a Redis cluster.
+        tls (bool): Whether to use TLS for the connection.
+        timeout (int): Timeout for the connection in seconds.
+        cores (str): Comma-separated list of CPU cores to use.
+    """
+
+    @pydantic.validate_call
+    def __init__(
+            self,
+            host: str = "127.0.0.1",
+            port: int = 6379,
+            username: str = "",
+            password: str = "",
+            cluster: bool = False,
+            # tls: bool = False,
+            timeout: int = 30,
+            cores: str = "",
+    ):
+        self.host = host
+        self.port = port
+        self.username = username
+        self.password = password
+        self.cluster = cluster
+        # self.tls = tls
+        self.timeout = timeout
+        if cores == "":
+            cores = f"0-{multiprocessing.cpu_count() - 1}"
+        self.cores = parse_cores_string(cores)
+
+    def bench(
+            self,
+            command: str,
+            connections: int = 0,
+            pipeline: int = 1,
+            count: int = 0,
+            target: int = 0,
+            seconds: int = 0,
+            quiet: bool = False,
+    ) -> Result:
+        """
+        Runs a benchmark test with the specified parameters.
+
+        Args:
+            command (str): The Redis command to benchmark.
+            connections (int): The number of parallel connections.
+            pipeline (int): The number of commands to pipeline.
+            count (int): The total number of requests to make.
+            target(int): The number of requests to send per second.
+            seconds (int): The duration of the test in seconds.
+            quiet: (bool): Whether to suppress output.
+        Returns:
+            Result: The results of the benchmark test.
+        """
+        from . import _resp_benchmark_rust_lib
+        ret = _resp_benchmark_rust_lib.benchmark(
+            host=self.host,
+            port=self.port,
+            username=self.username,
+            password=self.password,
+            cluster=self.cluster,
+            tls=False,  # TODO: Implement TLS support
+            timeout=self.timeout,
+            cores=self.cores,
+
+            command=command,
+            connections=connections,
+            pipeline=pipeline,
+            count=count,
+            target=target,
+            seconds=seconds,
+            load=False,
+            quiet=quiet,
+        )
+        result = Result(
+            qps=ret.qps,
+            avg_latency_ms=ret.avg_latency_ms,
+            p99_latency_ms=ret.p99_latency_ms,
+            connections=ret.connections
+        )
+
+        return result
+
+    def load_data(self, command: str, count: int, target: int = 0, connections: int = 128, pipeline: int = 10, quiet: bool = False):
+        """
+        Load data into the Redis server using the specified command.
+
+        Args:
+            command (str): The Redis command to use for loading data.
+            count (int): The total number of requests to make.
+            target(int): The number of requests to send per second.
+            connections (int): The number of parallel connections.
+            pipeline (int): The number of commands to pipeline
+            quiet: (bool): Whether to suppress output.
+        """
+
+        from . import _resp_benchmark_rust_lib
+        _resp_benchmark_rust_lib.benchmark(
+            host=self.host,
+            port=self.port,
+            username=self.username,
+            password=self.password,
+            cluster=self.cluster,
+            tls=False,
+            timeout=self.timeout,
+            cores=self.cores,
+
+            command=command,
+            connections=connections,
+            pipeline=pipeline,
+            count=count,
+            target=target,
+            seconds=0,
+            load=True,
+            quiet=quiet,
+        )
+
+    def flushall(self):
+        """
+        Clears all data from all Redis databases.
+        """
+        r = redis.Redis(host=self.host, port=self.port, username=self.username, password=self.password)
+        r.flushall()

resp_benchmark-0.2.0.dist-info/METADATA

@@ -0,0 +1,386 @@
+Metadata-Version: 2.4
+Name: resp-benchmark
+Version: 0.2.0
+Classifier: Programming Language :: Rust
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Dist: pydantic
+Requires-Dist: redis
+License-File: LICENSE
+Summary: resp-benchmark is a benchmark tool for testing databases that support the RESP protocol, such as Redis, Valkey, and Tair.
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+
+# resp-benchmark
+
+[![Python - Version](https://img.shields.io/badge/python-%3E%3D3.8-brightgreen)](https://www.python.org/doc/versions/)
+[![PyPI - Version](https://img.shields.io/pypi/v/resp-benchmark?color=%231772b4)](https://pypi.org/project/resp-benchmark/)
+[![PyPI - Downloads](https://img.shields.io/pypi/dw/resp-benchmark?color=%231ba784)](https://pypi.org/project/resp-benchmark/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/tair-opensource/resp-benchmark/blob/main/LICENSE)
+
+[English](README_en.md) | 中文
+
+一个基于 Rust 构建的 RESP (Redis 序列化协议) 数据库基准测试工具，提供 Python 绑定。用于测试 Redis、Valkey、Tair 等 RESP 兼容数据库的性能。
+
+## 主要功能
+
+- 支持自定义命令模板和占位符
+- 多线程并发测试
+- 支持连接池和管道操作
+- 支持 Redis 集群模式
+- 提供 CLI 工具和 Python 库接口
+- 内置 QPS 限流控制
+
+## 安装
+
+需要 Python 3.9 或更高版本。
+
+```bash
+pip install resp-benchmark
+```
+
+## 快速开始
+
+### 命令行使用
+
+```bash
+# 基础基准测试
+resp-benchmark -s 10 "SET {key uniform 100000} {value 64}"
+
+# 加载数据然后测试
+resp-benchmark --load -n 1000000 "SET {key sequence 100000} {value 64}"
+resp-benchmark -s 10 "GET {key uniform 100000}"
+
+# 自定义连接数和管道
+resp-benchmark -c 128 -P 10 -s 30 "SET {key uniform 1000000} {value 128}"
+```
+
+### Python 库使用
+
+```python
+from resp_benchmark import Benchmark
+
+# 初始化基准测试
+bm = Benchmark(host="127.0.0.1", port=6379)
+
+# 加载测试数据
+bm.load_data(
+    command="SET {key sequence 1000000} {value 64}", 
+    count=1000000, 
+    connections=128
+)
+
+# 运行基准测试
+result = bm.bench(
+    command="GET {key uniform 1000000}", 
+    seconds=30, 
+    connections=64
+)
+
+print(f"QPS: {result.qps}")
+print(f"平均延迟: {result.avg_latency_ms}ms")
+print(f"P99 延迟: {result.p99_latency_ms}ms")
+```
+
+## 命令语法
+
+resp-benchmark 使用强大的占位符系统来生成多样化和真实的测试数据：
+
+### 键占位符
+
+- **`{key uniform N}`**: 从 0 到 N-1 的随机键
+  - 示例: `{key uniform 100000}` → `key_0000099999`
+  
+- **`{key sequence N}`**: 从 0 到 N-1 的顺序键（适用于加载数据）
+  - 示例: `{key sequence 100000}` → `key_0000000000`, `key_0000000001`, ...
+  
+- **`{key zipfian N}`**: Zipfian 分布键（模拟真实世界的访问模式）
+  - 示例: `{key zipfian 100000}` → 遵循指数为 1.03 的 Zipfian 分布
+
+### 值占位符
+
+- **`{value N}`**: N 字节的随机字符串
+  - 示例: `{value 64}` → `a8x9mK2p...` (64 字节)
+  
+- **`{rand N}`**: 0 到 N-1 的随机数
+  - 示例: `{rand 1000}` → `742`
+  
+- **`{range N W}`**: 范围 N 内相差 W 的两个数字
+  - 示例: `{range 100 10}` → `45 55`
+
+### 命令示例
+
+```bash
+# 字符串操作
+SET {key uniform 1000000} {value 64}
+GET {key uniform 1000000}
+INCR {key uniform 100000}
+
+# 列表操作
+LPUSH {key uniform 1000} {value 64}
+LINDEX {key uniform 1000} {rand 100}
+
+# 集合操作
+SADD {key uniform 1000} {value 64}
+SISMEMBER {key uniform 1000} {value 64}
+
+# 有序集合操作
+ZADD {key uniform 1000} {rand 1000} {value 64}
+ZRANGEBYSCORE {key uniform 1000} {range 1000 100}
+
+# 哈希操作
+HSET {key uniform 1000} {key uniform 100} {value 64}
+HGET {key uniform 1000} {key uniform 100}
+```
+
+## 命令行选项
+
+| 选项 | 描述 | 默认值 |
+|------|------|--------|
+| `-h` | 服务器主机名 | 127.0.0.1 |
+| `-p` | 服务器端口 | 6379 |
+| `-u` | 认证用户名 | "" |
+| `-a` | 认证密码 | "" |
+| `-c` | 连接数（0 为自动） | 0 |
+| `-n` | 总请求数（0 为无限） | 0 |
+| `-s` | 持续时间（秒）（0 为无限） | 0 |
+| `-t` | 目标 QPS（0 为无限） | 0 |
+| `-P` | 管道深度 | 1 |
+| `--cores` | 使用的 CPU 核心（逗号分隔） | 全部 |
+| `--cluster` | 启用集群模式 | false |
+| `--load` | 仅加载数据，不进行基准测试 | false |
+
+## 高级特性
+
+### 连接自动扩展
+
+当指定 `-c 0` 时，resp-benchmark 根据系统资源和目标 QPS 自动确定最优连接数。
+
+### CPU 核心绑定
+
+将基准测试线程绑定到特定 CPU 核心以获得一致的性能：
+
+```bash
+# 使用核心 0, 1, 2, 3
+resp-benchmark --cores 0,1,2,3 -s 10 "SET {key uniform 100000} {value 64}"
+```
+
+### 速率限制
+
+控制请求速率进行渐进式负载测试：
+
+```bash
+# 目标 10,000 QPS
+resp-benchmark -t 10000 -s 30 "SET {key uniform 100000} {value 64}"
+```
+
+### 管道操作
+
+使用管道进行批量操作：
+
+```bash
+# 每个连接管道 10 个请求
+resp-benchmark -P 10 -c 128 -s 30 "SET {key uniform 100000} {value 64}"
+```
+
+### 集群模式
+
+使用自动槽位分布测试 Redis 集群：
+
+```bash
+resp-benchmark --cluster -h cluster-endpoint -p 7000 -s 30 "SET {key uniform 100000} {value 64}"
+```
+
+## 性能优化
+
+### 最佳实践
+
+1. **预加载数据**: 使用 `--load` 在基准测试前填充测试数据
+2. **适当的连接数**: 从 `-c 128` 开始，根据结果调整
+3. **键分布**: 读取使用 `uniform`，写入使用 `sequence`
+4. **明智使用管道**: 批量操作使用 `-P 10`，延迟测试使用 `-P 1`
+5. **清洁状态**: 测试之间清除数据以避免干扰
+
+### 示例工作流程
+
+```bash
+# 1. 清除现有数据
+redis-cli FLUSHALL
+
+# 2. 加载测试数据
+resp-benchmark --load -c 256 -P 10 -n 1000000 "SET {key sequence 100000} {value 64}"
+
+# 3. 使用不同模式进行基准测试
+resp-benchmark -c 128 -s 30 "GET {key uniform 100000}"    # 随机访问
+resp-benchmark -c 128 -s 30 "GET {key zipfian 100000}"    # 真实访问模式
+```
+
+## 完整示例
+
+### 字符串操作
+
+```bash
+# 基本 SET/GET
+resp-benchmark --load -n 1000000 "SET {key sequence 100000} {value 64}"
+resp-benchmark -s 10 "GET {key uniform 100000}"
+
+# 大值
+resp-benchmark -s 10 "SET {key uniform 10000} {value 1024}"
+
+# 递增操作
+resp-benchmark -s 10 "INCR {key uniform 10000}"
+```
+
+### 列表操作
+
+```bash
+# 构建列表
+resp-benchmark --load -n 1000000 "LPUSH {key sequence 1000} {value 64}"
+
+# 随机访问
+resp-benchmark -s 10 "LINDEX {key uniform 1000} {rand 1000}"
+
+# 范围操作
+resp-benchmark -s 10 "LRANGE {key uniform 1000} {range 1000 10}"
+```
+
+### 集合操作
+
+```bash
+# 填充集合
+resp-benchmark --load -n 1000000 "SADD {key sequence 1000} {key sequence 1000}"
+
+# 测试成员关系
+resp-benchmark -s 10 "SISMEMBER {key uniform 1000} {key uniform 1000}"
+```
+
+### 有序集合操作
+
+```bash
+# 添加带分数的成员
+resp-benchmark --load -n 1000000 "ZADD {key sequence 1000} {rand 10000} {key sequence 1000}"
+
+# 分数查询
+resp-benchmark -s 10 "ZSCORE {key uniform 1000} {key uniform 1000}"
+
+# 范围查询
+resp-benchmark -s 10 "ZRANGEBYSCORE {key uniform 1000} {range 10000 100}"
+```
+
+### 哈希操作
+
+```bash
+# 填充哈希
+resp-benchmark --load -n 1000000 "HSET {key sequence 1000} {key sequence 100} {value 64}"
+
+# 字段访问
+resp-benchmark -s 10 "HGET {key uniform 1000} {key uniform 100}"
+```
+
+### Lua 脚本
+
+```bash
+# 加载脚本
+redis-cli SCRIPT LOAD "return redis.call('SET', KEYS[1], ARGV[1])"
+
+# 基准测试脚本执行
+resp-benchmark -s 10 "EVALSHA d8f2fad9f8e86a53d2a6ebd960b33c4972cacc37 1 {key uniform 100000} {value 64}"
+```
+
+## Python 库 API
+
+### 初始化
+
+```python
+from resp_benchmark import Benchmark
+
+# 基本连接
+bm = Benchmark(host="127.0.0.1", port=6379)
+
+# 带认证
+bm = Benchmark(
+    host="redis.example.com",
+    port=6379,
+    username="user",
+    password="pass"
+)
+
+# 集群模式
+bm = Benchmark(
+    host="cluster-endpoint",
+    port=7000,
+    cluster=True
+)
+
+# 自定义配置
+bm = Benchmark(
+    host="127.0.0.1",
+    port=6379,
+    cores="0,1,2,3",  # 使用特定核心
+    timeout=30        # 连接超时
+)
+```
+
+### 加载数据
+
+```python
+# 顺序加载（推荐）
+bm.load_data(
+    command="SET {key sequence 1000000} {value 64}",
+    count=1000000,
+    connections=128,
+    pipeline=10
+)
+
+# 带速率限制
+bm.load_data(
+    command="SET {key sequence 1000000} {value 64}",
+    count=1000000,
+    connections=128,
+    target=50000  # 50k QPS
+)
+```
+
+### 基准测试
+
+```python
+# 基于时间的基准测试
+result = bm.bench(
+    command="GET {key uniform 1000000}",
+    seconds=30,
+    connections=64
+)
+
+# 基于计数的基准测试
+result = bm.bench(
+    command="GET {key uniform 1000000}",
+    count=1000000,
+    connections=64
+)
+
+# 带管道
+result = bm.bench(
+    command="SET {key uniform 1000000} {value 64}",
+    seconds=30,
+    connections=64,
+    pipeline=10
+)
+```
+
+### 结果分析
+
+```python
+# 访问基准测试结果
+print(f"QPS: {result.qps:.2f}")
+print(f"平均延迟: {result.avg_latency_ms:.2f}ms")
+print(f"P99 延迟: {result.p99_latency_ms:.2f}ms")
+print(f"使用的连接数: {result.connections}")
+```
+
+## 贡献
+
+欢迎贡献！请随时提交拉取请求或开启议题。
+
+## 许可证
+
+该项目基于 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件。

resp_benchmark-0.2.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+resp_benchmark-0.2.0.dist-info/METADATA,sha256=BxS1x3Bjr63N3XyEZDirnxWF1GQ6v_QfT7ab-mScQo4,9432
+resp_benchmark-0.2.0.dist-info/WHEEL,sha256=Rwpoa6Y-CxeIKCamzdzdYcnjRYuJsvIAt4kqFhrruZI,130
+resp_benchmark-0.2.0.dist-info/entry_points.txt,sha256=q1llaLwyhHn2jvpR28wBbila30DyZ1B5_4ackdlZ2R4,57
+resp_benchmark-0.2.0.dist-info/licenses/LICENSE,sha256=Kj-yFXYfT2SMHVx80nmX0ta2SPNqCQAq1_fwhkPqJrw,1072
+resp_benchmark/__init__.py,sha256=5DYLIsYOU6wd-xMX2sJF1IMr3vktktFIBE6CyxUc3A4,74
+resp_benchmark/_resp_benchmark_rust_lib.cpython-313t-arm-linux-gnueabihf.so,sha256=9aUukeFoGCzTXRSkUhzlPEc1Kq-y_zvCLWLiEcvRbOY,2957660
+resp_benchmark/cli.py,sha256=MH7MfDBBzEVCfTuq_K9vd_iKGVIs4LW4pk_U1tZpGoM,2695
+resp_benchmark/cores.py,sha256=bSEaHXJYo6spGIK_j-beTz8qbun3D7bgYrYxjUaMuDw,619
+resp_benchmark/wrapper.py,sha256=6S1YChLkEc65pGY5SxGnjO5biwVpZ8gHMGVt8tHeXtU,4989
+resp_benchmark-0.2.0.dist-info/RECORD,,

resp_benchmark-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: maturin (1.9.1)
+Root-Is-Purelib: false
+Tag: cp313-cp313t-manylinux_2_17_armv7l.manylinux2014_armv7l

resp_benchmark-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+resp-benchmark=resp_benchmark.cli:main

resp_benchmark-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 tair-opensource
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.