# 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) — 部署模式、端点设置、负载均衡器配置


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://documentation.alluxio.io/ee-ai-cn/benchmark/s3-api/cosbench.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.