docs/userguide/collectd.userguide.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3 .. (c) OPNFV, Intel Corporation and others.
   4
   5 collectd plugins
   6 =================
   7 Barometer has enabled the following collectd plugins:
   8
   9 * dpdkstat plugin: A read plugin that retrieve stats from the DPDK extended
  10    NIC stats API.
  11
  12 * `ceilometer plugin`_: A write plugin that pushes the retrieved stats to
  13   Ceilometer. It's capable of pushing any stats read through collectd to
  14   Ceilometer, not just the DPDK stats.
  15
  16 * hugepages plugin:  A read plugin that retrieves the number of available
  17   and free hugepages on a platform as well as what is available in terms of
  18   hugepages per socket.
  19
  20 * RDT plugin: A read plugin that provides the last level cache utilitzation and
  21   memory bandwidth utilization
  22
  23 * Open vSwitch events Plugin: A read plugin that retrieves events from OVS.
  24
  25 All the plugins above are available on the collectd master, except for the
  26 ceilometer plugin as it's a python based plugin and only C plugins are accepted
  27 by the collectd community. The ceilometer plugin lives in the OpenStack
  28 repositories.
  29
  30 Other plugins under development or existing as a pull request into collectd master:
  31
  32 * dpdkevents:  A read plugin that retrieves DPDK link status and DPDK
  33   forwarding cores liveliness status (DPDK Keep Alive).
  34
  35 * Open vSwitch stats Plugin: A read plugin that retrieve flow and interface
  36   stats from OVS.
  37
  38 * mcelog plugin: A read plugin that uses mcelog client protocol to check for
  39   memory Machine Check Exceptions and sends the stats for reported exceptions.
  40
  41 * SNMP write: A write plugin that will act as a SNMP subagent and will map
  42   collectd metrics to relavent OIDs. Will only support SNMP: get, getnext and
  43   walk.
  44
  45 * Legacy/IPMI: A read plugin that will report platform thermals, voltages,
  46   fanspeed....
  47
  48 Building collectd with the Barometer plugins and installing the dependencies
  49 =============================================================================
  50
  51 All plugins
  52 -----------
  53 The plugins that have been merged to the baromter master branch can all be
  54 built and configured through the barometer repository.
  55
  56 **Note**: sudo permissions are required to install collectd.
  57
  58 **Note**: These are instructions for Ubuntu 16.04.
  59
  60 To build and install these dependencies, clone the barometer repo:
  61
  62 .. code:: c
  63
  64     $ git clone https://gerrit.opnfv.org/gerrit/barometer
  65
  66 Install the build dependencies
  67
  68 .. code:: bash
  69
  70     $ ./src/install_build_deps.sh
  71
  72 To install collectd as a service and install all it's dependencies:
  73
  74 .. code:: bash
  75
  76     $ cd barometer/src && sudo make && sudo make install
  77
  78 This will install collectd as a service and the base install directory
  79 is /opt/collectd.
  80
  81 Sample configuration files can be found in '/opt/collectd/etc/collectd.conf.d'
  82
  83 Please note if you are using any Open vSwitch plugins you need to run:
  84
  85 .. code:: bash
  86
  87     $ sudo ovs-vsctl set-manager ptcp:6640
  88
  89 DPDK statistics plugin
  90 -----------------------
  91 Repo: https://github.com/collectd/collectd
  92 Branch: master
  93 Dependencies: DPDK (http://dpdk.org/)
  94
  95 To build and install DPDK to /usr please see:
  96 https://github.com/collectd/collectd/blob/master/docs/BUILD.dpdkstat.md
  97
  98 Building and installing collectd:
  99
 100 .. code:: bash
 101
 102     $ git clone https://github.com/collectd/collectd.git
 103     $ cd collectd
 104     $ ./build.sh
 105     $ ./configure --enable-syslog --enable-logfile --enable-debug
 106     $ make
 107     $ sudo make install
 108
 109
 110 This will install collectd to /opt/collectd
 111 The collectd configuration file can be found at /opt/collectd/etc
 112 To configure the hugepages plugin you need to modify the configuration file to
 113 include:
 114
 115 .. code:: bash
 116
 117     LoadPlugin dpdkstat
 118     <Plugin dpdkstat>
 119            Coremask "0xf"
 120            ProcessType "secondary"
 121            FilePrefix "rte"
 122            EnabledPortMask 0xffff
 123     </Plugin>
 124
 125 For more information on the plugin parameters, please see:
 126 https://github.com/collectd/collectd/blob/master/src/collectd.conf.pod
 127
 128 Please note if you are configuring collectd with the **static DPDK library**
 129 you must compile the DPDK library with the -fPIC flag:
 130
 131 .. code:: bash
 132
 133     $ make EXTRA_CFLAGS=-fPIC
 134
 135 You must also modify the configuration step when building collectd:
 136
 137 .. code:: bash
 138
 139     $ ./configure CFLAGS=" -lpthread -Wl,--whole-archive -Wl,-ldpdk -Wl,-lm -Wl,-lrt -Wl,-lpcap -Wl,-ldl -Wl,--no-whole-archive"
 140
 141 Please also note that if you are not building and installing DPDK system-wide
 142 you will need to specify the specific paths to the header files and libraries
 143 using LIBDPDK_CPPFLAGS and LIBDPDK_LDFLAGS. You will also need to add the DPDK
 144 library symbols to the shared library path using ldconfig. Note that this
 145 update to the shared library path is not persistant (i.e. it will not survive a
 146 reboot). Pending a merge of https://github.com/collectd/collectd/pull/2073.
 147
 148 .. code:: bash
 149
 150     $ ./configure LIBDPDK_CPPFLAGS="path to DPDK header files" LIBDPDK_LDFLAGS="path to DPDK libraries"
 151
 152
 153 Hugepages Plugin
 154 -----------------
 155 Repo: https://github.com/collectd/collectd
 156 Branch: master
 157 Dependencies: None, but assumes hugepages are configured.
 158
 159 To configure some hugepages:
 160
 161 .. code:: bash
 162
 163    sudo mkdir -p /mnt/huge
 164    sudo mount -t hugetlbfs nodev /mnt/huge
 165    sudo echo 14336 > /sys/devices/system/node/node0/hugepages/hugepages-2048kB/nr_hugepages
 166
 167 Building and installing collectd:
 168
 169 .. code:: bash
 170
 171     $ git clone https://github.com/collectd/collectd.git
 172     $ cd collectd
 173     $ ./build.sh
 174     $ ./configure --enable-syslog --enable-logfile --enable-hugepages --enable-debug
 175     $ make
 176     $ sudo make install
 177
 178 This will install collectd to /opt/collectd
 179 The collectd configuration file can be found at /opt/collectd/etc
 180 To configure the hugepages plugin you need to modify the configuration file to
 181 include:
 182
 183 .. code:: bash
 184
 185     LoadPlugin hugepages
 186     <Plugin hugepages>
 187         ReportPerNodeHP  true
 188         ReportRootHP     true
 189         ValuesPages      true
 190         ValuesBytes      false
 191         ValuesPercentage false
 192     </Plugin>
 193
 194 For more information on the plugin parameters, please see:
 195 https://github.com/collectd/collectd/blob/master/src/collectd.conf.pod
 196
 197 Intel RDT Plugin
 198 -----------------
 199 Repo: https://github.com/collectd/collectd
 200 Branch: master
 201 Dependencies:
 202
 203   * PQoS/Intel RDT library https://github.com/01org/intel-cmt-cat.git
 204   * msr kernel module
 205
 206 Building and installing PQoS/Intel RDT library:
 207
 208 .. code:: bash
 209
 210     $ git clone https://github.com/01org/intel-cmt-cat.git
 211     $ cd intel-cmt-cat.git
 212     $ make
 213     $ make install PREFIX=/usr
 214
 215 Building and installing collectd:
 216
 217 .. code:: bash
 218
 219     $ git clone https://github.com/collectd/collectd.git
 220     $ cd collectd
 221     $ ./build.sh
 222     $ ./configure --enable-syslog --enable-logfile --with-libpqos=/usr/ --enable-debug
 223     $ make
 224     $ sudo make install
 225
 226 This will install collectd to /opt/collectd
 227 The collectd configuration file can be found at /opt/collectd/etc
 228 To configure the RDT plugin you need to modify the configuration file to
 229 include:
 230
 231 .. code:: bash
 232
 233     <LoadPlugin intel_rdt>
 234       Interval 1
 235     </LoadPlugin>
 236     <Plugin "intel_rdt">
 237       Cores ""
 238     </Plugin>
 239
 240 For more information on the plugin parameters, please see:
 241 https://github.com/collectd/collectd/blob/master/src/collectd.conf.pod
 242
 243 Installing collectd as a service
 244 --------------------------------
 245 Collectd service scripts are available in the collectd/contrib directory.
 246 To install collectd as a service:
 247
 248 .. code:: bash
 249
 250     $ sudo cp contrib/systemd.collectd.service /etc/systemd/system/
 251     $ cd /etc/systemd/system/
 252     $ sudo mv systemd.collectd.service collectd.service
 253     $ sudo chmod +x collectd.service
 254
 255 Modify collectd.service
 256
 257 .. code:: bash
 258
 259     [Service]
 260     ExecStart=/opt/collectd/sbin/collectd
 261     EnvironmentFile=-/opt/collectd/etc/
 262     EnvironmentFile=-/opt/collectd/etc/
 263     CapabilityBoundingSet=CAP_SETUID CAP_SETGID
 264
 265 Reload
 266
 267 .. code:: bash
 268
 269     $ sudo systemctl daemon-reload
 270     $ sudo systemctl start collectd.service
 271     $ sudo systemctl status collectd.service should show success
 272
 273 Additional useful plugins
 274 --------------------------
 275 Exec Plugin
 276 ~~~~~~~~~~~
 277 Can be used to show you when notifications are being generated by calling a
 278 bash script that dumps notifications to file. (handy for debug). Modify
 279 /opt/collectd/etc/collectd.conf:
 280
 281 .. code:: bash
 282
 283    LoadPlugin exec
 284    <Plugin exec>
 285    #   Exec "user:group" "/path/to/exec"
 286       NotificationExec "user" "<path to barometer>/barometer/src/collectd/collectd_sample_configs/write_notification.sh"
 287    </Plugin>
 288
 289 write_notification.sh (just writes the notification passed from exec through
 290 STDIN to a file (/tmp/notifications)):
 291
 292 .. code:: bash
 293
 294    #!/bin/bash
 295    rm -f /tmp/notifications
 296    while read x y
 297    do
 298      echo $x$y >> /tmp/notifications
 299    done
 300
 301 output to /tmp/notifications should look like:
 302
 303 .. code:: bash
 304
 305     Severity:WARNING
 306     Time:1479991318.806
 307     Host:localhost
 308     Plugin:ovs_events
 309     PluginInstance:br-ex
 310     Type:gauge
 311     TypeInstance:link_status
 312     uuid:f2aafeec-fa98-4e76-aec5-18ae9fc74589
 313
 314     linkstate of "br-ex" interface has been changed to "DOWN"
 315
 316 logfile plugin
 317 ~~~~~~~~~~~~~~~
 318 Can be used to log collectd activity. Modify /opt/collectd/etc/collectd.conf to
 319 include:
 320
 321 .. code:: bash
 322
 323     LoadPlugin logfile
 324     <Plugin logfile>
 325         LogLevel info
 326         File "/var/log/collectd.log"
 327         Timestamp true
 328         PrintSeverity false
 329     </Plugin>
 330
 331 Monitoring Interfaces and Openstack Support
 332 -------------------------------------------
 333 .. Figure:: monitoring_interfaces.png
 334
 335    Monitoring Interfaces and Openstack Support
 336
 337 The figure above shows the DPDK L2 forwarding application running on a compute
 338 node, sending and receiving traffic. collectd is also running on this compute
 339 node retrieving the stats periodically from DPDK through the dpdkstat plugin
 340 and publishing the retrieved stats to Ceilometer through the ceilometer plugin.
 341
 342 To see this demo in action please checkout: `Barometer OPNFV Summit demo`_
 343
 344 References
 345 ----------
 346 [1] https://collectd.org/wiki/index.php/Naming_schema
 347 [2] https://github.com/collectd/collectd/blob/master/src/daemon/plugin.h
 348 [3] https://collectd.org/wiki/index.php/Value_list_t
 349 [4] https://collectd.org/wiki/index.php/Data_set
 350 [5] https://collectd.org/documentation/manpages/types.db.5.shtml
 351 [6] https://collectd.org/wiki/index.php/Data_source
 352 [7] https://collectd.org/wiki/index.php/Meta_Data_Interface
 353
 354 .. _Barometer OPNFV Summit demo: https://prezi.com/kjv6o8ixs6se/software-fastpath-service-quality-metrics-demo/
 355 .. _ceilometer plugin: https://github.com/openstack/collectd-ceilometer-plugin/tree/stable/mitaka