---
title: "cosbench-rs"
description: "A Rust object-storage load generator for mock, S3, and Swift targets with validated YAML workloads and JSON, CSV, timeline, and HTML reports."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.myswift.rs/llms.txt
> Use this file to discover all available pages before exploring further.

# cosbench-rs

`cosbench-rs` is a Rust implementation of the core COSBench workload model. It
supports mock, S3, and Swift storage, staged concurrency, mixed operation
ratios, integrity checks, multipart thresholds, and machine-readable reports.

## Install and verify

```sh
cd cosbench-rs
cargo build --release --locked
./target/release/cosbench-rs --help
./target/release/cosbench-rs validate -c examples/swift-tempauth.yaml
```

## Workload schema

Top-level fields are `name`, optional `description`, optional
`sample_interval_secs`, `storage`, optional `auth`, and `stages`.

Storage types:

- `mock`: optional simulated `latency_us`;
- `s3`: endpoint, region, access/secret keys, path-style choice, timeout, and
  multipart threshold/part size;
- `swift`: storage endpoint, timeout, and optional static token.

Auth types are `none`, `temp_auth`, and `keystone_v3`. For Swift, an empty
storage endpoint uses the URL returned by authentication.

```yaml
name: swift-roundtrip
description: prepare, mixed read/write, then cleanup
sample_interval_secs: 1
auth:
  type: temp_auth
  url: http://127.0.0.1:8080/auth/v1.0
  user: test:tester
  key: REPLACE_FROM_SECRET_STORE
storage:
  type: swift
  endpoint: ""
  timeout_ms: 60000
stages:
  - name: main
kind: main
workers: 8
runtime_secs: 30
operations:
  - { type: read, ratio: 70 }
  - { type: write, ratio: 30 }
objects:
  cprefix: bench-
  containers: { start: 1, end: 4 }
  oprefix: object-
  objects: { start: 1, end: 1000 }
  size: 65536
  hash_check: true
```

Each stage needs workers greater than zero, at least one operation with a
nonzero total ratio, and either `runtime_secs` or `total_ops`. Write operations
need a nonzero `size` or `size_max`. `sequential: true` makes object selection
deterministic for prepare/cleanup-style stages.

## Commands

```sh
cosbench-rs validate -c workload.yaml
cosbench-rs run -c workload.yaml --report-dir reports
cosbench-rs report -i reports --output reports/report.html
cosbench-rs import-xml -i legacy.xml -o workload.yaml
cosbench-rs serve --bind 127.0.0.1:19088
```

`run` writes JSON, CSV, and per-stage timeline CSV files when `--report-dir` is
set. The HTML report is self-contained. Preserve the workload file and raw JSON
beside derived CSV/HTML output.

## Control server

`serve` provides `/api/health`, `/api/workloads`, `/api/workloads/{id}`, and
`/runs/{id}`. Submitted work runs asynchronously in the process. The server's
CORS layer is permissive; bind it to loopback or a protected benchmark network
and do not place storage credentials in browser-visible shared workloads.

## Fair measurement

Separate prepare, measured main, and cleanup stages. Confirm the prepared
population before interpreting read success. Record route, client placement,
host contention, connection/concurrency settings, object distribution, errors,
and p50/p95/p99. Route-labelled historical results are on
[Performance](/performance); G8 requirements are on
[G0-G8 validation](/validation-gates).

Source: https://docs.myswift.rs/cosbench-rs/index.mdx