X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=contrib%2Fvisualize-alignment%2FREADME;h=6c30f94669a6e2d038d2906d348a5346d0f9deb6;hp=a81c92a07edd4dbce38c9b7e2e1701dddedf6bbb;hb=a81bf3f3ef24c8b6d66aea1038f7a16a382ff375;hpb=37e0c30d9075a35780a945a462913165d973c372

diff --git a/contrib/visualize-alignment/README b/contrib/visualize-alignment/README
index a81c92a..6c30f94 100644
--- a/contrib/visualize-alignment/README
+++ b/contrib/visualize-alignment/README
@@ -1,14 +1,30 @@
+This directory contains some experimental work for capturing traces of
+block device operations while filesystem operations are performed.
+
+You can trace any operation that libguestfs supports, including
+partitioning, mkfs, LVM operations, and filesystem operations.  You
+can enable and disable tracing in order to capture single operations
+such as a single write, or groups of operations.  You can examine the
+traces by hand (as text files) or turn them into graphical
+visualizations.
+
+IMPORTANT NOTE: This is not upstream (in qemu) nor integrated into
+libguestfs.  We should probably be using the 'blktrace' command
+instead, or if that is not suitable, get a more reliable and useful
+trace mechanism added to qemu (the current patch is not suitable for
+upstreaming).
+
 The *.qtr files are qemu trace files, produced using the unofficial
-patch in the current directory.
+qemu patch in the current directory.
 
 - guestfish-N-fs-10M.qtr
 
-  The command 'guestfish -N fs:ext2:10' before we modified the
+  The command 'guestfish -N fs:ext2:10M' before we modified the
   part-disk API to align the partition to 64 sectors.
 
 - guestfish-N-fs-10M-aligned-part-disk.qtr
 
-  The command 'guestfish -N fs:ext2:10' after we modified the
+  The command 'guestfish -N fs:ext2:10M' after we modified the
   part-disk API to align the partition to 64 sectors.
 
 - guestfish-add-mount.qtr
@@ -18,5 +34,37 @@ patch in the current directory.
 
 - guestfish-write-hello.qtr
 
-  $ guestfish -a test1.img -m /dev/sda1 write /hello "hello, world."
-  Note that the trace includes the adding and mounting operations.
+  $ guestfish -a test1.img -m /dev/sda1 \
+      debug qtrace "/dev/vda on" : \
+      write /hello "hello, world." : \
+      debug qtrace "/dev/vda off"
+  where test1.img was created by the command above.
+
+  This is just the creation of a new file with a small amount of content.
+
+  Within this trace file, the qtrace on/off commands appear as patterns
+  of reads.  For on: 2, 21, 15, 2.  For off: 2, 15, 21, 2.
+
+- guestfish-lv-ext4-4k.qtr
+
+  $ guestfish \
+      alloc test1.img 40M : \
+      run : \
+      part-disk /dev/vda mbr : \
+      pvcreate /dev/vda : \
+      vgcreate VG /dev/vda : \
+      lvcreate LV VG 32 : \
+      mkfs-b ext4 4096 /dev/VG/LV
+
+  Some points to note:
+    * an ext4 filesystem, so it has a journal and extents
+    * 4K block size, so we expect writes to be aligned
+    * located inside an LV, so more realistic
+
+- guestfish-lv-ext4-4k-write-hello.qtr
+
+  $ guestfish -a test1.img -m /dev/VG/LV \
+      debug qtrace "/dev/vda on" : \
+      write /hello "hello, world." : \
+      debug qtrace "/dev/vda off"
+  where test1.img was created by the previous command.