fustor-benchmark 0.2__tar.gz

fustor_benchmark-0.2/PKG-INFO

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: fustor-benchmark
+Version: 0.2
+Summary: Performance benchmarking tool for Fustor platform
+Author-email: Huajin Wang <wanghuajin999@163.com>
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.1.7
+Requires-Dist: requests>=2.31.0
+Requires-Dist: pyyaml>=6.0.1
+Requires-Dist: psutil>=5.9.0
+
+# Fustor 性能基准测试工具 (Benchmark)
+
+该模块是 Fustor 平台的自动化压力测试和性能量化工具。它通过模拟大规模文件系统元数据，量化 Fusion API 相比于操作系统原生文件系统调用的性能优势。
+
+## 核心设计目标
+
+1.  **量化优势**: 对比 Fusion 内存索引与 Linux 原生 `find` 命令在递归元数据检索下的延迟与吞吐量。
+2.  **百万级规模**: 支持生成并同步超过 1,000,000 个文件的元数据。
+3.  **全自动流程**: 自动编排 Registry、Fusion 和 Agent，实现一键式从环境部署到报告生成。
+
+## 目录结构规范与安全
+
+为了保护生产数据免受误删，Benchmark 实施了严格的路径校验：
+
+*   **路径白名单**: 压测主目录（`run-dir`）必须以 **`fustor-benchmark-run`** 结尾。
+*   **结构定义**:
+    *   `{run-dir}/data/`: 存放生成的数百万个模拟文件。
+    *   `{run-dir}/.fustor/`: 存放压测期间的独立配置文件、SQLite 数据库、日志以及最终报告。
+
+## 快速使用
+
+### 1. 数据生成
+构建一个包含 1000 个 UUID 目录，每个目录下 1000 个文件（总计 100 万文件）的测试集：
+```bash
+uv run fustor-benchmark generate fustor-benchmark-run --num-dirs 1000
+```
+
+### 2. 执行压测
+运行全链路同步并执行并发性能对比：
+```bash
+uv run fustor-benchmark run fustor-benchmark-run -d 5 -c 20 -n 100
+```
+*   `-d`: 探测深度。
+*   `-c`: 并发数。
+*   `-n`: 总请求次数。
+
+## 报告与指标
+
+压测完成后，将在 `fustor-benchmark-run/.fustor/` 下生成以下产出：
+
+1.  **`report.html`**: 交互式可视化报表。
+    *   **Latency Distribution**: 展示 Avg, P50, P95, P99 的柱状对比。
+    *   **Latency Percentiles**: 展现延迟分布曲线。
+    *   **Speedup Factor**: 自动计算 Fusion 相比 OS 的加速倍数。
+2.  **`benchmark_results.json`**: 结构化的指标数据，包含所有原始延迟序列。
+
+## 安全保护说明
+
+Benchmark 会在 `run-dir` 下执行 `shutil.rmtree` 操作以清理旧环境。**请务必确保指定的目录不包含任何重要业务数据**。如果尝试在非 `fustor-benchmark-run` 后缀目录下运行，程序将强制退出。

fustor_benchmark-0.2/README.md

@@ -0,0 +1,49 @@
+# Fustor 性能基准测试工具 (Benchmark)
+
+该模块是 Fustor 平台的自动化压力测试和性能量化工具。它通过模拟大规模文件系统元数据，量化 Fusion API 相比于操作系统原生文件系统调用的性能优势。
+
+## 核心设计目标
+
+1.  **量化优势**: 对比 Fusion 内存索引与 Linux 原生 `find` 命令在递归元数据检索下的延迟与吞吐量。
+2.  **百万级规模**: 支持生成并同步超过 1,000,000 个文件的元数据。
+3.  **全自动流程**: 自动编排 Registry、Fusion 和 Agent，实现一键式从环境部署到报告生成。
+
+## 目录结构规范与安全
+
+为了保护生产数据免受误删，Benchmark 实施了严格的路径校验：
+
+*   **路径白名单**: 压测主目录（`run-dir`）必须以 **`fustor-benchmark-run`** 结尾。
+*   **结构定义**:
+    *   `{run-dir}/data/`: 存放生成的数百万个模拟文件。
+    *   `{run-dir}/.fustor/`: 存放压测期间的独立配置文件、SQLite 数据库、日志以及最终报告。
+
+## 快速使用
+
+### 1. 数据生成
+构建一个包含 1000 个 UUID 目录，每个目录下 1000 个文件（总计 100 万文件）的测试集：
+```bash
+uv run fustor-benchmark generate fustor-benchmark-run --num-dirs 1000
+```
+
+### 2. 执行压测
+运行全链路同步并执行并发性能对比：
+```bash
+uv run fustor-benchmark run fustor-benchmark-run -d 5 -c 20 -n 100
+```
+*   `-d`: 探测深度。
+*   `-c`: 并发数。
+*   `-n`: 总请求次数。
+
+## 报告与指标
+
+压测完成后，将在 `fustor-benchmark-run/.fustor/` 下生成以下产出：
+
+1.  **`report.html`**: 交互式可视化报表。
+    *   **Latency Distribution**: 展示 Avg, P50, P95, P99 的柱状对比。
+    *   **Latency Percentiles**: 展现延迟分布曲线。
+    *   **Speedup Factor**: 自动计算 Fusion 相比 OS 的加速倍数。
+2.  **`benchmark_results.json`**: 结构化的指标数据，包含所有原始延迟序列。
+
+## 安全保护说明
+
+Benchmark 会在 `run-dir` 下执行 `shutil.rmtree` 操作以清理旧环境。**请务必确保指定的目录不包含任何重要业务数据**。如果尝试在非 `fustor-benchmark-run` 后缀目录下运行，程序将强制退出。

