ceph/src/test/fio/README.md

   1 FIO
   2 ===
   3
   4 Ceph uses the fio workload generator and benchmarking utility.
   5 (https://github.com/axboe/fio.git)
   6
   7 FIO tool is automatically fetched to build/src/fio, and build if necessary.
   8
   9 RBD
  10 ---
  11
  12 The fio engine for rbd is located in the fio tree itself, so you'll need to
  13 build it from source.
  14
  15 If you install the ceph libraries to a location that isn't in your
  16 LD_LIBRARY_PATH, be sure to add it:
  17
  18     export LD_LIBRARY_PATH=/path/to/install/lib
  19
  20 To build fio with rbd:
  21
  22     ./configure --extra-cflags="-I/path/to/install/include -L/path/to/install/lib"
  23     make
  24
  25 If configure fails with "Rados Block Device engine   no", see config.log for
  26 details and adjust the cflags as necessary.
  27
  28 If ceph was compiled with tcmalloc, it may be necessary to compile fio with:
  29     make EXTLIBS=tcmalloc
  30 Otherwise fio might crash in malloc_usable_size().
  31
  32 To view the fio options specific to the rbd engine:
  33
  34     ./fio --enghelp=rbd
  35
  36 See examples/rbd.fio for an example job file. To run:
  37
  38     ./fio examples/rbd.fio
  39
  40 ObjectStore
  41 -----------
  42
  43 This fio engine allows you to mount and use a ceph object store directly,
  44 without having to build a ceph cluster or start any daemons.
  45
  46 Because the ObjectStore is not a public-facing interface, we build it inside
  47 of the ceph tree and load libfio_ceph_objectstore.so into fio as an external
  48 engine.
  49
  50 To build fio_ceph_objectstore run:
  51 ```
  52   ./do_cmake.sh -DWITH_FIO=ON
  53   cd build
  54   make fio_ceph_objectstore
  55 ```
  56 This will fetch FIO to build/src/fio directory,
  57 compile fio tool and libfio_ceph_objectstore.so.
  58
  59 If you install the ceph libraries to a location that isn't in your
  60 LD_LIBRARY_PATH, be sure to add it:
  61
  62     export LD_LIBRARY_PATH=/path/to/install/lib
  63
  64 To view the fio options specific to the objectstore engine:
  65
  66     ./fio --enghelp=libfio_ceph_objectstore.so
  67
  68 The conf= option requires a ceph configuration file (ceph.conf). Example job
  69 and conf files for each object store are provided in the same directory as
  70 this README.
  71
  72 To run:
  73
  74     ./fio /path/to/job.fio
  75
  76 RADOS
  77 -----
  78
  79 By default FIO can be compiled with support for RADOS.
  80 When ceph is installed in your system default compilation of FIO includes RADOS ioengine.
  81 If you installed ceph in any other place (cmake -DCMAKE_INSTALL_PREFIX=${CEPH_INSTALL_ROOT} ..) you can build FIO following way:
  82
  83     LIBS="-lrados -ltcmalloc" LDFLAGS="-L${CEPH_INSTALL_ROOT}/lib" EXTFLAGS="-I${CEPH_INSTALL_ROOT}/include" \
  84     rados=yes ./configure
  85     LIBS="-lrados -ltcmalloc" LDFLAGS="-L${CEPH_INSTALL_ROOT}/lib" EXTFLAGS="-I${CEPH_INSTALL_ROOT}/include" \
  86     rados=yes make
  87
  88 "-ltcmalloc" is necessary if ceph was compiled with tcmalloc.
  89
  90 Messenger
  91 ---------
  92
  93 This fio engine allows you to test CEPH messenger transport layer, without
  94 any disk activities involved.
  95
  96 To build fio_ceph_messenger:
  97 ```
  98   ./do_cmake.sh -DWITH_FIO=ON
  99   cd build
 100   make fio_ceph_messenger
 101 ```
 102 If you install the ceph libraries to a location that isn't in your
 103 LD_LIBRARY_PATH, be sure to add it:
 104
 105     export LD_LIBRARY_PATH=/path/to/install/lib
 106
 107 To view the fio options specific to the messenger engine:
 108
 109     ./fio --enghelp=libfio_ceph_messenger.so
 110
 111 The ceph_conf_file= option requires a ceph configuration file (ceph.conf),
 112 see ceph-messenger.conf and ceph-messenger.fio for details.
 113
 114 To run:
 115
 116     ./fio ./ceph-messenger.fio