> For the complete documentation index, see [llms.txt](https://documentation.alluxio.io/ee-ai-cn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.alluxio.io/ee-ai-cn/benchmark/s3-api/cosbench.md).

# COSBench 基准测试

[COSBench](https://github.com/intel-cloud/cosbench) 是 Intel 的分布式对象存储基准测试工具——Controller + Driver 架构，执行阶段化 XML 工作负载。适合**复杂的多阶段读写工作负载**，支持跨多个 Driver 节点分布、混合操作类型。

关于何时选用 COSBench 而非 [Warp](/ee-ai-cn/benchmark/s3-api/warp.md) 或 [httpbench](/ee-ai-cn/benchmark/s3-api/httpbench.md)，参见[基准测试工具选型](/ee-ai-cn/benchmark/s3-api.md#ji-zhun-ce-shi-gong-ju-xuan-xing)。4 driver COSBench 集群的参考吞吐数据见[参考性能基线](/ee-ai-cn/benchmark/s3-api.md#can-kao-xing-neng-ji-xian)。

## 先决条件

* **操作系统**：CentOS 7（内核 3.10）或更高版本。COSBench 在 Ubuntu 上存在已知兼容性问题，不推荐使用。
* **预加载数据**：对于热读取基准测试（缓存命中），请确保测试数据集已完全加载到 Alluxio 缓存中。使用 `bin/alluxio job load --path /path --submit` 加载数据，使用 `bin/alluxio fs check-cached /path` 进行验证。

## 安装

在所有 COSBench Controller 和 Driver 节点上：

1. 下载 [COSBench 0.4.2.c4 版](https://github.com/intel-cloud/cosbench/releases/tag/v0.4.2.c4) 并解压缩。
2. 安装依赖项：

   ```shell
   sudo yum install nmap-ncat curl java-1.8.0-openjdk-devel -y
   ```
3. 禁用 MD5 验证——编辑 `cosbench-start.sh` 并添加以下 Java 属性。这对于与 Alluxio S3 API 的兼容性是必需的：

   ```properties
   -Dcom.amazonaws.services.s3.disableGetObjectMD5Validation=true
   ```
4. 从 COSBench 根目录启动 Controller 和所有 Driver：

   ```shell
   sudo bash start-all.sh
   ```

## 使用

运行下方任何场景都遵循相同的三步流程：先选一份 XML 工作负载（看下方子小节或自己写），存到 `conf/`，然后：

```shell
# 提交
bash cli.sh submit conf/<your-file>.xml

# 监控——打开 Web 仪表盘：
# http://<CONTROLLER_IP>:19088/controller/index.html

# 结束后停止所有服务
sudo bash stop-all.sh
```

COSBench 工作负载由以下阶段组成：

| 阶段        | 用途               |
| --------- | ---------------- |
| `init`    | 创建测试存储桶          |
| `prepare` | 写入用于测试的初始数据      |
| `main`    | 在设定的持续时间内运行读/写操作 |
| `cleanup` | 删除测试期间创建的对象      |
| `dispose` | 删除存储桶            |

{% hint style="info" %}
如果您正在使用 Alluxio 挂载点，则无法通过 S3 API 创建新的存储桶。跳过 `init` 和 `dispose` 阶段，并使用与您的挂载配置匹配的预先存在的存储桶。
{% endhint %}

**COSBench 配置语法**：

* `r(1,10)` — **范围**：按顺序遍历 1 到 10 的项目。用于 `init`、`prepare`、`cleanup` 和 `dispose` 阶段。
* `u(1,10)` — **均匀随机**：在 1 到 10 之间随机选择一个项目。用于 `main` 阶段以模拟真实的访问模式。
* `c(64)KB` — **常量**：每个对象的固定大小为 64KB。

{% hint style="info" %}
**存储桶命名**：COSBench 会在 `cprefix` 后自动追加数字序号。例如，`cprefix=my-bucket;containers=r(1,1)` 创建的存储桶名称是 `my-bucket1`，而非 `my-bucket`。使用预先存在的存储桶（如 Alluxio 挂载点）时，需确保 `cprefix` 生成的名称与实际存储桶名完全一致——对于名为 `my-bucket1` 的存储桶，应使用 `cprefix=my-bucket` 配合 `containers=r(1,1)`。
{% endhint %}

### 场景：基本读/写工作负载

**目标**：使用小数据集验证基本的 S3 读/写功能。

创建两个存储桶，向每个存储桶写入 10 个 64KB 的对象，运行一个 30 秒的测试，读写比为 80/20，然后进行清理。

{% hint style="info" %}
以下 `accesskey` 和 `secretkey` 为**占位符值**。请将其替换为您的 Alluxio S3 API 凭据。
{% endhint %}

```xml
<?xml version="1.0" encoding="UTF-8" ?>
<workload name="s3-sample" description="sample benchmark for s3">
  <storage type="s3" config="accesskey=root;secretkey=dump;endpoint=http://localhost:29998;path_style_access=true" />

  <workflow>
    <workstage name="init">
      <work type="init" workers="1" config="cprefix=s3testqwer;containers=r(1,2)" />
    </workstage>

    <workstage name="prepare">
      <work type="prepare" workers="1" config="cprefix=s3testqwer;containers=r(1,2);objects=r(1,10);sizes=c(64)KB" />
    </workstage>

    <workstage name="main">
      <work name="main" workers="8" runtime="30">
        <operation type="read" ratio="80" config="cprefix=s3testqwer;containers=u(1,2);objects=u(1,10)" />
        <operation type="write" ratio="20" config="cprefix=s3testqwer;containers=u(1,2);objects=u(11,20);sizes=c(64)KB" />
      </work>
    </workstage>

    <workstage name="cleanup">
      <work type="cleanup" workers="1" config="cprefix=s3testqwer;containers=r(1,2);objects=r(1,20)" />
    </workstage>

    <workstage name="dispose">
      <work type="dispose" workers="1" config="cprefix=s3testqwer;containers=r(1,2)" />
    </workstage>
  </workflow>
</workload>
```

### 场景：高并发读取测试

**目标**：在高并发下测量最大读取 IOPS/吞吐量。与基本示例的主要区别：使用 4 个分布式 Driver，每个 128 个线程。

准备 10,000 个小对象（100KB），使用四个 Driver，每个 Driver 有 128 个工作线程，并发读取 300 秒。

{% hint style="info" %}
每个 `<work>` 块在每个 Driver 中重复出现，因为 COSBench 要求对分布式工作负载进行显式 Driver 分配。每个块从单独的 Driver 节点发送流量，以最大化总并发量。
{% endhint %}

```xml
<?xml version="1.0" encoding="UTF-8" ?>
<workload name="s3-sample" description="sample benchmark for s3">
  <storage type="s3" config="accesskey=root;secretkey=dump;endpoint=http://<ip>:29998;path_style_access=true" />
  <workflow>
    <workstage name="prepare">
      <work type="prepare" workers="100" config="cprefix=ufs;containers=r(2,2);oprefix=myobjects;osuffix=.jpg;objects=r(1,10000);sizes=c(100)KB" />
    </workstage>

    <workstage name="128">
      <work name="read" workers="128" driver="driver1" runtime="300">
        <operation type="read" ratio="100" config="cprefix=ufs;containers=r(2,2);oprefix=myobjects;osuffix=.jpg;objects=u(1,10000)" />
      </work>
      <work name="read" workers="128" driver="driver2" runtime="300">
        <operation type="read" ratio="100" config="cprefix=ufs;containers=r(2,2);oprefix=myobjects;osuffix=.jpg;objects=u(1,10000)" />
      </work>
      <work name="read" workers="128" driver="driver3" runtime="300">
        <operation type="read" ratio="100" config="cprefix=ufs;containers=r(2,2);oprefix=myobjects;osuffix=.jpg;objects=u(1,10000)" />
      </work>
      <work name="read" workers="128" driver="driver4" runtime="300">
        <operation type="read" ratio="100" config="cprefix=ufs;containers=r(2,2);oprefix=myobjects;osuffix=.jpg;objects=u(1,10000)" />
      </work>
    </workstage>
  </workflow>
</workload>
```

## 故障排除

* **针对 Alluxio 的 `init` 阶段失败** — Alluxio 挂载点不支持通过 S3 API 创建存储桶。跳过 `init`/`dispose` 阶段，使用预先存在的存储桶。

跨工具的通用故障排查（redirect 模式行为、内核调优、缓存命中验证），参见 hub 页的[性能调优与故障排除](/ee-ai-cn/benchmark/s3-api.md#xing-neng-diao-you-yu-gu-zhang-pai-chu)。

## 另请参阅

* [S3 API 基准测试](/ee-ai-cn/benchmark/s3-api.md) — 概述、参考基线、工具选型、跨工具故障排查
* [Warp 基准测试](/ee-ai-cn/benchmark/s3-api/warp.md) — 适合做 bucket 级别读取测试的单二进制工具
* [httpbench 基准测试](/ee-ai-cn/benchmark/s3-api/httpbench.md) — 单 worker、redirect 感知的小工具
* [S3 API 设置与配置](/ee-ai-cn/data-access/s3-api.md) — 部署模式、端点设置、负载均衡器配置