Skip to content

Commit 1e3f8a8

Browse files
djs55djs55
committed
Merge pull request #73 from djs55/rrds
Fix the description of RRDs
2 parents 143fbda + 61e2f1d commit 1e3f8a8

File tree

1 file changed

+177
-65
lines changed

1 file changed

+177
-65
lines changed

‎xen-api/metrics.md‎

Lines changed: 177 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -3,111 +3,223 @@ title: Metrics
33
layout: default
44
---
55

6-
Getting XenServer Performance Statistics
7-
---------------------------------------------
8-
9-
XenServer records statistics about the performance of various
10-
aspects of your XenServer installation. The metrics are stored
6+
[xcp-rrdd](https://github.com/xapi-project/xcp-rrdd)
7+
records statistics about the host and the VMs running on top.
8+
The metrics are stored
119
persistently for long term access and analysis of historical trends.
12-
Where storage is available to a VM, the statistics are written to disk
13-
when a VM is shut down. Statistics are stored in RRDs (Round Robin
14-
Databases), which are maintained for individual VMs (including the
15-
control domain) and the server. RRDs are resident on the server on which
10+
Statistics are stored in
11+
[RRDs](http://oss.oetiker.ch/rrdtool/)
12+
(Round Robin Databases).
13+
RRDs are fixed-size structures containing data at multiple resolutions.
14+
'Data sources' are sampled every few seconds and points are added to
15+
the highest resolution RRD. Periodically each high-frequency RRD is
16+
'consolidated' (e.g. averaged) to produce a data point for a lower-frequency RRD.
17+
18+
RRDs are resident on the server on which
1619
the VM is running, or the pool master when the VM is not running. The
1720
RRDs are also backed up every day.
1821

19-
> **Warning**
20-
>
21-
> In earlier versions of the XenServer API, instantaneous
22-
> performance metrics could be obtained using the `VM_metrics`,
23-
> `VM_guest_metrics`, `host_metrics` methods and associated methods.
24-
> These methods has been deprecated in favor of using the http handler
25-
> described in this chapter to download the statistics from the RRDs on
26-
> the VMs and servers. Note that by default the legacy metrics will
27-
> return zeroes. To revert to periodic statistical polling as present in
28-
> earlier versions of XenServer, set the
29-
> `other-config:rrd_update_interval=` parameters on your host to one of
30-
> the following values, and restart your host:
31-
>
32-
> never
33-
> : This is the default, meaning no periodic polling is performed.
34-
>
35-
> 1
36-
> : Polling is performed every 5 seconds.
37-
>
38-
> 2
39-
> : Polling is performed every minute.
40-
>
41-
> By default, the older metrics APIs will not return any values, and so
42-
> this key must be enabled to run monitoring clients which use the
43-
> legacy monitoring protocol.
22+
Granularity
23+
-----------
4424

4525
Statistics are persisted for a maximum of one year, and are stored at
4626
different granularities. The average and most recent values are stored
4727
at intervals of:
4828

4929
- 5 seconds for the past 10 minutes
50-
5130
- one minute for the past 2 hours
52-
5331
- one hour for the past week
54-
5532
- one day for the past year
5633

5734
RRDs are saved to disk as uncompressed XML. The size of each RRD when
5835
written to disk ranges from 200KiB to approximately 1.2MiB when the RRD
5936
stores the full year of statistics.
6037

61-
> **Warning**
62-
>
63-
> If statistics cannot be written to disk, for example when a disk is
64-
> full, statistics will be lost and the last saved version of the RRD
65-
> will be used.
38+
By default each RRD contains only averaged data to save storage space.
39+
To record minimum and maximum values in future RRDs, set the Pool-wide flag
40+
41+
```sh
42+
xe pool-param-set uuid= other-config:create_min_max_in_new_VM_RRDs=true
43+
```
44+
45+
Downloading
46+
===========
6647

6748
Statistics can be downloaded over HTTP in XML format, for example using
68-
`wget`. See [](http://oss.oetiker.ch/rrdtool/doc/rrddump.en.html) and
69-
[](http://oss.oetiker.ch/rrdtool/doc/rrdxport.en.html) for information
49+
`wget`. See [rrddump](http://oss.oetiker.ch/rrdtool/doc/rrddump.en.html) and
50+
[rrdxport](http://oss.oetiker.ch/rrdtool/doc/rrdxport.en.html) for information
7051
about the XML format. HTTP authentication can take the form of a
7152
username and password or a session token. Parameters are appended to the
7253
URL following a question mark (?) and separated by ampersands (&).
7354

55+
Statistics may be downloaded all at once, including all history, or as
56+
deltas suitable for interactive graphing.
57+
58+
Downloading statistics all at once
59+
----------------------------------
60+
61+
To obtain a full dump of RRD data for a host use:
62+
63+
```sh
64+
wget http://user:password@host/host_rrd
65+
```
66+
67+
The RRD data is in the XML export format used by rrdtool and looks like this:
68+
69+
```xml
70+
<?xml version="1.0"?>
71+
<rrd>
72+
<version>0003</version>
73+
<step>5</step>
74+
<lastupdate>1213616574</lastupdate>
75+
<ds>
76+
<name>memory_total_kib</name>
77+
<type>GAUGE</type>
78+
<minimal_heartbeat>300.0000</minimal_heartbeat>
79+
<min>0.0</min>
80+
<max>Infinity</max>
81+
<last_ds>2070172</last_ds>
82+
<value>9631315.6300</value>
83+
<unknown_sec>0</unknown_sec>
84+
</ds>
85+
<ds>
86+
<!-- other dss - the order of the data sources is important
87+
and defines the ordering of the columns in the archives below -->
88+
</ds>
89+
<rra>
90+
<cf>AVERAGE</cf>
91+
<pdp_per_row>1</pdp_per_row>
92+
<params>
93+
<xff>0.5000</xff>
94+
</params>
95+
<cdp_prep> <!-- This is for internal use -->
96+
<ds>
97+
<primary_value>0.0</primary_value>
98+
<secondary_value>0.0</secondary_value>
99+
<value>0.0</value>
100+
<unknown_datapoints>0</unknown_datapoints>
101+
</ds>
102+
...other dss - internal use only...
103+
</cdp_prep>
104+
<database>
105+
<row>
106+
<v>2070172.0000</v> <!-- columns correspond to the DSs defined above -->
107+
<v>1756408.0000</v>
108+
<v>0.0</v>
109+
<v>0.0</v>
110+
<v>732.2130</v>
111+
<v>0.0</v>
112+
<v>782.9186</v>
113+
<v>0.0</v>
114+
<v>647.0431</v>
115+
<v>0.0</v>
116+
<v>0.0001</v>
117+
<v>0.0268</v>
118+
<v>0.0100</v>
119+
<v>0.0</v>
120+
<v>615.1072</v>
121+
</row>
122+
...
123+
</rra>
124+
... other archives ...
125+
</rrd>
126+
127+
```
128+
129+
To obtain a full dump of RRD data of a VM with uuid `x`:
130+
131+
```sh
132+
wget http://user:password@host/vm_rrd?uuid=x
133+
```
134+
135+
Note that it is quite expensive to download full RRDs as they contain
136+
lots of historical information. For interactive displays clients should
137+
download deltas instead.
138+
139+
140+
Downloading deltas
141+
------------------
142+
74143
To obtain an update of all VM statistics on a host, the URL would be of
75144
the form:
76145

77-
http://:@/rrd_updates?start=
146+
```sh
147+
wget http://user:password@host/rrd_updates?start=<secondsinceepoch>
148+
```
78149

79150
This request returns data in an rrdtool `xport` style XML format, for
80-
every VM resident on the particular host that is being queried. To
151+
every VM resident on the particular host that is being queried.
152+
To
81153
differentiate which column in the export is associated with which VM,
82154
the `legend` field is prefixed with the UUID of the VM.
83155

156+
An example `rrd_updates` output:
157+
158+
```xml
159+
<xport>
160+
<meta>
161+
<start>1213578000</start>
162+
<step>3600</step>
163+
<end>1213617600</end>
164+
<rows>12</rows>
165+
<columns>12</columns>
166+
<legend>
167+
<entry>AVERAGE:vm:ecd8d7a0-1be3-4d91-bd0e-4888c0e30ab3:cpu1</entry> <!-- nb - each data source might have multiple entries for different consolidation functions -->
168+
<entry>AVERAGE:vm:ecd8d7a0-1be3-4d91-bd0e-4888c0e30ab3:cpu0</entry>
169+
<entry>AVERAGE:vm:ecd8d7a0-1be3-4d91-bd0e-4888c0e30ab3:memory</entry>
170+
<entry>MIN:vm:ecd8d7a0-1be3-4d91-bd0e-4888c0e30ab3:cpu1</entry>
171+
<entry>MIN:vm:ecd8d7a0-1be3-4d91-bd0e-4888c0e30ab3:cpu0</entry>
172+
<entry>MIN:vm:ecd8d7a0-1be3-4d91-bd0e-4888c0e30ab3:memory</entry>
173+
<entry>MAX:vm:ecd8d7a0-1be3-4d91-bd0e-4888c0e30ab3:cpu1</entry>
174+
<entry>MAX:vm:ecd8d7a0-1be3-4d91-bd0e-4888c0e30ab3:cpu0</entry>
175+
<entry>MAX:vm:ecd8d7a0-1be3-4d91-bd0e-4888c0e30ab3:memory</entry>
176+
<entry>LAST:vm:ecd8d7a0-1be3-4d91-bd0e-4888c0e30ab3:cpu1</entry>
177+
<entry>LAST:vm:ecd8d7a0-1be3-4d91-bd0e-4888c0e30ab3:cpu0</entry>
178+
<entry>LAST:vm:ecd8d7a0-1be3-4d91-bd0e-4888c0e30ab3:memory</entry>
179+
</legend>
180+
</meta>
181+
<data>
182+
<row>
183+
<t>1213617600</t>
184+
<v>0.0</v> <!-- once again, the order or the columns is defined by the legend above -->
185+
<v>0.0282</v>
186+
<v>209715200.0000</v>
187+
<v>0.0</v>
188+
<v>0.0201</v>
189+
<v>209715200.0000</v>
190+
<v>0.0</v>
191+
<v>0.0445</v>
192+
<v>209715200.0000</v>
193+
<v>0.0</v>
194+
<v>0.0243</v>
195+
<v>209715200.0000</v>
196+
</row>
197+
...
198+
</data>
199+
</xport>
200+
```
201+
202+
84203
To obtain host updates too, use the query parameter `host=true`:
85204

86-
http://:@/rrd_updates?start=&host=true
205+
```sh
206+
wget http://user:password@host/rrd_updates?start=<secondssinceepoch>&host=true
207+
```
87208

88209
The step will decrease as the period decreases, which means that if you
89210
request statistics for a shorter time period you will get more detailed
90211
statistics.
91212

92-
**Additional rrd\_updates parameters**
93-
94-
cf=ave|min|max
95-
: the data consolidation mode
96-
97-
interval=interval
98-
: the interval between values to be reported
99-
100-
> **Note**
101-
>
102-
> By default only `ave` statistics are available. To obtain `min` and
103-
> `max` statistics for a VM, run the following command:
104-
>
105-
> xe pool-param-set uuid= other-config:create_min_max_in_new_VM_RRDs
213+
To download updates containing only the averages, or minimums or maximums,
214+
add the parameter `cf=AVERAGE|MIN|MAX` (note case is important) e.g.
106215

107-
To obtain all statistics for a host:
216+
```sh
217+
wget http://user:password@host/rrd_updates?start=0&cf=MAX
218+
```
108219

109-
http:///host_rrd
220+
To request a different update interval, add the parameter `interval=seconds` e.g.
110221

111-
To obtain all statistics for a VM:
112222

113-
http:///vm_rrd?uuid=
223+
```sh
224+
wget http://user:password@host/rrd_updates?start=0&interval=5
225+
```

0 commit comments

Comments
 (0)