docs/release/userguide/feature.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) <optionally add copywriters name>
   4
   5 ===================================
   6 OPNFV Barometer User Guide
   7 ===================================
   8
   9 .. contents::
  10    :depth: 3
  11    :local:
  12
  13 Barometer collectd plugins description
  14 ---------------------------------------
  15 .. Describe the specific features and how it is realised in the scenario in a brief manner
  16 .. to ensure the user understand the context for the user guide instructions to follow.
  17
  18 collectd is a daemon which collects system performance statistics periodically
  19 and provides a variety of mechanisms to publish the collected metrics. It
  20 supports more than 90 different input and output plugins. Input plugins
  21 retrieve metrics and publish them to the collectd deamon, while output plugins
  22 publish the data they receive to an end point. collectd also has infrastructure
  23 to support thresholding and notification.
  24
  25 Barometer has enabled the following collectd plugins:
  26
  27 * *dpdkstat plugin*: A read plugin that retrieve stats from the DPDK extended
  28    NIC stats API.
  29
  30 * *dpdkevents plugin*:  A read plugin that retrieves DPDK link status and DPDK
  31   forwarding cores liveliness status (DPDK Keep Alive).
  32
  33 * `gnocchi plugin`_: A write plugin that pushes the retrieved stats to
  34   Gnocchi. It's capable of pushing any stats read through collectd to
  35   Gnocchi, not just the DPDK stats.
  36
  37 * `aodh plugin`_: A notification plugin that pushes events to Aodh, and
  38   creates/updates alarms appropriately.
  39
  40 * *hugepages plugin*:  A read plugin that retrieves the number of available
  41   and free hugepages on a platform as well as what is available in terms of
  42   hugepages per socket.
  43
  44 * *Open vSwitch events Plugin*: A read plugin that retrieves events from OVS.
  45
  46 * *Open vSwitch stats Plugin*: A read plugin that retrieves flow and interface
  47   stats from OVS.
  48
  49 * *mcelog plugin*: A read plugin that uses mcelog client protocol to check for
  50   memory Machine Check Exceptions and sends the stats for reported exceptions
  51
  52 * *PMU plugin*: A read plugin that provides performance counters data on
  53   Intel CPUs using Linux perf interface.
  54
  55 * *RDT plugin*: A read plugin that provides the last level cache utilization and
  56   memory bandwidth utilization
  57
  58 * *virt*: A read plugin that uses virtualization API *libvirt* to gather
  59   statistics about virtualized guests on a system directly from the hypervisor,
  60   without a need to install collectd instance on the guest.
  61
  62 * *SNMP Agent*: A write plugin that will act as a AgentX subagent that receives
  63   and handles queries from SNMP master agent and returns the data collected
  64   by read plugins. The SNMP Agent plugin handles requests only for OIDs
  65   specified in configuration file. To handle SNMP queries the plugin gets data
  66   from collectd and translates requested values from collectd's internal format
  67   to SNMP format. Supports SNMP: get, getnext and walk requests.
  68
  69 All the plugins above are available on the collectd master, except for the
  70 Gnocchi and Aodh plugins as they are Python-based plugins and only C plugins
  71 are accepted by the collectd community. The Gnocchi and Aodh plugins live in
  72 the OpenStack repositories.
  73
  74 Other plugins existing as a pull request into collectd master:
  75
  76 * *Legacy/IPMI*: A read plugin that reports platform thermals, voltages,
  77   fanspeed, current, flow, power etc. Also, the plugin monitors Intelligent
  78   Platform Management Interface (IPMI) System Event Log (SEL) and sends the
  79   appropriate notifications based on monitored SEL events.
  80
  81 * *PCIe AER*: A read plugin that monitors PCIe standard and advanced errors and
  82   sends notifications about those errors.
  83
  84
  85 Third party application in Barometer repository:
  86
  87 * *Open vSwitch PMD stats*: An aplication that retrieves PMD stats from OVS. It is run
  88   through exec plugin.
  89
  90 **Plugins included in the Danube release:**
  91
  92 * Hugepages
  93 * Open vSwitch Events
  94 * Ceilometer
  95 * Mcelog
  96
  97 collectd capabilities and usage
  98 ------------------------------------
  99 .. Describe the specific capabilities and usage for <XYZ> feature.
 100 .. Provide enough information that a user will be able to operate the feature on a deployed scenario.
 101
 102 .. note:: Plugins included in the OPNFV D release will be built-in to the fuel
 103  plugin and available in the /opt/opnfv directory on the fuel master. You don't
 104  need to clone the barometer/collectd repos to use these, but you can configure
 105  them as shown in the examples below.
 106
 107  The collectd plugins in OPNFV are configured with reasonable defaults, but can
 108  be overridden.
 109
 110 Building all Barometer upstreamed plugins from scratch
 111 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 112 The plugins that have been merged to the collectd master branch can all be
 113 built and configured through the barometer repository.
 114
 115 .. note::
 116  * sudo permissions are required to install collectd.
 117  * These are instructions for Ubuntu 16.04
 118
 119 To build all the upstream plugins, clone the barometer repo:
 120
 121 .. code:: c
 122
 123     $ git clone https://gerrit.opnfv.org/gerrit/barometer
 124
 125 To install collectd as a service and install all it's dependencies:
 126
 127 .. code:: bash
 128
 129     $ cd barometer/systems && ./build_base_machine.sh
 130
 131 This will install collectd as a service and the base install directory
 132 will be /opt/collectd.
 133
 134 Sample configuration files can be found in '/opt/collectd/etc/collectd.conf.d'
 135
 136 .. note::
 137   If you don't want to use one of the Barometer plugins, simply remove the
 138   sample config file from '/opt/collectd/etc/collectd.conf.d'
 139 .. note::
 140   If you plan on using the Exec plugin (for OVS_PMD_STATS or for executing scripts
 141   on notification generation), the plugin requires a non-root
 142   user to execute scripts. By default, `collectd_exec` user is used in the exec.conf
 143   provided in the sample configurations directory under src/collectd in the Barometer
 144   repo. The scripts *DO NOT* create this user. You need to create this user before you
 145   run build_base_machine.sh. Or modify configuration in the sample configurations
 146   directory under src/collectd to use another existing non root user before running
 147   run build_base_machine.sh.
 148
 149 .. note::
 150   If you are using any Open vSwitch plugins you need to run:
 151
 152 .. code:: bash
 153
 154     $ sudo ovs-vsctl set-manager ptcp:6640
 155
 156 After this, you should be able to start collectd as a service
 157
 158 .. code:: bash
 159
 160     $ sudo systemctl status collectd
 161
 162 If you want to use granfana to display the metrics you collect, please see:
 163 `grafana guide`_
 164
 165 For more information on configuring and installing OpenStack plugins for
 166 collectd, check out the `collectd-ceilometer-plugin GSG`_.
 167
 168 Below is the per plugin installation and configuration guide, if you only want
 169 to install some/particular plugins.
 170
 171 DPDK plugins
 172 ^^^^^^^^^^^^^
 173 Repo: https://github.com/collectd/collectd
 174
 175 Branch: master
 176
 177 Dependencies: DPDK (http://dpdk.org/)
 178
 179 .. note:: DPDK statistics plugin requires DPDK version 16.04 or later
 180
 181 To build and install DPDK to /usr please see:
 182 https://github.com/collectd/collectd/blob/master/docs/BUILD.dpdkstat.md
 183
 184 Building and installing collectd:
 185
 186 .. code:: bash
 187
 188     $ git clone https://github.com/collectd/collectd.git
 189     $ cd collectd
 190     $ ./build.sh
 191     $ ./configure --enable-syslog --enable-logfile --enable-debug
 192     $ make
 193     $ sudo make install
 194
 195 .. note:: If DPDK was installed in a non standard location you will need to
 196     specify paths to the header files and libraries using *LIBDPDK_CPPFLAGS* and
 197     *LIBDPDK_LDFLAGS*. You will also need to add the DPDK library symbols to the
 198     shared library path using *ldconfig*. Note that this update to the shared
 199     library path is not persistant (i.e. it will not survive a reboot).
 200
 201 Example of specifying custom paths to DPDK headers and libraries:
 202
 203 .. code:: bash
 204
 205     $ ./configure LIBDPDK_CPPFLAGS="path to DPDK header files" LIBDPDK_LDFLAGS="path to DPDK libraries"
 206
 207 This will install collectd to /opt/collectd
 208 The collectd configuration file can be found at /opt/collectd/etc
 209
 210 To configure the dpdkstats plugin you need to modify the configuration file to
 211 include:
 212
 213 .. code:: bash
 214
 215     LoadPlugin dpdkstat
 216     <Plugin "dpdkstat">
 217         <EAL>
 218             Coremask "0x2"
 219             MemoryChannels "4"
 220             ProcessType "secondary"
 221             FilePrefix "rte"
 222         </EAL>
 223         EnabledPortMask 0xffff
 224         PortName "interface1"
 225         PortName "interface2"
 226     </Plugin>
 227
 228
 229 To configure the dpdkevents plugin you need to modify the configuration file to
 230 include:
 231
 232 .. code:: bash
 233
 234     LoadPlugin dpdkevents
 235     <Plugin "dpdkevents">
 236         Interval 1
 237         <EAL>
 238             Coremask "0x1"
 239             MemoryChannels "4"
 240             ProcessType "secondary"
 241             FilePrefix "rte"
 242         </EAL>
 243         <Event "link_status">
 244             SendEventsOnUpdate true
 245             EnabledPortMask 0xffff
 246             PortName "interface1"
 247             PortName "interface2"
 248             SendNotification false
 249         </Event>
 250         <Event "keep_alive">
 251             SendEventsOnUpdate true
 252             LCoreMask "0xf"
 253             KeepAliveShmName "/dpdk_keepalive_shm_name"
 254             SendNotification false
 255         </Event>
 256     </Plugin>
 257
 258 .. note:: Currently, the DPDK library doesn’t support API to de-initialize
 259  the DPDK resources allocated on the initialization. It means, the collectd
 260  plugin will not be able to release the allocated DPDK resources
 261  (locks/memory/pci bindings etc.) correctly on collectd shutdown or reinitialize
 262  the DPDK library if primary DPDK process is restarted. The only way to release
 263  those resources is to terminate the process itself. For this reason, the plugin
 264  forks off a separate collectd process. This child process becomes a secondary
 265  DPDK process which can be run on specific CPU cores configured by user through
 266  collectd configuration file (“Coremask” EAL configuration option, the
 267  hexadecimal bitmask of the cores to run on).
 268
 269 For more information on the plugin parameters, please see:
 270 https://github.com/collectd/collectd/blob/master/src/collectd.conf.pod
 271
 272 .. note:: dpdkstat plugin initialization time depends on read interval. It
 273  requires 5 read cycles to set up internal buffers and states. During that time
 274  no statistics are submitted. Also if plugin is running and the number of DPDK
 275  ports is increased, internal buffers are resized. That requires 3 read cycles
 276  and no port statistics are submitted in that time.
 277
 278 The Address-Space Layout Randomization (ASLR) security feature in Linux should be
 279 disabled, in order for the same hugepage memory mappings to be present in all
 280 DPDK multi-process applications.
 281
 282 To disable ASLR:
 283
 284 .. code:: bash
 285
 286     $ sudo echo 0 > /proc/sys/kernel/randomize_va_space
 287
 288 To fully enable ASLR:
 289
 290 .. code:: bash
 291
 292     $ sudo echo 2 > /proc/sys/kernel/randomize_va_space
 293
 294 .. warning:: Disabling Address-Space Layout Randomization (ASLR) may have security
 295     implications. It is recommended to be disabled only when absolutely necessary,
 296     and only when all implications of this change have been understood.
 297
 298 For more information on multi-process support, please see:
 299 http://dpdk.org/doc/guides/prog_guide/multi_proc_support.html
 300
 301 **DPDK stats plugin limitations:**
 302
 303 1. The DPDK primary process application should use the same version of DPDK
 304    that collectd DPDK plugin is using;
 305
 306 2. L2 statistics are only supported;
 307
 308 3. The plugin has been tested on Intel NIC’s only.
 309
 310 **DPDK stats known issues:**
 311
 312 * DPDK port visibility
 313
 314   When network port controlled by Linux is bound to DPDK driver, the port
 315   will not be available in the OS. It affects the SNMP write plugin as those
 316   ports will not be present in standard IF-MIB. Thus addition work is
 317   required to be done to support DPDK ports and statistics.
 318
 319 Hugepages Plugin
 320 ^^^^^^^^^^^^^^^^^
 321 Repo: https://github.com/collectd/collectd
 322
 323 Branch: master
 324
 325 Dependencies: None, but assumes hugepages are configured.
 326
 327 To configure some hugepages:
 328
 329 .. code:: bash
 330
 331    sudo mkdir -p /mnt/huge
 332    sudo mount -t hugetlbfs nodev /mnt/huge
 333    sudo echo 14336 > /sys/devices/system/node/node0/hugepages/hugepages-2048kB/nr_hugepages
 334
 335 Building and installing collectd:
 336
 337 .. code:: bash
 338
 339     $ git clone https://github.com/collectd/collectd.git
 340     $ cd collectd
 341     $ ./build.sh
 342     $ ./configure --enable-syslog --enable-logfile --enable-hugepages --enable-debug
 343     $ make
 344     $ sudo make install
 345
 346 This will install collectd to /opt/collectd
 347 The collectd configuration file can be found at /opt/collectd/etc
 348 To configure the hugepages plugin you need to modify the configuration file to
 349 include:
 350
 351 .. code:: bash
 352
 353     LoadPlugin hugepages
 354     <Plugin hugepages>
 355         ReportPerNodeHP  true
 356         ReportRootHP     true
 357         ValuesPages      true
 358         ValuesBytes      false
 359         ValuesPercentage false
 360     </Plugin>
 361
 362 For more information on the plugin parameters, please see:
 363 https://github.com/collectd/collectd/blob/master/src/collectd.conf.pod
 364
 365 Intel PMU Plugin
 366 ^^^^^^^^^^^^^^^^
 367 Repo: https://github.com/collectd/collectd
 368
 369 Branch: master
 370
 371 Dependencies:
 372
 373   * PMU tools (jevents library) https://github.com/andikleen/pmu-tools
 374
 375 To be suitable for use in collectd plugin shared library *libjevents* should be
 376 compiled as position-independent code. To do this add the following line to
 377 *pmu-tools/jevents/Makefile*:
 378
 379 .. code:: bash
 380
 381     CFLAGS += -fPIC
 382
 383 Building and installing *jevents* library:
 384
 385 .. code:: bash
 386
 387     $ git clone https://github.com/andikleen/pmu-tools.git
 388     $ cd pmu-tools/jevents/
 389     $ make
 390     $ sudo make install
 391
 392 Building and installing collectd:
 393
 394 .. code:: bash
 395
 396     $ git clone https://github.com/collectd/collectd.git
 397     $ cd collectd
 398     $ ./build.sh
 399     $ ./configure --enable-syslog --enable-logfile --with-libjevents=/usr/local --enable-debug
 400     $ make
 401     $ sudo make install
 402
 403 This will install collectd to /opt/collectd
 404 The collectd configuration file can be found at /opt/collectd/etc
 405 To configure the PMU plugin you need to modify the configuration file to
 406 include:
 407
 408 .. code:: bash
 409
 410     <LoadPlugin intel_pmu>
 411       Interval 1
 412     </LoadPlugin>
 413     <Plugin "intel_pmu">
 414       ReportHardwareCacheEvents true
 415       ReportKernelPMUEvents true
 416       ReportSoftwareEvents true
 417     </Plugin>
 418
 419 For more information on the plugin parameters, please see:
 420 https://github.com/collectd/collectd/blob/master/src/collectd.conf.pod
 421
 422 .. note::
 423
 424     The plugin opens file descriptors whose quantity depends on number of
 425     monitored CPUs and number of monitored counters. Depending on configuration,
 426     it might be required to increase the limit on the number of open file
 427     descriptors allowed. This can be done using 'ulimit -n' command. If collectd
 428     is executed as a service 'LimitNOFILE=' directive should be defined in
 429     [Service] section of *collectd.service* file.
 430
 431 Intel RDT Plugin
 432 ^^^^^^^^^^^^^^^^
 433 Repo: https://github.com/collectd/collectd
 434
 435 Branch: master
 436
 437 Dependencies:
 438
 439   * PQoS/Intel RDT library https://github.com/01org/intel-cmt-cat.git
 440   * msr kernel module
 441
 442 Building and installing PQoS/Intel RDT library:
 443
 444 .. code:: bash
 445
 446     $ git clone https://github.com/01org/intel-cmt-cat.git
 447     $ cd intel-cmt-cat
 448     $ make
 449     $ make install PREFIX=/usr
 450
 451 You will need to insert the msr kernel module:
 452
 453 .. code:: bash
 454
 455     $ modprobe msr
 456
 457 Building and installing collectd:
 458
 459 .. code:: bash
 460
 461     $ git clone https://github.com/collectd/collectd.git
 462     $ cd collectd
 463     $ ./build.sh
 464     $ ./configure --enable-syslog --enable-logfile --with-libpqos=/usr/ --enable-debug
 465     $ make
 466     $ sudo make install
 467
 468 This will install collectd to /opt/collectd
 469 The collectd configuration file can be found at /opt/collectd/etc
 470 To configure the RDT plugin you need to modify the configuration file to
 471 include:
 472
 473 .. code:: bash
 474
 475     <LoadPlugin intel_rdt>
 476       Interval 1
 477     </LoadPlugin>
 478     <Plugin "intel_rdt">
 479       Cores ""
 480     </Plugin>
 481
 482 For more information on the plugin parameters, please see:
 483 https://github.com/collectd/collectd/blob/master/src/collectd.conf.pod
 484
 485 IPMI Plugin
 486 ^^^^^^^^^^^^
 487 Repo: https://github.com/maryamtahhan/collectd
 488
 489 Branch: feat_ipmi_events, feat_ipmi_analog
 490
 491 Dependencies: OpenIPMI library (http://openipmi.sourceforge.net/)
 492
 493 The IPMI plugin is already implemented in the latest collectd and sensors
 494 like temperature, voltage, fanspeed, current are already supported there.
 495 The list of supported IPMI sensors has been extended and sensors like flow,
 496 power are supported now. Also, a System Event Log (SEL) notification feature
 497 has been introduced.
 498
 499 * The feat_ipmi_events branch includes new SEL feature support in collectd
 500   IPMI plugin. If this feature is enabled, the collectd IPMI plugin will
 501   dispatch notifications about new events in System Event Log.
 502
 503 * The feat_ipmi_analog branch includes the support of extended IPMI sensors in
 504   collectd IPMI plugin.
 505
 506 **Install dependencies**
 507
 508 On Ubuntu, the OpenIPMI library can be installed via apt package manager:
 509
 510 .. code:: bash
 511
 512     $ sudo apt-get install libopenipmi-dev
 513
 514 Anyway, it's recommended to use the latest version of the OpenIPMI library as
 515 it includes fixes of known issues which aren't included in standard OpenIPMI
 516 library package. The latest version of the library can be found at
 517 https://sourceforge.net/p/openipmi/code/ci/master/tree/. Steps to install the
 518 library from sources are described below.
 519
 520 Remove old version of OpenIPMI library:
 521
 522 .. code:: bash
 523
 524     $ sudo apt-get remove libopenipmi-dev
 525
 526 Download OpenIPMI library sources:
 527
 528 .. code:: bash
 529
 530     $ git clone https://git.code.sf.net/p/openipmi/code openipmi-code
 531     $ cd openipmi-code
 532
 533 Patch the OpenIPMI pkg-config file to provide correct compilation flags
 534 for collectd IPMI plugin:
 535
 536 .. code:: diff
 537
 538     diff --git a/OpenIPMIpthread.pc.in b/OpenIPMIpthread.pc.in
 539     index 59b52e5..fffa0d0 100644
 540     --- a/OpenIPMIpthread.pc.in
 541     +++ b/OpenIPMIpthread.pc.in
 542     @@ -6,6 +6,6 @@ includedir=@includedir@
 543      Name: OpenIPMIpthread
 544      Description: Pthread OS handler for OpenIPMI
 545      Version: @VERSION@
 546     -Requires: OpenIPMI pthread
 547     +Requires: OpenIPMI
 548      Libs: -L${libdir} -lOpenIPMIutils -lOpenIPMIpthread
 549     -Cflags: -I${includedir}
 550     +Cflags: -I${includedir} -pthread
 551
 552 Build and install OpenIPMI library:
 553
 554 .. code:: bash
 555
 556     $ autoreconf --install
 557     $ ./configure --prefix=/usr
 558     $ make
 559     $ sudo make install
 560
 561 Enable IPMI support in the kernel:
 562
 563 .. code:: bash
 564
 565     $ sudo modprobe ipmi_devintf
 566     $ sudo modprobe ipmi_si
 567
 568 .. note::
 569   If HW supports IPMI, the ``/dev/ipmi0`` character device will be
 570   created.
 571
 572 Clone and install the collectd IPMI plugin:
 573
 574 .. code:: bash
 575
 576     $ git clone  https://github.com/maryamtahhan/collectd
 577     $ cd collectd
 578     $ git checkout $BRANCH
 579     $ ./build.sh
 580     $ ./configure --enable-syslog --enable-logfile --enable-debug
 581     $ make
 582     $ sudo make install
 583
 584 Where $BRANCH is feat_ipmi_events or feat_ipmi_analog.
 585
 586 This will install collectd to default folder ``/opt/collectd``. The collectd
 587 configuration file (``collectd.conf``) can be found at ``/opt/collectd/etc``. To
 588 configure the IPMI plugin you need to modify the file to include:
 589
 590 .. code:: bash
 591
 592     LoadPlugin ipmi
 593     <Plugin ipmi>
 594        SELEnabled true # only feat_ipmi_events branch supports this
 595     </Plugin>
 596
 597 .. note::
 598   By default, IPMI plugin will read all available analog sensor values,
 599   dispatch the values to collectd and send SEL notifications.
 600
 601 For more information on the IPMI plugin parameters and SEL feature configuration,
 602 please see:
 603 https://github.com/maryamtahhan/collectd/blob/feat_ipmi_events/src/collectd.conf.pod
 604
 605 Extended analog sensors support doesn't require additional configuration. The usual
 606 collectd IPMI documentation can be used:
 607
 608 - https://collectd.org/wiki/index.php/Plugin:IPMI
 609 - https://collectd.org/documentation/manpages/collectd.conf.5.shtml#plugin_ipmi
 610
 611 IPMI documentation:
 612
 613 - https://www.kernel.org/doc/Documentation/IPMI.txt
 614 - http://www.intel.com/content/www/us/en/servers/ipmi/ipmi-second-gen-interface-spec-v2-rev1-1.html
 615
 616 Mcelog Plugin
 617 ^^^^^^^^^^^^^^
 618 Repo: https://github.com/collectd/collectd
 619
 620 Branch: master
 621
 622 Dependencies: mcelog
 623
 624 Start by installing mcelog.
 625
 626 .. note::
 627   The kernel has to have CONFIG_X86_MCE enabled. For 32bit kernels you
 628   need at least a 2.6,30 kernel.
 629
 630 On ubuntu:
 631
 632 .. code:: bash
 633
 634     $ apt-get update && apt-get install mcelog
 635
 636 Or build from source
 637
 638 .. code:: bash
 639
 640     $ git clone git://git.kernel.org/pub/scm/utils/cpu/mce/mcelog.git
 641     $ cd mcelog
 642     $ make
 643     ... become root ...
 644     $ make install
 645     $ cp mcelog.service /etc/systemd/system/
 646     $ systemctl enable mcelog.service
 647     $ systemctl start mcelog.service
 648
 649
 650 Verify you got a /dev/mcelog. You can verify the daemon is running completely
 651 by running:
 652
 653 .. code:: bash
 654
 655      $ mcelog --client
 656
 657 This should query the information in the running daemon. If it prints nothing
 658 that is fine (no errors logged yet). More info @
 659 http://www.mcelog.org/installation.html
 660
 661 Modify the mcelog configuration file "/etc/mcelog/mcelog.conf" to include or
 662 enable:
 663
 664 .. code:: bash
 665
 666     socket-path = /var/run/mcelog-client
 667
 668 Clone and install the collectd mcelog plugin:
 669
 670 .. code:: bash
 671
 672     $ git clone  https://github.com/maryamtahhan/collectd
 673     $ cd collectd
 674     $ git checkout feat_ras
 675     $ ./build.sh
 676     $ ./configure --enable-syslog --enable-logfile --enable-debug
 677     $ make
 678     $ sudo make install
 679
 680 This will install collectd to /opt/collectd
 681 The collectd configuration file can be found at /opt/collectd/etc
 682 To configure the mcelog plugin you need to modify the configuration file to
 683 include:
 684
 685 .. code:: bash
 686
 687     <LoadPlugin mcelog>
 688       Interval 1
 689     </LoadPlugin>
 690     <Plugin "mcelog">
 691        McelogClientSocket "/var/run/mcelog-client"
 692     </Plugin>
 693
 694 For more information on the plugin parameters, please see:
 695 https://github.com/maryamtahhan/collectd/blob/feat_ras/src/collectd.conf.pod
 696
 697 Simulating a Machine Check Exception can be done in one of 3 ways:
 698
 699 * Running $make test in the mcelog cloned directory - mcelog test suite
 700 * using mce-inject
 701 * using mce-test
 702
 703 **mcelog test suite:**
 704
 705 It is always a good idea to test an error handling mechanism before it is
 706 really needed. mcelog includes a test suite. The test suite relies on
 707 mce-inject which needs to be installed and in $PATH.
 708
 709 You also need the mce-inject kernel module configured (with
 710 CONFIG_X86_MCE_INJECT=y), compiled, installed and loaded:
 711
 712 .. code:: bash
 713
 714     $ modprobe mce-inject
 715
 716 Then you can run the mcelog test suite with
 717
 718 .. code:: bash
 719
 720     $ make test
 721
 722 This will inject different classes of errors and check that the mcelog triggers
 723 runs. There will be some kernel messages about page offlining attempts. The
 724 test will also lose a few pages of memory in your system (not significant)
 725 .. note::
 726   This test will kill any running mcelog, which needs to be restarted
 727   manually afterwards.
 728
 729 **mce-inject:**
 730
 731 A utility to inject corrected, uncorrected and fatal machine check exceptions
 732
 733 .. code:: bash
 734
 735     $ git clone https://git.kernel.org/pub/scm/utils/cpu/mce/mce-inject.git
 736     $ cd mce-inject
 737     $ make
 738     $ modprobe mce-inject
 739
 740 Modify the test/corrected script to include the following:
 741
 742 .. code:: bash
 743
 744     CPU 0 BANK 0
 745     STATUS 0xcc00008000010090
 746     ADDR 0x0010FFFFFFF
 747
 748 Inject the error:
 749 .. code:: bash
 750
 751     $ ./mce-inject < test/corrected
 752
 753 .. note::
 754   The uncorrected and fatal scripts under test will cause a platform reset.
 755   Only the fatal script generates the memory errors**. In order to  quickly
 756   emulate uncorrected memory errors and avoid host reboot following test errors
 757   from mce-test  suite can be injected:
 758
 759 .. code:: bash
 760
 761        $ mce-inject  mce-test/cases/coverage/soft-inj/recoverable_ucr/data/srao_mem_scrub
 762
 763 **mce-test:**
 764
 765 In addition an more in-depth test of the Linux kernel machine check facilities
 766 can be done with the mce-test test suite. mce-test supports testing uncorrected
 767 error handling, real error injection, handling of different soft offlining
 768 cases, and other tests.
 769
 770 **Corrected memory error injection:**
 771
 772 To inject corrected memory errors:
 773
 774 * Remove sb_edac and edac_core kernel modules: rmmod sb_edac rmmod edac_core
 775 * Insert einj module: modprobe einj param_extension=1
 776 * Inject an error by specifying details (last command should be repeated at least two times):
 777
 778 .. code:: bash
 779
 780     $ APEI_IF=/sys/kernel/debug/apei/einj
 781     $ echo 0x8 > $APEI_IF/error_type
 782     $ echo 0x01f5591000 > $APEI_IF/param1
 783     $ echo 0xfffffffffffff000 > $APEI_IF/param2
 784     $ echo 1 > $APEI_IF/notrigger
 785     $ echo 1 > $APEI_IF/error_inject
 786
 787 * Check the MCE statistic: mcelog --client. Check the mcelog log for injected error details: less /var/log/mcelog.
 788
 789 Open vSwitch Plugins
 790 ^^^^^^^^^^^^^^^^^^^^^
 791 OvS Plugins Repo: https://github.com/collectd/collectd
 792
 793 OvS Plugins Branch: master
 794
 795 OvS Events MIBs: The SNMP OVS interface link status is provided by standard
 796 IF-MIB (http://www.net-snmp.org/docs/mibs/IF-MIB.txt)
 797
 798 Dependencies: Open vSwitch, Yet Another JSON Library (https://github.com/lloyd/yajl)
 799
 800 On Ubuntu, install the dependencies:
 801
 802 .. code:: bash
 803
 804     $ sudo apt-get install libyajl-dev openvswitch-switch
 805
 806 Start the Open vSwitch service:
 807
 808 .. code:: bash
 809
 810     $ sudo service openvswitch-switch start
 811
 812 configure the ovsdb-server manager:
 813
 814 .. code:: bash
 815
 816     $ sudo ovs-vsctl set-manager ptcp:6640
 817
 818 Clone and install the collectd ovs plugin:
 819
 820 .. code:: bash
 821
 822     $ git clone $REPO
 823     $ cd collectd
 824     $ git checkout master
 825     $ ./build.sh
 826     $ ./configure --enable-syslog --enable-logfile --enable-debug
 827     $ make
 828     $ sudo make install
 829
 830 This will install collectd to /opt/collectd. The collectd configuration file
 831 can be found at /opt/collectd/etc. To configure the OVS events plugin you
 832 need to modify the configuration file to include:
 833
 834 .. code:: bash
 835
 836     <LoadPlugin ovs_events>
 837        Interval 1
 838     </LoadPlugin>
 839     <Plugin "ovs_events">
 840        Port 6640
 841        Socket "/var/run/openvswitch/db.sock"
 842        Interfaces "br0" "veth0"
 843        SendNotification false
 844        DispatchValues true
 845     </Plugin>
 846
 847 To configure the OVS stats plugin you need to modify the configuration file
 848 to include:
 849
 850 .. code:: bash
 851
 852     <LoadPlugin ovs_stats>
 853        Interval 1
 854     </LoadPlugin>
 855     <Plugin ovs_stats>
 856        Port "6640"
 857        Address "127.0.0.1"
 858        Socket "/var/run/openvswitch/db.sock"
 859        Bridges "br0" "br_ext"
 860     </Plugin>
 861
 862 For more information on the plugin parameters, please see:
 863 https://github.com/collectd/collectd/blob/master/src/collectd.conf.pod
 864
 865 OVS PMD stats
 866 ^^^^^^^^^^^^^^
 867 Repo: https://gerrit.opnfv.org/gerrit/barometer
 868
 869 Prequistes:
 870 1. Open vSwitch dependencies are installed.
 871 2. Open vSwitch service is running.
 872 3. Ovsdb-server manager is configured.
 873 You can refer `Open vSwitch Plugins`_ section above for each one of them.
 874
 875 OVS PMD stats application is run through the exec plugin.
 876
 877 To configure the OVS PMD stats application you need to modify the exec plugin configuration
 878 to include:
 879
 880 .. code:: bash
 881
 882     <LoadPlugin exec>
 883        Interval 1
 884     </LoadPlugin
 885     <Plugin exec>
 886         Exec "user:group" "<path to ovs_pmd_stat.sh>"
 887         #NotificationExec "nobody" "/usr/lib/collectd/notify.sh"
 888     </Plugin>
 889
 890 .. note:: Exec plugin configuration has to be changed to use appropriate user before starting collectd service.
 891
 892 ovs_pmd_stat.sh calls the script for OVS PMD stats application with its argument:
 893
 894 .. code:: bash
 895
 896      sudo python /usr/local/src/ovs_pmd_stats.py" "--socket-pid-file"
 897      "/var/run/openvswitch/ovs-vswitchd.pid"
 898
 899 SNMP Agent Plugin
 900 ^^^^^^^^^^^^^^^^^
 901 Repo: https://github.com/maryamtahhan/collectd/
 902
 903 Branch: feat_snmp
 904
 905 Dependencies: NET-SNMP library
 906
 907 Start by installing net-snmp and dependencies.
 908
 909 On ubuntu:
 910
 911 .. code:: bash
 912
 913     $ apt-get install snmp snmp-mibs-downloader snmpd libsnmp-dev
 914     $ systemctl start snmpd.service
 915
 916 Or build from source
 917
 918 Become root to install net-snmp dependencies
 919
 920 .. code:: bash
 921
 922     $ apt-get install libperl-dev
 923
 924 Clone and build net-snmp
 925
 926 .. code:: bash
 927
 928     $ git clone https://github.com/haad/net-snmp.git
 929     $ cd net-snmp
 930     $ ./configure --with-persistent-directory="/var/net-snmp" --with-systemd --enable-shared --prefix=/usr
 931     $ make
 932
 933 Become root
 934
 935 .. code:: bash
 936
 937     $ make install
 938
 939 Copy default configuration to persistent folder
 940
 941 .. code:: bash
 942
 943     $ cp EXAMPLE.conf /usr/share/snmp/snmpd.conf
 944
 945 Set library path and default MIB configuration
 946
 947 .. code:: bash
 948
 949     $ cd ~/
 950     $ echo export LD_LIBRARY_PATH=/usr/lib >> .bashrc
 951     $ net-snmp-config --default-mibdirs
 952     $ net-snmp-config --snmpconfpath
 953
 954 Configure snmpd as a service
 955
 956 .. code:: bash
 957
 958     $ cd net-snmp
 959     $ cp ./dist/snmpd.service /etc/systemd/system/
 960     $ systemctl enable snmpd.service
 961     $ systemctl start snmpd.service
 962
 963 Add the following line to snmpd.conf configuration file
 964 "/usr/share/snmp/snmpd.conf" to make all OID tree visible for SNMP clients:
 965
 966 .. code:: bash
 967
 968     view   systemonly  included   .1
 969
 970 To verify that SNMP is working you can get IF-MIB table using SNMP client
 971 to view the list of Linux interfaces:
 972
 973 .. code:: bash
 974
 975     $ snmpwalk -v 2c -c public localhost IF-MIB::interfaces
 976
 977 Clone and install the collectd snmp_agent plugin:
 978
 979 .. code:: bash
 980
 981     $ git clone  https://github.com/maryamtahhan/collectd
 982     $ cd collectd
 983     $ git checkout feat_snmp
 984     $ ./build.sh
 985     $ ./configure --enable-syslog --enable-logfile --enable-debug --enable-snmp --with-libnetsnmp
 986     $ make
 987     $ sudo make install
 988
 989 This will install collectd to /opt/collectd
 990 The collectd configuration file can be found at /opt/collectd/etc
 991 **SNMP Agent plugin is a generic plugin and cannot work without configuration**.
 992 To configure the snmp_agent plugin you need to modify the configuration file to
 993 include OIDs mapped to collectd types. The following example maps scalar
 994 memAvailReal OID to value represented as free memory type of memory plugin:
 995
 996 .. code:: bash
 997
 998     LoadPlugin snmp_agent
 999     <Plugin "snmp_agent">
1000       <Data "memAvailReal">
1001         Plugin "memory"
1002         Type "memory"
1003         TypeInstance "free"
1004         OIDs "1.3.6.1.4.1.2021.4.6.0"
1005       </Data>
1006     </Plugin>
1007
1008 **Limitations**
1009
1010 * Object instance with Counter64 type is not supported in SNMPv1. When GetNext
1011   request is received, Counter64 type objects will be skipped. When Get
1012   request is received for Counter64 type object, the error will be returned.
1013 * Interfaces that are not visible to Linux like DPDK interfaces cannot be
1014   retreived using standard IF-MIB tables.
1015
1016 For more information on the plugin parameters, please see:
1017 https://github.com/maryamtahhan/collectd/blob/feat_snmp/src/collectd.conf.pod
1018
1019 For more details on AgentX subagent, please see:
1020 http://www.net-snmp.org/tutorial/tutorial-5/toolkit/demon/
1021
1022 virt plugin
1023 ^^^^^^^^^^^^
1024 Repo: https://github.com/maryamtahhan/collectd
1025
1026 Branch: feat_libvirt_upstream
1027
1028 Dependencies: libvirt (https://libvirt.org/), libxml2
1029
1030 On Ubuntu, install the dependencies:
1031
1032 .. code:: bash
1033
1034     $ sudo apt-get install libxml2-dev
1035
1036 Install libvirt:
1037
1038 libvirt version in package manager might be quite old and offer only limited
1039 functionality. Hence, building and installing libvirt from sources is recommended.
1040 Detailed instructions can bet found at:
1041 https://libvirt.org/compiling.html
1042
1043 Certain metrics provided by the plugin have a requirement on a minimal version of
1044 the libvirt API. *File system information* statistics require a *Guest Agent (GA)*
1045 to be installed and configured in a VM. User must make sure that installed GA
1046 version supports retrieving file system information. Number of *Performance monitoring events*
1047 metrics depends on running libvirt daemon version.
1048
1049 .. note:: Please keep in mind that RDT metrics (part of *Performance monitoring
1050     events*) have to be supported by hardware. For more details on hardware support,
1051     please see:
1052     https://github.com/01org/intel-cmt-cat
1053
1054     Additionally perf metrics **cannot** be collected if *Intel RDT* plugin is enabled.
1055
1056 libvirt version can be checked with following commands:
1057
1058 .. code:: bash
1059
1060     $ virsh --version
1061     $ libvirtd --version
1062
1063 .. table:: Extended statistics requirements
1064
1065     +-------------------------------+--------------------------+-------------+
1066     | Statistic                     | Min. libvirt API version | Requires GA |
1067     +===============================+==========================+=============+
1068     | Domain reason                 | 0.9.2                    | No          |
1069     +-------------------------------+--------------------------+-------------+
1070     | Disk errors                   | 0.9.10                   | No          |
1071     +-------------------------------+--------------------------+-------------+
1072     | Job statistics                | 1.2.9                    | No          |
1073     +-------------------------------+--------------------------+-------------+
1074     | File system information       | 1.2.11                   | Yes         |
1075     +-------------------------------+--------------------------+-------------+
1076     | Performance monitoring events | 1.3.3                    | No          |
1077     +-------------------------------+--------------------------+-------------+
1078
1079 Start libvirt daemon:
1080
1081 .. code:: bash
1082
1083     $ systemctl start libvirtd
1084
1085 Create domain (VM) XML configuration file. For more information on domain XML
1086 format and examples, please see:
1087 https://libvirt.org/formatdomain.html
1088
1089 .. note:: Installing additional hypervisor dependencies might be required before
1090     deploying virtual machine.
1091
1092 Create domain, based on created XML file:
1093
1094 .. code:: bash
1095
1096     $ virsh define DOMAIN_CFG_FILE.xml
1097
1098 Start domain:
1099
1100 .. code:: bash
1101
1102     $ virsh start DOMAIN_NAME
1103
1104 Check if domain is running:
1105
1106 .. code:: bash
1107
1108     $ virsh list
1109
1110 Check list of available *Performance monitoring events* and their settings:
1111
1112 .. code:: bash
1113
1114     $ virsh perf DOMAIN_NAME
1115
1116 Enable or disable *Performance monitoring events* for domain:
1117
1118 .. code:: bash
1119
1120     $ virsh perf DOMAIN_NAME [--enable | --disable] EVENT_NAME --live
1121
1122 Clone and install the collectd virt plugin:
1123
1124 .. code:: bash
1125
1126     $ git clone $REPO
1127     $ cd collectd
1128     $ git checkout $BRANCH
1129     $ ./build.sh
1130     $ ./configure --enable-syslog --enable-logfile --enable-debug
1131     $ make
1132     $ sudo make install
1133
1134 Where ``$REPO`` and ``$BRANCH`` are equal to information provided above.
1135
1136 This will install collectd to ``/opt/collectd``. The collectd configuration file
1137 ``collectd.conf`` can be found at ``/opt/collectd/etc``. To load the virt plugin
1138 user needs to modify the configuration file to include:
1139
1140 .. code:: bash
1141
1142     LoadPlugin virt
1143
1144 Additionally, user can specify plugin configuration parameters in this file,
1145 such as connection URI, domain name and much more. By default extended virt plugin
1146 statistics are disabled. They can be enabled with ``ExtraStats`` option.
1147
1148 .. code:: bash
1149
1150     <Plugin virt>
1151        RefreshInterval 60
1152        ExtraStats "cpu_util disk disk_err domain_state fs_info job_stats_background pcpu perf vcpupin"
1153     </Plugin>
1154
1155 For more information on the plugin parameters, please see:
1156 https://github.com/maryamtahhan/collectd/blob/feat_libvirt_upstream/src/collectd.conf.pod
1157
1158 Installing collectd as a service
1159 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1160 **NOTE**: In an OPNFV installation, collectd is installed and configured as a
1161 service.
1162
1163 Collectd service scripts are available in the collectd/contrib directory.
1164 To install collectd as a service:
1165
1166 .. code:: bash
1167
1168     $ sudo cp contrib/systemd.collectd.service /etc/systemd/system/
1169     $ cd /etc/systemd/system/
1170     $ sudo mv systemd.collectd.service collectd.service
1171     $ sudo chmod +x collectd.service
1172
1173 Modify collectd.service
1174
1175 .. code:: bash
1176
1177     [Service]
1178     ExecStart=/opt/collectd/sbin/collectd
1179     EnvironmentFile=-/opt/collectd/etc/
1180     EnvironmentFile=-/opt/collectd/etc/
1181     CapabilityBoundingSet=CAP_SETUID CAP_SETGID
1182
1183 Reload
1184
1185 .. code:: bash
1186
1187     $ sudo systemctl daemon-reload
1188     $ sudo systemctl start collectd.service
1189     $ sudo systemctl status collectd.service should show success
1190
1191 Additional useful plugins
1192 ^^^^^^^^^^^^^^^^^^^^^^^^^^
1193
1194 * **Exec Plugin** : Can be used to show you when notifications are being
1195  generated by calling a bash script that dumps notifications to file. (handy
1196  for debug). Modify /opt/collectd/etc/collectd.conf:
1197
1198 .. code:: bash
1199
1200    LoadPlugin exec
1201    <Plugin exec>
1202    #   Exec "user:group" "/path/to/exec"
1203       NotificationExec "user" "<path to barometer>/barometer/src/collectd/collectd_sample_configs/write_notification.sh"
1204    </Plugin>
1205
1206 write_notification.sh (just writes the notification passed from exec through
1207 STDIN to a file (/tmp/notifications)):
1208
1209 .. code:: bash
1210
1211    #!/bin/bash
1212    rm -f /tmp/notifications
1213    while read x y
1214    do
1215      echo $x$y >> /tmp/notifications
1216    done
1217
1218 output to /tmp/notifications should look like:
1219
1220 .. code:: bash
1221
1222     Severity:WARNING
1223     Time:1479991318.806
1224     Host:localhost
1225     Plugin:ovs_events
1226     PluginInstance:br-ex
1227     Type:gauge
1228     TypeInstance:link_status
1229     uuid:f2aafeec-fa98-4e76-aec5-18ae9fc74589
1230
1231     linkstate of "br-ex" interface has been changed to "DOWN"
1232
1233 * **logfile plugin**: Can be used to log collectd activity. Modify
1234   /opt/collectd/etc/collectd.conf to include:
1235
1236 .. code:: bash
1237
1238     LoadPlugin logfile
1239     <Plugin logfile>
1240         LogLevel info
1241         File "/var/log/collectd.log"
1242         Timestamp true
1243         PrintSeverity false
1244     </Plugin>
1245
1246
1247 Monitoring Interfaces and Openstack Support
1248 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1249 .. Figure:: monitoring_interfaces.png
1250
1251    Monitoring Interfaces and Openstack Support
1252
1253 The figure above shows the DPDK L2 forwarding application running on a compute
1254 node, sending and receiving traffic. collectd is also running on this compute
1255 node retrieving the stats periodically from DPDK through the dpdkstat plugin
1256 and publishing the retrieved stats to OpenStack through the
1257 collectd-ceilometer-plugin.
1258
1259 To see this demo in action please checkout: `Barometer OPNFV Summit demo`_
1260
1261 For more information on configuring and installing OpenStack plugins for
1262 collectd, check out the `collectd-ceilometer-plugin GSG`_.
1263
1264 References
1265 ^^^^^^^^^^^
1266 .. [1] https://collectd.org/wiki/index.php/Naming_schema
1267 .. [2] https://github.com/collectd/collectd/blob/master/src/daemon/plugin.h
1268 .. [3] https://collectd.org/wiki/index.php/Value_list_t
1269 .. [4] https://collectd.org/wiki/index.php/Data_set
1270 .. [5] https://collectd.org/documentation/manpages/types.db.5.shtml
1271 .. [6] https://collectd.org/wiki/index.php/Data_source
1272 .. [7] https://collectd.org/wiki/index.php/Meta_Data_Interface
1273
1274 .. _Barometer OPNFV Summit demo: https://prezi.com/kjv6o8ixs6se/software-fastpath-service-quality-metrics-demo/
1275 .. _gnocchi plugin: https://github.com/openstack/collectd-ceilometer-plugin/tree/stable/ocata/
1276 .. _aodh plugin: https://github.com/openstack/collectd-ceilometer-plugin/tree/stable/ocata/
1277 .. _collectd-ceilometer-plugin GSG: https://github.com/openstack/collectd-ceilometer-plugin/blob/master/doc/source/GSG.rst
1278 .. _grafana guide: https://wiki.opnfv.org/display/fastpath/Installing+and+configuring+InfluxDB+and+Grafana+to+display+metrics+with+collectd