> This page is for version dev.
> For other versions, use one of these documentation indexes:
> - 1.8.1 (default): https://docs.nvidia.com/networking/cloudai/1.8.1/llms.txt
> - 1.7.1: https://docs.nvidia.com/networking/cloudai/1.7.1/llms.txt
> - 1.6.1: https://docs.nvidia.com/networking/cloudai/1.6.1/llms.txt
> - dev: https://docs.nvidia.com/networking/cloudai/dev/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/networking/cloudai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/networking/cloudai/_mcp/server.

`Fio` runs the open-source `fio` tool from CloudAI. It supports standalone and Slurm systems.

## Scenarios

Use `conf/common/test_scenario/fio.toml` for Slurm clusters. It runs the common `fio` test in a container and starts 4 tasks total: `num_nodes = 2` and `num_tasks_per_node = 2`.

Use `conf/common/test_scenario/fio_local.toml` for local/standalone runs. It uses host-installed `fio` and no container image.

## Fio Arguments

Put fio CLI options under `cmd_args.args`. CloudAI does not declare a fixed fio option list; keys pass through verbatim.

```toml
name = "fio"
description = "fio random write smoke test"
test_template_name = "Fio"

[cmd_args]
fio_binary = "fio"

  [cmd_args.args]
  name = "fio-smoke"
  filename = "/tmp/cloudai-fio-test"
  rw = "randwrite"
  bs = "128k"
  size = "80m"
  iodepth = 1
  numjobs = 1
  group_reporting = true
  thread = true
```

This emits options like `--rw=randwrite` and `--group_reporting`. Quote TOML keys when option names contain characters such as `-`:

```toml
[cmd_args.args]
"max-jobs" = 4
```

List values are CloudAI DSE sweeps:

```toml
[cmd_args.args]
bs = ["128k", "1m"]
iodepth = [1, 8, 32]
```

To repeat the same fio option in one run, use a nested table. Nested key names are only stable TOML item names; values become fio values:

```toml
[cmd_args.args.a]
"0" = "=foo"  # --a==foo
"1" = "bar"   # --a=bar

[cmd_args.args."client"]
"0" = "host1" # --client=host1
"1" = "host2" # --client=host2
```

For existing or complex fio configs, use `job_file`:

```toml
[cmd_args]
fio_binary = "/tmp/fio/fio"
job_file = "/tmp/kv_emulation.fio"
```

## Slurm Tasks

Scenario `num_nodes` controls node count. `cmd_args.num_tasks_per_node` controls Slurm tasks per node. Total fio tasks = `num_nodes * num_tasks_per_node`. CloudAI passes this as `--ntasks` and `--ntasks-per-node`.

```toml
[[Tests]]
id = "Tests.fio"
test_name = "fio"
num_nodes = 2

  [Tests.cmd_args]
  docker_image_url = "openeuler/fio:3.42-oe2403sp3"
  num_tasks_per_node = 2
```

## Default Metric

For `agent_metrics = ["default"]`, CloudAI aggregates parsed fio summary rows. Defaults report total bandwidth across all operations and tasks. Bandwidth metrics are normalized to MiB/s before aggregation. Latency metrics are normalized to usec before aggregation.

```toml
[cmd_args]
metric_operation = "all"    # read, write, trim, all, first
metric_name = "bw"          # bw, iops, latency
metric_aggregate = "sum"    # sum, mean, min, max, first
```

Raw parsed rows and normalized metric values are written to `fio_summary.csv`.

## API Documentation

### Command Arguments

### `FioCmdArgs`

Command line arguments for fio.

| Field                | Type                    | Default         | Description                                                                |
| -------------------- | ----------------------- | --------------- | -------------------------------------------------------------------------- |
| `fio_binary`         | `str`                   | `'fio'`         | fio executable to run. Use an absolute path for patched/custom fio builds. |
| `job_file`           | `str \| None`           | `None`          | Optional fio job/config file. When set, it is appended after CLI options.  |
| `args`               | `dict[str, typing.Any]` | Factory: `dict` | fio CLI options, without leading `--`. Keys are passed to fio verbatim.    |
| `docker_image_url`   | `str \| None`           | `None`          | Optional Docker image to use for Slurm container execution.                |
| `num_tasks_per_node` | `int \| None`           | `1`             | Optional Slurm task count per node for multi-node fio runs.                |
| `metric_operation`   | `str`                   | `'all'`         | Operation used for the default metric: read, write, trim, all, or first.   |
| `metric_name`        | `str`                   | `'bw'`          | Metric used for the default metric: bw, iops, or latency.                  |
| `metric_aggregate`   | `str`                   | `'sum'`         | Aggregation used for the default metric: sum, mean, min, max, or first.    |

### Test Definition

### `FioTestDefinition`

Test definition for fio.

| Field                    | Type                                                      | Default         | Description                                                                                                                                                                                                                   |
| ------------------------ | --------------------------------------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                   | `str`                                                     | Required        |                                                                                                                                                                                                                               |
| `description`            | `str`                                                     | Required        |                                                                                                                                                                                                                               |
| `test_template_name`     | `str`                                                     | Required        |                                                                                                                                                                                                                               |
| `cmd_args`               | `cloudai.workloads.fio.fio.FioCmdArgs`                    | Required        |                                                                                                                                                                                                                               |
| `dse_excluded_args`      | `list[str]`                                               | Factory: `list` |                                                                                                                                                                                                                               |
| `extra_env_vars`         | `dict[str, str \| typing.List[str]]`                      | `{}`            |                                                                                                                                                                                                                               |
| `extra_cmd_args`         | `dict[str, str]`                                          | `{}`            |                                                                                                                                                                                                                               |
| `extra_container_mounts` | `list[str]`                                               | `[]`            |                                                                                                                                                                                                                               |
| `git_repos`              | `list[cloudai._core.installables.git_repo.GitRepo]`       | `[]`            |                                                                                                                                                                                                                               |
| `nsys`                   | `cloudai.models.workload.NsysConfiguration \| None`       | `None`          |                                                                                                                                                                                                                               |
| `predictor`              | `cloudai.models.workload.PredictorConfig \| None`         | `None`          |                                                                                                                                                                                                                               |
| `training_report`        | `cloudai.models.workload.TrainingReportConfig \| None`    | `None`          |                                                                                                                                                                                                                               |
| `agent`                  | `str`                                                     | `'grid_search'` |                                                                                                                                                                                                                               |
| `agent_steps`            | `int`                                                     | `1`             |                                                                                                                                                                                                                               |
| `agent_metrics`          | `list[str]`                                               | `['default']`   |                                                                                                                                                                                                                               |
| `agent_reward_function`  | `str`                                                     | `'inverse'`     |                                                                                                                                                                                                                               |
| `agent_config`           | `dict[str, Any] \| None`                                  | `None`          | Agent configuration.                                                                                                                                                                                                          |
| `env_params`             | `dict[str, cloudai.configurator.env_params.EnvParamSpec]` | Factory: `dict` | Environment parameters sampled by the env per trial. Sibling to cmd_args; not part of the agent's action space. CloudAIGymEnv samples, persists them in the trajectory output, and includes them in the trajectory cache key. |