doc: Document RBD Replay

Signed-off-by: Adam Crume <adamcrume@gmail.com>

diff --git a/doc/rbd/rbd-replay.rst b/doc/rbd/rbd-replay.rst
new file mode 100644 (file)
index 0000000..cc21ac9
--- /dev/null
+++ b/doc/rbd/rbd-replay.rst
@@ -0,0 +1,37 @@
+===================
+ RBD Replay
+===================
+
+.. index:: Ceph Block Device; RBD Replay
+
+RBD Replay is a set of tools for capturing and replaying Rados Block Device (RBD) workloads.
+To capture an RBD workload, ``lttng-tools`` must be installed on the client, and ``librbd`` on the clent must be the Giant release or later.
+To replay an RBD workload, ``librbd`` on the clent must be the Giant release or later.
+
+Capture and replay takes three steps\:
+
+1) Capture the trace.  Make sure to capture ``pthread_id`` context::
+
+    mkdir -p traces
+    lttng create -o traces librbd
+    lttng enable-event -u 'librbd:*'
+    lttng add-context -u -t pthread_id
+    lttng start
+    # run RBD workload here
+    lttng stop
+
+2) Process the trace with `rbd-replay-prep`_::
+
+    rbd-replay-prep traces/ust/uid/*/* replay.bin
+
+3) Replay the trace with `rbd-replay`_. Use read-only until you know it's doing what you want::
+
+    rbd-replay --read-only replay.bin
+
+.. important:: ``rbd-replay`` will destroy data by default.  Do not use against an image you wish to keep, unless you use the ``--read-only`` option.
+
+The replayed workload does not have to be against the same RBD image or even the same cluster as the captured workload.
+To account for differences, you may need to use the ``--pool`` and ``--map-image`` options of ``rbd-replay``.
+
+.. _rbd-replay: ../../man/8/rbd-replay
+.. _rbd-replay-prep: ../../man/8/rbd-replay-prep

diff --git a/doc/rbd/rbd.rst b/doc/rbd/rbd.rst
index 4105362d8a88aba92b82615eda113d2393bdfcac..a2c7c219bcab466379e588526b69cf349adb028b 100644 (file)
--- a/doc/rbd/rbd.rst
+++ b/doc/rbd/rbd.rst
@@ -55,6 +55,7 @@ devices simultaneously.
        Manpage rbd-replay-prep <../../man/8/rbd-replay-prep>
        Manpage rbd-replay <../../man/8/rbd-replay>
        librbd <librbdpy>
+       RBD Replay <rbd-replay>
        
 
 .. _RBD Caching: ../rbd-config-ref/