fustor_benchmark-0.2/pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "fustor-benchmark"
+dynamic = ["version"]
+description = "Performance benchmarking tool for Fustor platform"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "click>=8.1.7",
+    "requests>=2.31.0",
+    "pyyaml>=6.0.1",
+    "psutil>=5.9.0",
+]
+[[project.authors]]
+name = "Huajin Wang"
+email = "wanghuajin999@163.com"
+
+[build-system]
+requires = ["setuptools>=61.0", "setuptools-scm>=8.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools_scm]
+root = ".."
+version_scheme = "post-release"
+local_scheme = "dirty-tag"
+
+[project.scripts]
+fustor-benchmark = "fustor_benchmark.cli:cli"
+
+[tool.setuptools.packages.find]
+where = ["src"]

fustor_benchmark-0.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

fustor_benchmark-0.2/src/fustor_benchmark/cli.py

@@ -0,0 +1,40 @@
+import click
+import os
+from .generator import DataGenerator
+from .runner import BenchmarkRunner
+
+@click.group()
+def cli():
+    """Fustor Benchmark Tool"""
+    pass
+
+@cli.command()
+@click.argument("run-dir", type=click.Path(exists=False))
+@click.option("--num-dirs", default=1000, help="Number of UUID directories")
+@click.option("--num-subdirs", default=4, help="Number of subdirectories per UUID directory")
+@click.option("--files-per-subdir", default=250, help="Files per subdirectory")
+def generate(run_dir, num_dirs, num_subdirs, files_per_subdir):
+    """Generate benchmark dataset"""
+    gen = DataGenerator(os.path.join(run_dir, "data"))
+    gen.generate(num_dirs, num_subdirs, files_per_subdir)
+
+@cli.command()
+@click.argument("run-dir", type=click.Path(exists=True))
+@click.option("--concurrency", "-c", default=20, help="Number of concurrent workers")
+@click.option("--requests", "-n", default=200, help="Total number of requests to run")
+@click.option("--target-depth", "-d", default=5, help="Depth of target directories for benchmarking")
+@click.option("--force-gen", is_flag=True, help="Force regeneration of test data")
+@click.option("--skip-gen", is_flag=True, default=True, help="Skip generation if data exists (default: True)")
+def run(run_dir, concurrency, requests, target_depth, force_gen, skip_gen):
+    """Run the full benchmark suite"""
+    abs_run_dir = os.path.abspath(run_dir)
+    runner = BenchmarkRunner(run_dir=abs_run_dir)
+    # If force_gen is False and skip_gen is True, we treat it as custom_target=True (skip generation)
+    custom_target = skip_gen and not force_gen
+    runner.run(concurrency=concurrency, reqs=requests, target_depth=target_depth, force_gen=force_gen, custom_target=custom_target)
+
+cli.add_command(generate)
+cli.add_command(run)
+
+if __name__ == "__main__":
+    cli()

fustor_benchmark-0.2/src/fustor_benchmark/generator.py

@@ -0,0 +1,62 @@
+import os
+import uuid
+import time
+import shutil
+import click
+from concurrent.futures import ThreadPoolExecutor
+
+class DataGenerator:
+    def __init__(self, base_dir: str):
+        self.base_dir = os.path.abspath(base_dir)
+        self.submit_dir = os.path.join(self.base_dir, "upload/submit")
+
+    def _create_batch(self, args):
+        """
+        Creates subdirectories and files within a specific UUID directory.
+        args: (uuid_path, num_subdirs, files_per_subdir)
+        """
+        uuid_path, num_subdirs, files_per_subdir = args
+        try:
+            for s in range(num_subdirs):
+                sub_path = os.path.join(uuid_path, f"sub_{s}")
+                os.makedirs(sub_path, exist_ok=True)
+                for i in range(files_per_subdir):
+                    # Create empty dummy files
+                    file_path = os.path.join(sub_path, f"data_{i:04d}.dat")
+                    with open(file_path, "w") as f:
+                        pass
+        except Exception as e:
+            print(f"Error generating data in {uuid_path}: {e}")
+
+    def generate(self, num_uuids: int = 1000, num_subdirs: int = 4, files_per_subdir: int = 250):
+        # Safety Check: Only allow operations in directories ending with 'fustor-benchmark-run'
+        # Note: self.base_dir is typically run-dir/data, so we check the parent run-dir
+        run_dir = os.path.dirname(self.base_dir)
+        if not run_dir.endswith("fustor-benchmark-run"):
+            click.echo(click.style(f"FATAL: Operation denied. Target run-dir '{run_dir}' must end with 'fustor-benchmark-run' for safety.", fg="red", bold=True))
+            return
+
+        if os.path.exists(self.base_dir):
+            click.echo(f"Cleaning up old data in {self.base_dir}...")
+            shutil.rmtree(self.base_dir)
+
+        total_files = num_uuids * num_subdirs * files_per_subdir
+        click.echo(f"Generating {total_files:,} files in 1000 UUID directories...")
+        click.echo(f"Structure: {self.submit_dir}/{{c1}}/{{c2}}/{{uuid}}/sub_X/{{250 files}}")
+        
+        tasks = []
+        for _ in range(num_uuids):
+            uid = str(uuid.uuid4())
+            # Target path at depth 5 (relative to base_dir/data):
+            # 1:upload / 2:submit / 3:c1 / 4:c2 / 5:uuid
+            path = os.path.join(self.submit_dir, uid[0], uid[1], uid)
+            tasks.append((path, num_subdirs, files_per_subdir))
+
+        start_gen = time.time()
+        # Using a high worker count for I/O bound file creation
+        with ThreadPoolExecutor(max_workers=os.cpu_count() * 8) as executor:
+            list(executor.map(self._create_batch, tasks))
+        
+        duration = time.time() - start_gen
+        click.echo(f"Generation Complete: {duration:.2f}s (Average: {total_files/duration:.1f} files/sec)")
+        return self.base_dir

fustor_benchmark-0.2/src/fustor_benchmark/runner.py

@@ -0,0 +1,419 @@
+import time
+import subprocess
+import requests
+import click
+import statistics
+import random
+import os
+import json
+from concurrent.futures import ThreadPoolExecutor, ProcessPoolExecutor, as_completed
+from .generator import DataGenerator
+from .services import ServiceManager
+
+def run_find_recursive_metadata_task(args):
+    """
+    Simulates a recursive metadata retrieval: `find <dir> -type f -ls`
+    This matches the recursive nature of Fusion's tree API for a subdirectory.
+    """
+    data_dir, subdir = args
+    target = os.path.join(data_dir, subdir.lstrip('/'))
+    
+    # Recursive search for all descendant files with metadata
+    cmd = ["find", target, "-type", "f", "-ls"]
+        
+    start = time.time()
+    subprocess.run(cmd, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+    return time.time() - start
+
+class BenchmarkRunner:
+    def __init__(self, run_dir):
+        self.run_dir = os.path.abspath(run_dir) # Ensure absolute path
+        # Derived directories
+        self.data_dir = os.path.join(self.run_dir, "data")
+        self.env_dir = os.path.join(self.run_dir, ".fustor")
+        
+        self.services = ServiceManager(self.run_dir) 
+        self.generator = DataGenerator(self.data_dir)
+
+    def _calculate_stats(self, latencies, total_time, count):
+        """Calculate rich statistics from a list of latencies (in seconds)."""
+        if not latencies:
+            return {
+                "qps": 0, "avg": 0, "min": 0, "max": 0, "stddev": 0,
+                "p50": 0, "p95": 0, "p99": 0
+            }
+        
+        # Convert to milliseconds for presentation
+        l_ms = sorted([l * 1000 for l in latencies])
+        qps = count / total_time
+        
+        # Calculate percentiles
+        qs = statistics.quantiles(l_ms, n=100) if len(l_ms) >= 2 else [l_ms[0]] * 100
+        
+        return {
+            "qps": qps,
+            "avg": statistics.mean(l_ms),
+            "min": min(l_ms),
+            "max": max(l_ms),
+            "stddev": statistics.stdev(l_ms) if len(l_ms) >= 2 else 0,
+            "p50": statistics.median(l_ms),
+            "p95": qs[94],
+            "p99": qs[98],
+            "raw": l_ms # Keep raw data for charting
+        }
+
+    def _discover_leaf_targets_via_api(self, api_key: str, depth: int):
+        """Finds directories at the specified depth relative to data_dir using Fusion API."""
+        # Calculate the depth of the data_dir itself (prefix_depth)
+        # e.g., /home/user/data -> ['home', 'user', 'data'] -> depth 3
+        prefix_depth = len(self.data_dir.strip('/').split('/')) if self.data_dir != '/' else 0
+        max_fetch_depth = depth + prefix_depth
+        
+        click.echo(f"Discovering target directories at depth {depth} (prefix: {prefix_depth}, total: {max_fetch_depth}) via Fusion API...")
+        
+        fusion_url = f"http://localhost:{self.services.fusion_port}"
+        headers = {"X-API-Key": api_key}
+        
+        try:
+            # Fetch the tree with exact required depth
+            res = requests.get(
+                f"{fusion_url}/views/fs/tree", 
+                params={"path": "/", "max_depth": max_fetch_depth, "only_path": "true"}, 
+                headers=headers, 
+                timeout=30
+            )
+            if res.status_code != 200:
+                return ["/"]
+            
+            tree_data = res.json()
+            targets = []
+
+            # Determine the mount point node (the one matching self.data_dir)
+            # and start walking depth-counting from there.
+            def find_and_walk(node, current_rel_depth, inside_mount):
+                path = node.get('path', '')
+                
+                # Check if this node is our data_dir (mount point)
+                if not inside_mount:
+                    if os.path.abspath(path) == os.path.abspath(self.data_dir):
+                        inside_mount = True
+                        current_rel_depth = 0
+                    else:
+                        # Continue searching for the mount point in children
+                        children = node.get('children', {})
+                        if isinstance(children, dict):
+                            for child in children.values(): find_and_walk(child, 0, False)
+                        elif isinstance(children, list):
+                            for child in children: find_and_walk(child, 0, False)
+                        return
+
+                # If we are here, we are at or inside the mount point
+                if current_rel_depth == depth:
+                    if node.get('content_type') == 'directory':
+                        targets.append(path)
+                    return
+
+                # Recurse further down
+                children = node.get('children', {})
+                if isinstance(children, dict):
+                    for child in children.values(): find_and_walk(child, current_rel_depth + 1, True)
+                elif isinstance(children, list):
+                    for child in children: find_and_walk(child, current_rel_depth + 1, True)
+
+            find_and_walk(tree_data, 0, False)
+        except Exception as e:
+            click.echo(click.style(f"Discovery error: {e}. Falling back to root.", fg="yellow"))
+            return ["/"]
+
+        if not targets:
+            click.echo(click.style(f"No targets found at relative depth {depth}. (Check if data is synced)", fg="yellow"))
+            targets = ["/"]
+        else:
+            example_path = random.choice(targets)
+            click.echo(f"  [Check] Example target path at relative depth {depth}: '{example_path}'")
+            
+        click.echo(f"Discovered {len(targets)} candidate directories via API.")
+        return targets
+
+    def run_concurrent_baseline(self, targets, concurrency=20, requests_count=100):
+        click.echo(f"Running Concurrent OS Baseline (Recursive find -ls): {concurrency} workers, {requests_count} requests...")
+        # Since targets are now absolute paths from Fusion, we extract the relative part
+        # to join with local data_dir if needed, but here find needs absolute paths.
+        tasks = [(self.data_dir, t) for t in [random.choice(targets) for _ in range(requests_count)]]
+        latencies = []
+        start_total = time.time()
+        with ProcessPoolExecutor(max_workers=concurrency) as executor:
+            futures = [executor.submit(run_find_recursive_metadata_task, t) for t in tasks]
+            for f in as_completed(futures): latencies.append(f.result())
+        total_time = time.time() - start_total
+        return self._calculate_stats(latencies, total_time, requests_count)
+
+    def _run_single_fusion_req(self, url, headers, path):
+        start = time.time()
+        try:
+            res = requests.get(f"{url}/views/fs/tree", params={"path": path}, headers=headers, timeout=10)
+            if res.status_code != 200: return None
+        except Exception: return None
+        return time.time() - start
+
+    def run_concurrent_fusion(self, api_key, targets, concurrency=20, requests_count=100):
+        click.echo(f"Running Concurrent Fusion API (Recursive Tree): {concurrency} workers, {requests_count} requests...")
+        url = f"http://localhost:{self.services.fusion_port}"
+        headers = {"X-API-Key": api_key}
+        tasks = [random.choice(targets) for _ in range(requests_count)]
+        latencies = []
+        start_total = time.time()
+        with ThreadPoolExecutor(max_workers=concurrency) as executor:
+            futures = [executor.submit(self._run_single_fusion_req, url, headers, t) for t in tasks]
+            for f in as_completed(futures):
+                res = f.result()
+                if res is not None: latencies.append(res)
+        total_time = time.time() - start_total
+        return self._calculate_stats(latencies, total_time, requests_count)
+
+    def wait_for_sync(self, api_key: str):
+        click.echo("Waiting for Fusion readiness (Alternating between API status and Agent logs)...")
+        fusion_url = f"http://localhost:{self.services.fusion_port}"
+        headers = {"X-API-Key": api_key}
+        start_wait = time.time()
+        loop_count = 0
+        while True:
+            elapsed = time.time() - start_wait
+            if loop_count % 2 == 0:
+                is_ok, log_msg = self.services.check_agent_logs()
+                if not is_ok: raise RuntimeError(f"Agent reported error during sync: {log_msg}")
+                if int(elapsed) % 30 < 5: click.echo(f"  [Agent] Status: {log_msg}")
+            try:
+                res = requests.get(f"{fusion_url}/views/fs/tree", params={"path": "/"}, headers=headers, timeout=5)
+                if res.status_code == 200:
+                    click.echo(f"  [Fusion] READY (200 OK) after {elapsed:.1f}s.")
+                    break
+                elif res.status_code == 503:
+                    if int(elapsed) % 5 == 0:
+                        click.echo(f"  [Fusion] Still syncing... (Elapsed: {int(elapsed)}s)")
+                else: raise RuntimeError(f"  [Fusion] Unexpected API response: {res.status_code}")
+            except requests.ConnectionError: pass
+            except Exception as e: click.echo(f"  [Fusion] Warning: Connection glitch ({e})")
+            loop_count += 1
+            time.sleep(5)
+        click.echo("Sync complete. Proceeding to benchmark.")
+
+    def generate_html_report(self, results, output_path):
+        """Generates a rich HTML report with charts using Chart.js."""
+        template = """
+<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="utf-8">
+    <title>Fustor Benchmark Report</title>
+    <script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
+    <style>
+        body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; margin: 40px; background: #f4f7f6; color: #333; }
+        .container { max-width: 1100px; margin: auto; background: white; padding: 40px; border-radius: 12px; box-shadow: 0 4px 20px rgba(0,0,0,0.08); }
+        h1 { color: #2c3e50; border-bottom: 2px solid #eee; padding-bottom: 15px; margin-top: 0; }
+        .summary { display: flex; justify-content: space-between; margin: 30px -10px; }
+        .stat-card { background: #fff; padding: 20px; border-radius: 10px; flex: 1; margin: 0 10px; text-align: center; border: 1px solid #eee; border-top: 5px solid #3498db; transition: transform 0.2s; }
+        .stat-card:hover { transform: translateY(-5px); }
+        .stat-card.fusion { border-top-color: #2ecc71; }
+        .stat-card.gain { border-top-color: #f1c40f; }
+        .stat-value { font-size: 28px; font-weight: bold; margin: 10px 0; color: #2c3e50; }
+        .stat-label { font-size: 14px; color: #7f8c8d; text-transform: uppercase; letter-spacing: 1px; }
+        .chart-row { display: flex; gap: 20px; margin-bottom: 40px; }
+        .chart-box { flex: 1; background: #fff; padding: 20px; border-radius: 10px; border: 1px solid #eee; }
+        .chart-container { position: relative; height: 350px; width: 100%; }
+        table { width: 100%; border-collapse: collapse; margin-top: 20px; font-size: 15px; }
+        th, td { text-align: left; padding: 15px; border-bottom: 1px solid #eee; }
+        th { background: #f8f9fa; color: #2c3e50; font-weight: 600; }
+        .winning { color: #2ecc71; font-weight: bold; }
+        .info-bar { background: #e8f4fd; padding: 15px; border-radius: 8px; margin-bottom: 30px; display: flex; gap: 20px; font-size: 14px; }
+    </style>
+</head>
+<body>
+    <div class="container">
+        <h1>Fustor Performance Benchmark</h1>
+        
+        <div class="info-bar">
+            <span>📅 Time: <strong>{{timestamp}}</strong></span>
+            <span>📂 Target Depth: <strong>{{depth}}</strong></span>
+            <span>🚀 Requests: <strong>{{reqs}}</strong></span>
+            <span>👥 Concurrency: <strong>{{concurrency}}</strong></span>
+        </div>
+        
+        <div class="summary">
+            <div class="stat-card">
+                <div class="stat-label">OS Baseline (Avg)</div>
+                <div class="stat-value">{{os_avg}} ms</div>
+            </div>
+            <div class="stat-card fusion">
+                <div class="stat-label">Fusion API (Avg)</div>
+                <div class="stat-value">{{fusion_avg}} ms</div>
+            </div>
+            <div class="stat-card gain">
+                <div class="stat-label">Speedup Factor</div>
+                <div class="stat-value" style="color: #2ecc71">{{gain}}x</div>
+            </div>
+        </div>
+
+        <div class="chart-row">
+            <div class="chart-box">
+                <h3>Latency Distribution (Bar)</h3>
+                <div class="chart-container">
+                    <canvas id="barChart"></canvas>
+                </div>
+            </div>
+            <div class="chart-box">
+                <h3>Latency Percentiles (Line)</h3>
+                <div class="chart-container">
+                    <canvas id="lineChart"></canvas>
+                </div>
+            </div>
+        </div>
+
+        <h2>Detailed Metrics Comparison</h2>
+        <table>
+            <thead>
+                <tr>
+                    <th>Metric (ms)</th>
+                    <th>OS (find -ls)</th>
+                    <th>Fusion API</th>
+                    <th>Improvement</th>
+                </tr>
+            </thead>
+            <tbody>
+                <tr><td>Average Latency</td><td>{{os_avg}}</td><td>{{fusion_avg}}</td><td class="winning">{{gain_avg}}x faster</td></tr>
+                <tr><td>Median (P50)</td><td>{{os_p50}}</td><td>{{fusion_p50}}</td><td class="winning">{{gain_p50}}x faster</td></tr>
+                <tr><td>P95 Latency</td><td>{{os_p95}}</td><td>{{fusion_p95}}</td><td class="winning">{{gain_p95}}x faster</td></tr>
+                <tr><td>P99 Latency</td><td>{{os_p99}}</td><td>{{fusion_p99}}</td><td class="winning">{{gain_p99}}x faster</td></tr>
+                <tr><td>Throughput (QPS)</td><td>{{os_qps}}</td><td>{{fusion_qps}}</td><td class="winning">{{gain_qps}}x higher</td></tr>
+                <tr><td>Min / Max</td><td>{{os_min}} / {{os_max}}</td><td>{{fusion_min}} / {{fusion_max}}</td><td>-</td></tr>
+            </tbody>
+        </table>
+    </div>
+
+    <script>
+        // Bar Chart
+        new Chart(document.getElementById('barChart'), {
+            type: 'bar',
+            data: {
+                labels: ['Average', 'Median', 'P95', 'P99'],
+                datasets: [
+                    { label: 'OS Baseline', data: [{{os_avg}}, {{os_p50}}, {{os_p95}}, {{os_p99}}], backgroundColor: '#3498db' },
+                    { label: 'Fusion API', data: [{{fusion_avg}}, {{fusion_p50}}, {{fusion_p95}}, {{fusion_p99}}], backgroundColor: '#2ecc71' }
+                ]
+            },
+            options: { responsive: true, maintainAspectRatio: false, scales: { y: { beginAtZero: true } } }
+        });
+
+        // Percentile Line Chart
+        new Chart(document.getElementById('lineChart'), {
+            type: 'line',
+            data: {
+                labels: ['Min', 'P50', 'P75', 'P90', 'P95', 'P99', 'Max'],
+                datasets: [
+                    { label: 'OS Baseline', data: [{{os_min}}, {{os_p50}}, {{os_p75}}, {{os_p90}}, {{os_p95}}, {{os_p99}}, {{os_max}}], borderColor: '#3498db', fill: false, tension: 0.1 },
+                    { label: 'Fusion API', data: [{{fusion_min}}, {{fusion_p50}}, {{fusion_p75}}, {{fusion_p90}}, {{fusion_p95}}, {{fusion_p99}}, {{fusion_max}}], borderColor: '#2ecc71', fill: false, tension: 0.1 }
+                ]
+            },
+            options: { responsive: true, maintainAspectRatio: false, scales: { y: { type: 'logarithmic', title: { display: true, text: 'Latency (ms) - Log Scale' } } } }
+        });
+    </script>
+</body>
+</html>
+"""
+        # Calculate speedups
+        g_avg = results['os']['avg'] / results['fusion']['avg'] if results['fusion']['avg'] > 0 else 0
+        
+        # Helper for percentiles in line chart
+        def get_p(stats, p):
+            raw = stats['raw']
+            idx = int(len(raw) * p / 100)
+            return raw[min(idx, len(raw)-1)]
+
+        html = template.replace("{{timestamp}}", results['timestamp']) \
+                       .replace("{{depth}}", str(results['depth'])) \
+                       .replace("{{reqs}}", str(results['requests'])) \
+                       .replace("{{concurrency}}", str(results['concurrency'])) \
+                       .replace("{{os_avg}}", f"{results['os']['avg']:.2f}") \
+                       .replace("{{fusion_avg}}", f"{results['fusion']['avg']:.2f}") \
+                       .replace("{{os_p50}}", f"{results['os']['p50']:.2f}") \
+                       .replace("{{fusion_p50}}", f"{results['fusion']['p50']:.2f}") \
+                       .replace("{{os_p95}}", f"{results['os']['p95']:.2f}") \
+                       .replace("{{fusion_p95}}", f"{results['fusion']['p95']:.2f}") \
+                       .replace("{{os_p99}}", f"{results['os']['p99']:.2f}") \
+                       .replace("{{fusion_p99}}", f"{results['fusion']['p99']:.2f}") \
+                       .replace("{{os_qps}}", f"{results['os']['qps']:.1f}") \
+                       .replace("{{fusion_qps}}", f"{results['fusion']['qps']:.1f}") \
+                       .replace("{{os_min}}", f"{results['os']['min']:.2f}") \
+                       .replace("{{os_max}}", f"{results['os']['max']:.2f}") \
+                       .replace("{{fusion_min}}", f"{results['fusion']['min']:.2f}") \
+                       .replace("{{fusion_max}}", f"{results['fusion']['max']:.2f}") \
+                       .replace("{{os_p75}}", f"{get_p(results['os'], 75):.2f}") \
+                       .replace("{{os_p90}}", f"{get_p(results['os'], 90):.2f}") \
+                       .replace("{{fusion_p75}}", f"{get_p(results['fusion'], 75):.2f}") \
+                       .replace("{{fusion_p90}}", f"{get_p(results['fusion'], 90):.2f}") \
+                       .replace("{{gain}}", f"{g_avg:.1f}") \
+                       .replace("{{gain_avg}}", f"{g_avg:.1f}") \
+                       .replace("{{gain_p50}}", f"{results['os']['p50']/results['fusion']['p50']:.1f}" if results['fusion']['p50'] > 0 else "N/A") \
+                       .replace("{{gain_p95}}", f"{results['os']['p95']/results['fusion']['p95']:.1f}" if results['fusion']['p95'] > 0 else "N/A") \
+                       .replace("{{gain_p99}}", f"{results['os']['p99']/results['fusion']['p99']:.1f}" if results['fusion']['p99'] > 0 else "N/A") \
+                       .replace("{{gain_qps}}", f"{results['fusion']['qps']/results['os']['qps']:.1f}" if results['os']['qps'] > 0 else "N/A")
+
+        with open(output_path, "w") as f: f.write(html)
+
+    def run(self, concurrency=20, reqs=200, target_depth=5, force_gen=False, custom_target=False):
+        if not custom_target:
+            if os.path.exists(self.data_dir) and not force_gen: click.echo(f"Data directory '{self.data_dir}' exists. Skipping generation.")
+            else: self.generator.generate()
+        else: click.echo(f"Benchmarking target directory: {self.data_dir}")
+        
+        try:
+            self.services.setup_env()
+            self.services.start_registry(); api_key = self.services.configure_system()
+            self.services.start_fusion(); self.services.start_agent(api_key)
+            time.sleep(2)
+            is_ok, msg = self.services.check_agent_logs()
+            if not is_ok: raise RuntimeError(f"Agent failed to initialize correctly: {msg}")
+            click.echo("Agent health check passed.")
+            
+            self.wait_for_sync(api_key)
+            targets = self._discover_leaf_targets_via_api(api_key, target_depth)
+            
+            # Run benchmarks
+            os_stats = self.run_concurrent_baseline(targets, concurrency, reqs)
+            fusion_stats = self.run_concurrent_fusion(api_key, targets, concurrency, reqs)
+            
+            # Prepare results object
+            final_results = {
+                "depth": target_depth, "requests": reqs, "concurrency": concurrency,
+                "target_directory_count": len(targets),
+                "os": os_stats, "fusion": fusion_stats,
+                "timestamp": time.strftime("%Y-%m-%d %H:%M:%S")
+            }
+
+            # Save JSON and HTML to results directory
+            results_dir = os.path.join(self.run_dir, "results")
+            os.makedirs(results_dir, exist_ok=True)
+            
+            json_path = os.path.join(results_dir, "stress-find.json")
+            html_path = os.path.join(results_dir, "stress-find.html")
+            
+            with open(json_path, "w") as f: json.dump(final_results, f, indent=2)
+            self.generate_html_report(final_results, html_path)
+
+            # Output Scorecard to console
+            click.echo("\n" + "="*60)
+            click.echo(f"RECURSIVE METADATA RETRIEVAL PERFORMANCE (DEPTH {target_depth})")
+            click.echo(f"Target Directories Found: {len(targets)}")
+            click.echo("="*60)
+            click.echo(f"{ 'Metric (ms)':<25} | {'OS (find -ls)':<18} | {'Fusion API':<18}")
+            click.echo("-" * 65)
+            click.echo(f"{ 'Avg Latency':<25} | {os_stats['avg']:10.2f} ms      | {fusion_stats['avg']:10.2f} ms")
+            click.echo(f"{ 'P50 Latency':<25} | {os_stats['p50']:10.2f} ms      | {fusion_stats['p50']:10.2f} ms")
+            click.echo(f"{ 'P99 Latency':<25} | {os_stats['p99']:10.2f} ms      | {fusion_stats['p99']:10.2f} ms")
+            click.echo(f"{ 'Throughput (QPS)':<25} | {os_stats['qps']:10.1f}         | {fusion_stats['qps']:10.1f}")
+            click.echo("-" * 65)
+            click.echo(click.style(f"\nJSON results saved to: {json_path}", fg="cyan"))
+            click.echo(click.style(f"Visual HTML report saved to: {html_path}", fg="green", bold=True))
+            
+        finally:
+            self.services.stop_all()

fustor_benchmark-0.2/src/fustor_benchmark/services.py

@@ -0,0 +1,226 @@
+import os
+import time
+import shutil
+import signal
+import subprocess
+import requests
+import yaml
+import click
+
+class ServiceManager:
+    def __init__(self, run_dir: str):
+        self.run_dir = os.path.abspath(run_dir)
+        # 监控目标数据目录
+        self.data_dir = os.path.join(self.run_dir, "data")
+        # 系统环境主目录 (FUSTOR_HOME)
+        self.env_dir = os.path.join(self.run_dir, ".fustor")
+        
+        self.registry_port = 18101
+        self.fusion_port = 18102
+        self.agent_port = 18100
+        self.processes = []
+        
+        # Paths
+        self.venv_bin = os.path.abspath(".venv/bin") # Assuming run from repo root
+
+    def setup_env(self):
+        # Safety Check: Only allow operations in directories ending with 'fustor-benchmark-run'
+        if not self.run_dir.endswith("fustor-benchmark-run"):
+            click.echo(click.style(f"FATAL: Environment setup denied. Target run-dir '{self.run_dir}' must end with 'fustor-benchmark-run' for safety.", fg="red", bold=True))
+            sys.exit(1)
+
+        if os.path.exists(self.env_dir):
+            shutil.rmtree(self.env_dir)
+        os.makedirs(self.env_dir, exist_ok=True)
+        
+        # Generate a random token for internal communication
+        import secrets
+        self.client_token = secrets.token_urlsafe(32)
+        
+        # Registry DB config
+        with open(os.path.join(self.env_dir, ".env"), "w") as f:
+            f.write(f"FUSTOR_REGISTRY_DB_URL=sqlite+aiosqlite:///{self.env_dir}/registry.db\n")
+            f.write(f"FUSTOR_FUSION_REGISTRY_URL=http://localhost:{self.registry_port}\n")
+            f.write(f"FUSTOR_REGISTRY_CLIENT_TOKEN={self.client_token}\n")
+
+    def _wait_for_service(self, url: str, name: str, timeout: int = 30):
+        click.echo(f"Waiting for {name} at {url}...")
+        start = time.time()
+        while time.time() - start < timeout:
+            try:
+                requests.get(url, timeout=1)
+                click.echo(f"{name} is up.")
+                return True
+            except:
+                time.sleep(0.5)
+        click.echo(f"Error: {name} failed to start.")
+        return False
+
+    def start_registry(self):
+        cmd = [
+            f"{self.venv_bin}/fustor-registry", "start",
+            "-p", str(self.registry_port)
+        ]
+        log_file = open(os.path.join(self.env_dir, "registry.log"), "w")
+        env = os.environ.copy()
+        env["FUSTOR_HOME"] = self.env_dir
+        env["FUSTOR_REGISTRY_CLIENT_TOKEN"] = self.client_token
+        
+        p = subprocess.Popen(cmd, env=env, stdout=log_file, stderr=subprocess.STDOUT)
+        self.processes.append(p)
+        
+        if not self._wait_for_service(f"http://localhost:{self.registry_port}/health", "Registry"):
+            raise RuntimeError("Registry start failed")
+
+    def configure_system(self):
+        reg_url = f"http://localhost:{self.registry_port}/v1"
+        click.echo("Logging in to Registry...")
+        try:
+            res = requests.post(f"{reg_url}/auth/login", data={
+                "username": "admin@admin.com",
+                "password": "admin"
+            })
+            if res.status_code != 200:
+                raise RuntimeError(f"Login failed: {res.text}")
+            
+            token = res.json()["access_token"]
+            headers = {"Authorization": f"Bearer {token}"}
+            
+            click.echo("Creating Datastore...")
+            res = requests.post(f"{reg_url}/datastores/", json={
+                "name": "BenchmarkDS", "description": "Auto-generated"
+            }, headers=headers)
+            if res.status_code not in (200, 201):
+                 raise RuntimeError(f"DS creation failed: {res.text}")
+            ds_id = res.json()["id"]
+            
+            click.echo("Creating API Key...")
+            res = requests.post(f"{reg_url}/keys/", json={
+                "datastore_id": ds_id, "name": "bench-key"
+            }, headers=headers)
+            if res.status_code not in (200, 201):
+                 raise RuntimeError(f"API Key creation failed: {res.text}")
+            
+            self.api_key = res.json()["key"]
+            click.echo(f"API Key generated: {self.api_key[:8]}...")
+            
+            return self.api_key
+        except Exception as e:
+            raise RuntimeError(f"Failed to configure system: {e}")
+
+    def start_fusion(self):
+        cmd = [
+            f"{self.venv_bin}/fustor-fusion", "start",
+            "-p", str(self.fusion_port)
+        ]
+        log_file = open(os.path.join(self.env_dir, "fusion.log"), "w")
+        env = os.environ.copy()
+        env["FUSTOR_HOME"] = self.env_dir
+        env["FUSTOR_FUSION_REGISTRY_URL"] = f"http://localhost:{self.registry_port}"
+        env["FUSTOR_REGISTRY_CLIENT_TOKEN"] = self.client_token
+        
+        p = subprocess.Popen(cmd, env=env, stdout=log_file, stderr=subprocess.STDOUT)
+        self.processes.append(p)
+        
+        click.echo(f"Waiting for Fusion at http://localhost:{self.fusion_port}...")
+        start = time.time()
+        while time.time() - start < 30:
+            try:
+                requests.get(f"http://localhost:{self.fusion_port}/", timeout=1)
+                click.echo("Fusion is up.")
+                return
+            except requests.ConnectionError:
+                time.sleep(0.5)
+        raise RuntimeError("Fusion start failed")
+
+    def start_agent(self, api_key: str):
+        config = {
+            "sources": {
+                "bench-fs": {
+                    "driver": "fs",
+                    "uri": self.data_dir,
+                    "credential": {"user": "admin"},
+                    "disabled": False,
+                    "is_transient": True,
+                    "max_queue_size": 100000,
+                    "max_retries": 1,
+                    "driver_params": {"min_monitoring_window_days": 1}
+                }
+            },
+            "pushers": {
+                "bench-fusion": {
+                    "driver": "fusion",
+                    "endpoint": f"http://127.0.0.1:{self.fusion_port}",
+                    "credential": {"key": api_key},
+                    "disabled": False,
+                    "batch_size": 1000,
+                    "max_retries": 10,
+                    "retry_delay_sec": 5
+                }
+            },
+            "syncs": {
+                "bench-sync": {
+                    "source": "bench-fs",
+                    "pusher": "bench-fusion",
+                    "disabled": False
+                }
+            }
+        }
+        with open(os.path.join(self.env_dir, "agent-config.yaml"), "w") as f:
+            yaml.dump(config, f)
+            
+        cmd = [
+            f"{self.venv_bin}/fustor-agent", "start",
+            "-p", str(self.agent_port)
+        ]
+        log_file = open(os.path.join(self.env_dir, "agent.log"), "w")
+        env = os.environ.copy()
+        env["FUSTOR_HOME"] = self.env_dir
+        
+        p = subprocess.Popen(cmd, env=env, stdout=log_file, stderr=subprocess.STDOUT)
+        self.processes.append(p)
+        
+        self._wait_for_service(f"http://localhost:{self.agent_port}/", "Agent")
+
+    def check_agent_logs(self, lines=100):
+        log_path = os.path.join(self.env_dir, "agent.log")
+        if not os.path.exists(log_path):
+            return False, "Log file not found yet"
+        
+        try:
+            with open(log_path, "r") as f:
+                content = f.readlines()[-lines:]
+            
+            error_keywords = ["ERROR", "Exception", "Traceback", "404 -", "failed to start", "ConfigurationError", "崩溃"]
+            success_keywords = ["initiated successfully", "Uvicorn running", "Application startup complete"]
+            
+            has_error = False
+            error_msg = ""
+            has_success = False
+
+            for line in content:
+                if any(kw in line for kw in error_keywords):
+                    has_error = True
+                    error_msg = line.strip()
+                if any(kw in line for kw in success_keywords):
+                    has_success = True
+
+            if has_error:
+                return False, f"Detected Error: {error_msg}"
+            
+            if not has_success:
+                return True, "Starting up... (no success signal yet)"
+                
+            return True, "OK (Success signals detected)"
+        except Exception as e:
+            return True, f"Could not read log: {e}"
+
+    def stop_all(self):
+        click.echo("Stopping all services...")
+        for p in self.processes:
+            try:
+                p.terminate()
+                p.wait(timeout=5)
+            except:
+                p.kill()
+        self.processes = []

fustor_benchmark-0.2/src/fustor_benchmark.egg-info/PKG-INFO

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: fustor-benchmark
+Version: 0.2
+Summary: Performance benchmarking tool for Fustor platform
+Author-email: Huajin Wang <wanghuajin999@163.com>
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.1.7
+Requires-Dist: requests>=2.31.0
+Requires-Dist: pyyaml>=6.0.1
+Requires-Dist: psutil>=5.9.0
+
+# Fustor 性能基准测试工具 (Benchmark)
+
+该模块是 Fustor 平台的自动化压力测试和性能量化工具。它通过模拟大规模文件系统元数据，量化 Fusion API 相比于操作系统原生文件系统调用的性能优势。
+
+## 核心设计目标
+
+1.  **量化优势**: 对比 Fusion 内存索引与 Linux 原生 `find` 命令在递归元数据检索下的延迟与吞吐量。
+2.  **百万级规模**: 支持生成并同步超过 1,000,000 个文件的元数据。
+3.  **全自动流程**: 自动编排 Registry、Fusion 和 Agent，实现一键式从环境部署到报告生成。
+
+## 目录结构规范与安全
+
+为了保护生产数据免受误删，Benchmark 实施了严格的路径校验：
+
+*   **路径白名单**: 压测主目录（`run-dir`）必须以 **`fustor-benchmark-run`** 结尾。
+*   **结构定义**:
+    *   `{run-dir}/data/`: 存放生成的数百万个模拟文件。
+    *   `{run-dir}/.fustor/`: 存放压测期间的独立配置文件、SQLite 数据库、日志以及最终报告。
+
+## 快速使用
+
+### 1. 数据生成
+构建一个包含 1000 个 UUID 目录，每个目录下 1000 个文件（总计 100 万文件）的测试集：
+```bash
+uv run fustor-benchmark generate fustor-benchmark-run --num-dirs 1000
+```
+
+### 2. 执行压测
+运行全链路同步并执行并发性能对比：
+```bash
+uv run fustor-benchmark run fustor-benchmark-run -d 5 -c 20 -n 100
+```
+*   `-d`: 探测深度。
+*   `-c`: 并发数。
+*   `-n`: 总请求次数。
+
+## 报告与指标
+
+压测完成后，将在 `fustor-benchmark-run/.fustor/` 下生成以下产出：
+
+1.  **`report.html`**: 交互式可视化报表。
+    *   **Latency Distribution**: 展示 Avg, P50, P95, P99 的柱状对比。
+    *   **Latency Percentiles**: 展现延迟分布曲线。
+    *   **Speedup Factor**: 自动计算 Fusion 相比 OS 的加速倍数。
+2.  **`benchmark_results.json`**: 结构化的指标数据，包含所有原始延迟序列。
+
+## 安全保护说明
+
+Benchmark 会在 `run-dir` 下执行 `shutil.rmtree` 操作以清理旧环境。**请务必确保指定的目录不包含任何重要业务数据**。如果尝试在非 `fustor-benchmark-run` 后缀目录下运行，程序将强制退出。

fustor_benchmark-0.2/src/fustor_benchmark.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+src/fustor_benchmark/__init__.py
+src/fustor_benchmark/cli.py
+src/fustor_benchmark/generator.py
+src/fustor_benchmark/runner.py
+src/fustor_benchmark/services.py
+src/fustor_benchmark.egg-info/PKG-INFO
+src/fustor_benchmark.egg-info/SOURCES.txt
+src/fustor_benchmark.egg-info/dependency_links.txt
+src/fustor_benchmark.egg-info/entry_points.txt
+src/fustor_benchmark.egg-info/requires.txt
+src/fustor_benchmark.egg-info/top_level.txt

fustor_benchmark-0.2/src/fustor_benchmark.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

fustor_benchmark-0.2/src/fustor_benchmark.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+fustor-benchmark = fustor_benchmark.cli:cli

fustor_benchmark-0.2/src/fustor_benchmark.egg-info/requires.txt

@@ -0,0 +1,4 @@
+click>=8.1.7
+requests>=2.31.0
+pyyaml>=6.0.1
+psutil>=5.9.0

fustor_benchmark-0.2/src/fustor_benchmark.egg-info/top_level.txt

@@ -0,0 +1 @@
+fustor_benchmark