summaryrefslogtreecommitdiffstats
path: root/docs/release/userguide/collectd.ves.userguide.rst
blob: 7ed6be9e9a4fc6d09e5acf7e47c1c4ee2cb0148b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
.. This work is licensed under a Creative Commons Attribution 4.0 International License.
.. http://creativecommons.org/licenses/by/4.0
.. (c) OPNFV, Intel Corporation and others.

==============================
collectd VES plugin User Guide
==============================
The Barometer repository contains a python based write plugin for VES.

The plugin currently supports pushing platform relevant metrics through the
additional measurements field for VES.

**Please note**: Hardcoded configuration values will be modified so that they
are configurable through the configuration file.

Installation Instructions:
--------------------------
1. Clone this repo
2. Install collectd

.. code:: bash

   $ sudo apt-get install collectd

3. Modify the collectd configuration script: `/etc/collectd/collectd.conf`

.. code:: bash

    <LoadPlugin python>
      Globals true
    </LoadPlugin>

    <Plugin python>
      ModulePath "/path/to/your/python/modules"
      LogTraces true
      Interactive false
      Import "ves_plugin"
    <Module ves_plugin>
    # VES plugin configuration (see next section below)
    </Module>
    </Plugin>

where "/path/to/your/python/modules" is the path to where you cloned this repo

VES python plugin configuration description:
--------------------------------------------

**Note** Details of the Vendor Event Listener REST service

REST resources are defined with respect to a ServerRoot:

.. code:: bash

    ServerRoot = https://{Domain}:{Port}/{optionalRoutingPath}

REST resources are of the form:

.. code:: bash

    {ServerRoot}/eventListener/v{apiVersion}`
    {ServerRoot}/eventListener/v{apiVersion}/{topicName}`
    {ServerRoot}/eventListener/v{apiVersion}/eventBatch`

**Domain** *"host"*
  VES domain name. It can be IP address or hostname of VES collector
  (default: `127.0.0.1`)

**Port** *port*
  VES port (default: `30000`)

**Path** *"path"*
  Used as the "optionalRoutingPath" element in the REST path (default: `empty`)

**Topic** *"path"*
  Used as the "topicName" element in the REST  path (default: `empty`)

**UseHttps** *true|false*
  Allow plugin to use HTTPS instead of HTTP (default: `false`)

**Username** *"username"*
  VES collector user name (default: `empty`)

**Password** *"passwd"*
  VES collector password (default: `empty`)

**FunctionalRole** *"role"*
  Used as the 'functionalRole' field of 'commonEventHeader' event (default:
  `Collectd VES Agent`)

**GuestRunning** *true|false*
  This option is used if the collectd is running on a guest machine, e.g this
  option should be set to `true` in this case. Defaults to `false`.

**SendEventInterval** *interval*
  This configuration option controls how often (sec) collectd data is sent to
  Vendor Event Listener (default: `20`)

**ApiVersion** *version*
  Used as the "apiVersion" element in the REST path (default: `1`)

Other collectd.conf configurations
----------------------------------
Please ensure that FQDNLookup is set to false

.. code:: bash

    FQDNLookup   false

Please ensure that the virt plugin is enabled and configured as follows. This configuration
is is required only on a host side ('GuestRunning' = false).

.. code:: bash

    LoadPlugin virt

    <Plugin virt>
            Connection "qemu:///system"
            RefreshInterval 60
            HostnameFormat uuid
    </Plugin>

Please ensure that the cpu plugin is enabled and configured as follows

.. code:: bash

    LoadPlugin cpu

    <Plugin cpu>
        ReportByCpu false
        ValuesPercentage true
    </Plugin>

**Note**: The `ReportByCpu` option should be set to `true` (default) if VES pugin
is running on guest machine ('GuestRunning' = true).

Please ensure that the aggregation plugin is enabled and configured as follows
(required if 'GuestRunning' = true)

.. code:: bash

    LoadPlugin aggregation

    <Plugin aggregation>
        <Aggregation>
                Plugin "cpu"
                Type "percent"
                GroupBy "Host"
                GroupBy "TypeInstance"
                SetPlugin "cpu-aggregation"
                CalculateAverage true
        </Aggregation>
    </Plugin>

If plugin is running on a guest side, it is important to enable uuid plugin
too. In this case the hostname in event message will be represented as UUID
instead of system host name.

.. code:: bash

  LoadPlugin uuid

If custom UUID needs to be provided, the following configuration is required in collectd.conf
file:

.. code:: bash

    <Plugin uuid>
        UUIDFile "/etc/uuid"
    </Plugin>

Where "/etc/uuid" is a file containing custom UUID.

Please also ensure that the following plugins are enabled:

.. code:: bash

    LoadPlugin disk
    LoadPlugin interface
    LoadPlugin memory

VES plugin notification example
-------------------------------

A good example of collectD notification is monitoring of CPU load on a host or guest using
'threshold' plugin. The following configuration will setup VES plugin to send 'Fault'
event every time a CPU idle value is out of range (e.g.: WARNING: CPU-IDLE < 50%, CRITICAL:
CPU-IDLE < 30%) and send 'Fault' NORMAL event if CPU idle value is back to normal.

.. code:: bash

    LoadPlugin threshold

    <Plugin "threshold">
         <Plugin "cpu-aggregation">
            <Type "percent">
              WarningMin    50.0
              WarningMax   100.0
              FailureMin    30.0
              FailureMax   100.0
              Instance "idle"
              Hits 1
            </Type>
        </Plugin>
    </Plugin>

More detailed information on how to configure collectD thresholds(memory, cpu
etc.) can be found here at
https://collectd.org/documentation/manpages/collectd-threshold.5.shtml