ceph/src/seastar/doc/io-tester.md

   1 ## I/O Tester utility
   2
   3 The I/O Tester utility, `io_tester` generates a user-defined I/O pattern
   4 spanning one of multiple shards that is designed to simulate the I/O behavior
   5 of a complex Seastar application.
   6
   7 # Running I/O tester:
   8
   9 I/O tester takes the same options as Seastar, and those options may be used
  10 to test the behavior of I/O under the circumnstances established by those
  11 options. For instance, one may adjust the `--task-quota-ms` option to see
  12 if that affects higher percentile latencies.
  13
  14 Aside from the usual seastar options, I/O tester accepts the following options:
  15
  16 * `duration`: for how long to run the evaluation,
  17 * `directory`: a directory where to run the evaluation (it must be on XFS),
  18 * `conf`: the path to a YAML file describing the evaluation.
  19
  20 # Describing the evaluation
  21
  22 The evaluation is described in a YAML file that contains multiple classes.
  23 Each class spans jobs of similar characteristics in different shards and (for now)
  24 all jobs run concurrently.
  25
  26 The YAML file contains a list of maps where each element of the list describes a class.
  27 A class has some properties that are common to all elements of the class, and a nested map
  28 that contain properties of a job (class instance in a shard)
  29
  30 For example:
  31
  32 ```
  33 - name: big_writes
  34   type: seqread
  35   shards: all
  36   shard_info:
  37     parallelism: 10
  38     reqsize: 256kB
  39     shares: 10
  40     think_time: 0
  41 ```
  42
  43 * `name`: mandatory property, a string that identifies jobs of this class
  44 * `type`: mandatory property, one of seqread, seqwrite, randread, randwrite, append, cpu
  45 * `shards`: mandatory property, either the string "all" or a list of shards where this class should place jobs.
  46
  47 The properties under `shard_info` represent properties of the job that will
  48 be replicated to each shard. All properties under `shard_info` are optional, and in case not specified, defaults are used.
  49
  50 * `parallelism`: the amount of parallel requests this job will generate in a specific shard. Requests can be either active or thinking (see `think_time`)
  51 * `reqsize` : (I/O loads only) the size of requests generated by this job
  52 * `shares` : how many shares requests in this job will have in the scheduler
  53 * `think_time`: how long to wait before submitting another request in this job once one finishes.
  54 * `execution_time`: (cpu loads only) for how long to execute a CPU loop
  55
  56 # Example output
  57
  58 ```
  59       Creating initial files...
  60       Starting evaluation...
  61       Shard  0
  62        Class 0(big_writes: 10 shares, 262144-byte SEQ WRITE, 10 concurrent requests, NO think time)
  63         Throughput         :   436556 KB/s
  64         Lat average        :     5847 usec
  65         Lat quantile=  0.5 :     2678 usec
  66         Lat quantile= 0.95 :    13029 usec
  67         Lat quantile= 0.99 :    20835 usec
  68         Lat quantile=0.999 :   246090 usec
  69         Lat max            :   450785 usec
  70 ```
  71
  72 # Future
  73
  74 Some ideas for extending I/O tester:
  75
  76 * allow properties like think time, request size, etc, to be specified as distributions instead of a fixed number
  77 * allow classes to have class-wide properties. For instance, we could define a class with parallelism of 100, and distribute those 100 requests over all shards in which this class is placed
  78 * allow some jobs to be executed sequentially in relationship to others, so we can have preparation jobs.
  79 * support other types, like delete, fsync, etc.
  80 * provide functionality similar to diskplorer.
  81