+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
- 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-opts ext4 /dev/VG/LV blocksize:4096
+
+ 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.