Merge branch 'collectd-5.8'
[collectd.git] / docs / README.virt.md
1 Inside the virt plugin
2 ======================
3
4 Originally written: 20161111
5
6 Last updated: 20161124
7
8 This document will explain the new domain tag support introduced
9 in the virt plugin, and will provide one important use case for this feature.
10 In the reminder of this document, we consider
11
12 * libvirt <= 2.0.0
13 * QEMU <= 2.6.0
14
15
16 Domain tags and domains partitioning across virt reader instances
17 -----------------------------------------------------------------
18
19 The virt plugin gained the `Instances` option. It allows to start
20 more than one reader instance, so the the libvirt domains could be queried
21 by more than one reader thread.
22 The default value for `Instances` is `1`.
23 With default settings, the plugin will behave in a fully transparent,
24 backward compatible way.
25 It is recommended to set this value to one multiple of the
26 daemon `ReadThreads` value.
27
28 Each reader instance will query only a subset of the libvirt domain.
29 The subset is identified as follows:
30
31 1. Each virt reader instance is named `virt-$NUM`, where `NUM` is
32    the progressive order of instances. If you configure `Instances 3`
33    you will have `virt-0`, `virt-1`, `virt-2`. Please note: the `virt-0`
34    instance is special, and will always be available.
35 2. Each virt reader instance will iterate over all the libvirt active domains,
36    and will look for one `tag` attribute (see below) in the domain metadata section.
37 3. Each virt reader instance will take care *only* of the libvirt domains whose
38    tag matches with its own
39 4. The special `virt-0` instance will take care of all the libvirt domains with
40    no tags, or with tags which are not in the set \[virt-0 ... virt-$NUM\]
41
42 Collectd will just use the domain tags, but never enforces or requires them.
43 It is up to an external entity, like a software management system,
44 to attach and manage the tags to the domain.
45
46 Please note that unless you have such tag-aware management sofware,
47 it most likely make no sense to enable more than one reader instance on your
48 setup.
49
50
51 Libvirt tag metadata format
52 ----------------------------
53
54 This is the snipped to be added to libvirt domains:
55
56     <ovirtmap:tag xmlns:ovirtmap="http://ovirt.org/ovirtmap/tag/1.0">
57       $TAG
58     </ovirtmap:tag>
59
60 it must be included in the <metadata> section.
61
62 Check the `src/virt_test.c` file for really minimal example of libvirt domains.
63
64
65 Examples
66 --------
67
68 ### Example one: 10 libvirt domains named "domain-A" ... "domain-J", virt plugin with instances=5, using 5 different tags
69
70
71     libvirt domain name -    tag    - read instance - reason
72     domain-A                virt-0         0          tag match
73     domain-B                virt-1         1          tag match
74     domain-C                virt-2         2          tag match
75     domain-D                virt-3         3          tag match
76     domain-E                virt-4         4          tag match
77     domain-F                virt-0         0          tag match
78     domain-G                virt-1         1          tag match
79     domain-H                virt-2         2          tag match
80     domain-I                virt-3         3          tag match
81     domain-J                virt-4         4          tag match
82
83
84   Because the domain where properly tagged, all the read instances have even load. Please note that the the virt plugin
85   knows nothing, and should know nothing, about *how* the libvirt domain are tagged. This is entirely up to the
86   management system.
87
88
89 Example two: 10 libvirt domains named "domain-A" ... "domain-J", virt plugin with instances=3, using 5 different tags
90
91
92     libvirt domain name -    tag    - read instance - reason
93     domain-A                virt-0         0          tag match
94     domain-B                virt-1         1          tag match
95     domain-C                virt-2         2          tag match
96     domain-D                virt-3         0          adopted by instance #0
97     domain-E                virt-4         0          adopted by instance #0
98     domain-F                virt-0         0          rag match
99     domain-G                virt-1         1          tag match
100     domain-H                virt-2         2          tag match
101     domain-I                virt-3         0          adopted by instance #0
102     domain-J                virt-4         0          adopted by instance #0
103
104
105   In this case we have uneven load, but no domain is ignored.
106
107
108 ### Example three: 10 libvirt domains named "domain-A" ... "domain-J", virt plugin with instances=5, using 3 different tags
109
110
111     libvirt domain name -    tag    - read instance - reason
112     domain-A                virt-0         0          tag match
113     domain-B                virt-1         1          tag match
114     domain-C                virt-2         2          tag match
115     domain-D                virt-0         0          tag match
116     domain-E                virt-1         1          tag match
117     domain-F                virt-2         2          tag match
118     domain-G                virt-0         0          tag match
119     domain-H                virt-1         1          tag match
120     domain-I                virt-2         2          tag match
121     domain-J                virt-0         0          tag match
122
123
124   Once again we have uneven load and two idle read instances, but besides that no domain is left unmonitored
125
126
127 ### Example four: 10 libvirt domains named "domain-A" ... "domain-J", virt plugin with instances=5, partial tagging
128
129
130     libvirt domain name -    tag    - read instance - reason
131     domain-A                virt-0         0          tag match
132     domain-B                virt-1         1          tag match
133     domain-C                virt-2         2          tag match
134     domain-D                virt-0         0          tag match
135     domain-E                               0          adopted by instance #0
136     domain-F                               0          adopted by instance #0
137     domain-G                               0          adopted by instance #0
138     domain-H                               0          adopted by instance #0
139     domain-I                               0          adopted by instance #0
140     domain-J                               0          adopted by instance #0
141
142
143 The lack of tags causes uneven load, but no domain are unmonitored.
144
145
146 Possible extensions - custom tag format
147 ---------------------------------------
148
149 The aformentioned approach relies on fixed tag format, `virt-$N`. The algorithm works fine with any tag, which
150 is just one string, compared for equality. However, using custom strings for tags creates the need for a mapping
151 between tags and the read instances.
152 This mapping needs to be updated as long as domain are created or destroyed, and the virt plugin needs to be
153 notified of the changes.
154
155 This adds a significant amount of complexity, with little gain with respect to the fixed schema adopted initially.
156 For this reason, the introdution of dynamic, custom mapping was not implemented.
157
158
159 Dealing with datacenters: libvirt, qemu, shared storage
160 -------------------------------------------------------
161
162 When used in a datacenter, QEMU is most often configured to use shared storage. This is
163 the default configuration of datacenter management solutions like [oVirt](http://www.ovirt.org).
164 The actual shared storage could be implemented on top of NFS for small installations, or most likely
165 ISCSI or Fiber Channel. The key takeaway is that the storage is accessed over the network,
166 not using e.g. the SATA or PCI bus of any given host, so any network issue could cause
167 one or more storage operations to delay, or to be lost entirely.
168
169 In that case, the userspace process that requested the operation can end up in the D state,
170 and become unresponsive, and unkillable.
171
172
173 Dealing with unresponsive domains
174 ---------------------------------
175
176 All the above considered, one robust management or monitoring application must deal with the fact that
177 the libvirt API can block for a long time, or forever. This is not an issue or a bug of one specific
178 API, but it is rather a byproduct of how libvirt and QEMU interact.
179
180 Whenever we query more than one VM, we should take care to avoid that one blocked VM prevent other,
181 well behaving VMs to be queried. We don't want one rogue VM to disrupt well-behaving VMs.
182 Unfortunately, any way we enumerate VMs, either implicitely, using the libvirt bulk stats API,
183 or explicitely, listing all libvirt domains and query each one in turn, we may unpredictably encounter
184 one unresponsive VM.
185
186 There are many possible approaches to deal with this issue. The virt plugin supports
187 a simple but effective approach partitioning the domains, as follows.
188
189 1. The virt plugin always register one or more `read` callbacks. The `zero` read callback is guaranteed to
190    be always present, so it performs special duties (more details later)
191    Each callback will be named 'virt-$N', where `N` ranges from 0 (zero) to M-1, where M is the number of instances configured.
192    `M` equals to `5` by default, because this is the same default number of threads in the libvirt worker pool.
193 2. Each of the read callbacks queries libvirt for the list of all the active domains, and retrieves the libvirt domain metadata.
194    Both of those operations are safe wrt domain blocked in I/O (they affect only the libvirtd daemon).
195 3. Each of the read callbacks extracts the `tag` from the domain metadata using a well-known format (see below).
196    Each of the read callbacks discards any domain which has no tag, or whose tag doesn't match with the read callback tag.
197 3.a. The read callback tag equals to the read callback name, thus `virt-$N`. Remember that `virt-0` is guaranteed to be
198      always present.
199 3.b. Since the `virt-0` reader is always present, it will take care of domains with no tag, or with unrecognized tag.
200      One unrecognized tag is any tag which has not the scheme `virt-$N`.
201 4. Each read callback only samples the subset of domains with matching tag. The `virt-0` reader will possibly do more,
202    but worst case the load will be unbalanced, no domain will be left unsampled.
203
204 To make this approach work, some entity must attach the tags to the libvirt domains, in such a way that all
205 the domains which run on a given host and insist on the same network-based storage share the same tag.
206 This minimizes the disruption, because when using the shared storage, if one domain becomes unresponsive because
207 of unavailable storage, the most likely thing to happen is that others domain using the same storage will soon become
208 unavailable; should the box run other libvirt domains using other network-based storage, they could be monitored
209 safely.
210
211 In case of [oVirt](http://www.ovirt.org), the aforementioned tagging is performed by the host agent.
212
213 Please note that this approach is ineffective if the host completely lose network access to the storage network.
214 In this case, however, no recovery is possible and no damage limitation is possible.
215
216 Lastly, please note that if the virt plugin is configured with instances=1, it behaves exactly like before.
217
218
219 Addendum: high level overview: libvirt client, libvirt daemon, qemu
220 --------------------------------------------------------------------
221
222 Let's review how the client application (collectd + virt plugin), the libvirtd daemon and the
223 QEMU processes interact with each other.
224
225 The libvirt daemon talks to QEMU using the JSON QMP protcol over one unix domain socket.
226 The details of the protocol are not important now, but the key part is that the protocol
227 is a simple request/response, meaning that libvirtd must serialize all the interactions
228 with the QEMU monitor, and must protects its endpoint with a lock.
229 No out of order request/responses are possible (e.g. no pipelining or async replies).
230 This means that if for any reason one QMP request could not be completed, any other caller
231 trying to access the QEMU monitor will block until the blocked caller returns.
232
233 To retrieve some key informations, most notably about the block device state or the balloon
234 device state, the libvirtd daemon *must* use the QMP protocol.
235
236 The QEMU core, including the handling of the QMP protocol, is single-threaded.
237 All the above combined make it possible for a client to block forever waiting for one QMP
238 request, if QEMU itself is blocked. The most likely cause of block is I/O, and this is especially
239 true considering how QEMU is used in a datacenter.
240