From: Adam Crume <adamcrume@gmail.com>
Date: Tue, 2 Dec 2014 04:44:02 +0000 (-0800)
Subject: doc: Document RBD Replay
X-Git-Tag: v0.90~15^2
X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=70e1a5dcbb1b817a935782037f9a2b11d12f4d53;p=ceph.git

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
index 000000000000..cc21ac9eb69d
--- /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 4105362d8a88..a2c7c219bcab 100644
--- 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/