From 301e912b2b1bd19f17e9addb26b009f6f67d7f88 Mon Sep 17 00:00:00 2001
From: Florian Forster <octo@collectd.org>
Date: Fri, 28 Oct 2016 13:32:27 +0200
Subject: [PATCH] collectd.conf(5): Improve the "BlockDeviceFormat" and
 "BlockDeviceFormatBasename" sections.

---
 src/collectd.conf.pod | 70 +++++++++++++++++++------------------------
 1 file changed, 31 insertions(+), 39 deletions(-)

diff --git a/src/collectd.conf.pod b/src/collectd.conf.pod
index 64be99e2..761351e4 100644
--- a/src/collectd.conf.pod
+++ b/src/collectd.conf.pod
@@ -7773,8 +7773,6 @@ option is set to 0, refreshing is disabled completely.
 
 =item B<BlockDevice> I<name:dev>
 
-=item B<BlockDeviceFormat> B<source>|B<target>
-
 =item B<InterfaceDevice> I<name:dev>
 
 =item B<IgnoreSelected> B<true>|B<false>
@@ -7800,54 +7798,48 @@ Example:
 Ignore all I<hdb> devices on any domain, but other block devices (eg. I<hda>)
 will be collected.
 
-If I<BlockDeviceFormat> is set to B<target>, then the device names will be the ones
-in the I<target> node for the device in the XML definition of the domain. The
-default is B<target>. This is the behavior before adding the option.
-
-If I<BlockDeviceFormat> is set to B<source>, then the device names will be the ones
-in the I<source> node for the device in the XML definition of the domain.
-
-Example:
-
-If the domain XML have the following device defined:
+=item B<BlockDeviceFormat> B<target>|B<source>
 
-   <disk type='block' device='disk'>
-      <driver name='qemu' type='raw' cache='none' io='native' discard='unmap'/>
-      <source dev='/var/lib/libvirt/images/image1.qcow2'/>
-      <target dev='sda' bus='scsi'/>
-      <boot order='2'/>
-      <address type='drive' controller='0' bus='0' target='0' unit='0'/>
-    </disk>
+If I<BlockDeviceFormat> is set to B<target>, the default, then the device name
+seen by the guest will be used for reporting metrics. 
+This corresponds to the C<E<lt>targetE<gt>> node in the XML definition of the
+domain.
 
-setting 
+If I<BlockDeviceFormat> is set to B<source>, then metrics will be reported
+using the path of the source, e.g. an image file.
+This corresponds to the C<E<lt>sourceE<gt>> node in the XML definition of the
+domain.
 
-	 BlockDeviceFormat target
+B<Example:>
 
-will name the device in the graph as C<sda> 
-
-setting
- 
-	BlockDeviceFormat source
+If the domain XML have the following device defined:
 
-will name the device in the graph as C<var_lib_libvirt_images_image1.qcow2>
+  <disk type='block' device='disk'>
+    <driver name='qemu' type='raw' cache='none' io='native' discard='unmap'/>
+    <source dev='/var/lib/libvirt/images/image1.qcow2'/>
+    <target dev='sda' bus='scsi'/>
+    <boot order='2'/>
+    <address type='drive' controller='0' bus='0' target='0' unit='0'/>
+  </disk>
 
-These names will also be part of the RRD filename.
+Setting C<BlockDeviceFormat target> will cause the I<type instance> to be set
+to C<sda>.
+Setting C<BlockDeviceFormat source> will cause the I<type instance> to be set
+to C<var_lib_libvirt_images_image1.qcow2>.
 
 =item B<BlockDeviceFormatBasename> B<false>|B<true>
 
-I<BlockDeviceFormatBasename> - this option is honored if and only if 
-option I<BlockDeviceFormat> is set to B<source>. If set to B<true> then 
-only the last part of the path will be used for device name and naming the
-RRD file.
-
-Example: 
-
-if the device path (source tag) is: C</var/lib/libvirt/images/image1.qcow2>
+The B<BlockDeviceFormatBasename> controls whether the full path or the
+L<basename(1)> of the source is being used as the I<type instance> when
+B<BlockDeviceFormat> is set to B<source>. Defaults to B<false>.
 
-setting:
-	BlockDeviceFormatBasename true
+B<Example:>
 
-will set the device name to: C<image1.qcow2>
+Assume the device path (source tag) is C</var/lib/libvirt/images/image1.qcow2>.
+Setting C<BlockDeviceFormatBasename false> will cause the I<type instance> to
+be set to C<var_lib_libvirt_images_image1.qcow2>.
+Setting C<BlockDeviceFormatBasename true> will cause the I<type instance> to be
+set to C<image1.qcow2>.
 
 =item B<HostnameFormat> B<name|uuid|hostname|...>
 
-- 
2.30.2