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 * mcelog plugin: A read plugin that uses mcelog client protocol to check for
  26   memory Machine Check Exceptions and sends the stats for reported exceptions
  27
  28 All the plugins above are available on the collectd master, except for the
  29 ceilometer plugin as it's a python based plugin and only C plugins are accepted
  30 by the collectd community. The ceilometer plugin lives in the OpenStack
  31 repositories.
  32
  33 Other plugins under development or existing as a pull request into collectd master:
  34
  35 * dpdkevents:  A read plugin that retrieves DPDK link status and DPDK
  36   forwarding cores liveliness status (DPDK Keep Alive).
  37
  38 * Open vSwitch stats Plugin: A read plugin that retrieve flow and interface
  39   stats from OVS.
  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 reports platform thermals, voltages,
  46   fanspeed, current, flow, power etc. Also, the plugin monitors Intelligent
  47   Platform Management Interface (IPMI) System Event Log (SEL) and sends the
  48   collectd notification once a new record appears in the SEL.
  49
  50 Building collectd with the Barometer plugins and installing the dependencies
  51 =============================================================================
  52
  53 All Upstreamed plugins
  54 -----------------------
  55 The plugins that have been merged to the collectd master branch can all be
  56 built and configured through the barometer repository.
  57
  58 **Note**: sudo permissions are required to install collectd.
  59
  60 **Note**: These are instructions for Ubuntu 16.04.
  61
  62 To build and install these dependencies, clone the barometer repo:
  63
  64 .. code:: c
  65
  66     $ git clone https://gerrit.opnfv.org/gerrit/barometer
  67
  68 Install the build dependencies
  69
  70 .. code:: bash
  71
  72     $ ./src/install_build_deps.sh
  73
  74 To install collectd as a service and install all it's dependencies:
  75
  76 .. code:: bash
  77
  78     $ cd barometer/src && sudo make && sudo make install
  79
  80 This will install collectd as a service and the base install directory
  81 is /opt/collectd.
  82
  83 Sample configuration files can be found in '/opt/collectd/etc/collectd.conf.d'
  84
  85 Please note if you are using any Open vSwitch plugins you need to run:
  86
  87 .. code:: bash
  88
  89     $ sudo ovs-vsctl set-manager ptcp:6640
  90
  91 DPDK statistics plugin
  92 -----------------------
  93 Repo: https://github.com/collectd/collectd
  94
  95 Branch: master
  96
  97 Dependencies: DPDK (http://dpdk.org/)
  98
  99 To build and install DPDK to /usr please see:
 100 https://github.com/collectd/collectd/blob/master/docs/BUILD.dpdkstat.md
 101
 102 Building and installing collectd:
 103
 104 .. code:: bash
 105
 106     $ git clone https://github.com/collectd/collectd.git
 107     $ cd collectd
 108     $ ./build.sh
 109     $ ./configure --enable-syslog --enable-logfile --enable-debug
 110     $ make
 111     $ sudo make install
 112
 113
 114 This will install collectd to /opt/collectd
 115 The collectd configuration file can be found at /opt/collectd/etc
 116 To configure the hugepages plugin you need to modify the configuration file to
 117 include:
 118
 119 .. code:: bash
 120
 121     LoadPlugin dpdkstat
 122     <Plugin dpdkstat>
 123            Coremask "0xf"
 124            ProcessType "secondary"
 125            FilePrefix "rte"
 126            EnabledPortMask 0xffff
 127     </Plugin>
 128
 129 For more information on the plugin parameters, please see:
 130 https://github.com/collectd/collectd/blob/master/src/collectd.conf.pod
 131
 132 Please note if you are configuring collectd with the **static DPDK library**
 133 you must compile the DPDK library with the -fPIC flag:
 134
 135 .. code:: bash
 136
 137     $ make EXTRA_CFLAGS=-fPIC
 138
 139 You must also modify the configuration step when building collectd:
 140
 141 .. code:: bash
 142
 143     $ ./configure CFLAGS=" -lpthread -Wl,--whole-archive -Wl,-ldpdk -Wl,-lm -Wl,-lrt -Wl,-lpcap -Wl,-ldl -Wl,--no-whole-archive"
 144
 145 Please also note that if you are not building and installing DPDK system-wide
 146 you will need to specify the specific paths to the header files and libraries
 147 using LIBDPDK_CPPFLAGS and LIBDPDK_LDFLAGS. You will also need to add the DPDK
 148 library symbols to the shared library path using ldconfig. Note that this
 149 update to the shared library path is not persistant (i.e. it will not survive a
 150 reboot). Pending a merge of https://github.com/collectd/collectd/pull/2073.
 151
 152 .. code:: bash
 153
 154     $ ./configure LIBDPDK_CPPFLAGS="path to DPDK header files" LIBDPDK_LDFLAGS="path to DPDK libraries"
 155
 156
 157 Hugepages Plugin
 158 -----------------
 159 Repo: https://github.com/collectd/collectd
 160
 161 Branch: master
 162
 163 Dependencies: None, but assumes hugepages are configured.
 164
 165 To configure some hugepages:
 166
 167 .. code:: bash
 168
 169    sudo mkdir -p /mnt/huge
 170    sudo mount -t hugetlbfs nodev /mnt/huge
 171    sudo echo 14336 > /sys/devices/system/node/node0/hugepages/hugepages-2048kB/nr_hugepages
 172
 173 Building and installing collectd:
 174
 175 .. code:: bash
 176
 177     $ git clone https://github.com/collectd/collectd.git
 178     $ cd collectd
 179     $ ./build.sh
 180     $ ./configure --enable-syslog --enable-logfile --enable-hugepages --enable-debug
 181     $ make
 182     $ sudo make install
 183
 184 This will install collectd to /opt/collectd
 185 The collectd configuration file can be found at /opt/collectd/etc
 186 To configure the hugepages plugin you need to modify the configuration file to
 187 include:
 188
 189 .. code:: bash
 190
 191     LoadPlugin hugepages
 192     <Plugin hugepages>
 193         ReportPerNodeHP  true
 194         ReportRootHP     true
 195         ValuesPages      true
 196         ValuesBytes      false
 197         ValuesPercentage false
 198     </Plugin>
 199
 200 For more information on the plugin parameters, please see:
 201 https://github.com/collectd/collectd/blob/master/src/collectd.conf.pod
 202
 203 Intel RDT Plugin
 204 -----------------
 205 Repo: https://github.com/collectd/collectd
 206
 207 Branch: master
 208
 209 Dependencies:
 210
 211   * PQoS/Intel RDT library https://github.com/01org/intel-cmt-cat.git
 212   * msr kernel module
 213
 214 Building and installing PQoS/Intel RDT library:
 215
 216 .. code:: bash
 217
 218     $ git clone https://github.com/01org/intel-cmt-cat.git
 219     $ cd intel-cmt-cat
 220     $ make
 221     $ make install PREFIX=/usr
 222
 223 You will need to insert the msr kernel module:
 224
 225 .. code:: bash
 226
 227     $ modprobe msr
 228
 229 Building and installing collectd:
 230
 231 .. code:: bash
 232
 233     $ git clone https://github.com/collectd/collectd.git
 234     $ cd collectd
 235     $ ./build.sh
 236     $ ./configure --enable-syslog --enable-logfile --with-libpqos=/usr/ --enable-debug
 237     $ make
 238     $ sudo make install
 239
 240 This will install collectd to /opt/collectd
 241 The collectd configuration file can be found at /opt/collectd/etc
 242 To configure the RDT plugin you need to modify the configuration file to
 243 include:
 244
 245 .. code:: bash
 246
 247     <LoadPlugin intel_rdt>
 248       Interval 1
 249     </LoadPlugin>
 250     <Plugin "intel_rdt">
 251       Cores ""
 252     </Plugin>
 253
 254 For more information on the plugin parameters, please see:
 255 https://github.com/collectd/collectd/blob/master/src/collectd.conf.pod
 256
 257 IPMI Plugin
 258 -----------
 259 Repo: https://github.com/maryamtahhan/collectd
 260
 261 Branch: feat_ipmi_events, feat_ipmi_analog
 262
 263 Dependencies: OpenIPMI library
 264
 265 The IPMI plugin is already implemented in the latest collectd and sensors
 266 like temperature, voltage, fanspeed, current are already supported there.
 267 The list of supported IPMI sensors has been extended and sensors like flow,
 268 power are supported now. Also, a System Event Log (SEL) notification feature
 269 has been introduced.
 270
 271 * The feat_ipmi_events branch includes new SEL feature support in collectd
 272   IPMI plugin. If this feature is enabled, the collectd IPMI plugin will
 273   dispatch notifications about new events in System Event Log.
 274
 275 * The feat_ipmi_analog branch includes the support of extended IPMI sensors in
 276   collectd IPMI plugin.
 277
 278 On Ubuntu, install the dependencies:
 279
 280 .. code:: bash
 281
 282     $ sudo apt-get install libopenipmi-dev
 283
 284 Enable IPMI support in the kernel:
 285
 286 .. code:: bash
 287
 288     $ sudo modprobe ipmi_devintf
 289     $ sudo modprobe ipmi_si
 290
 291 **Note**: If HW supports IPMI, the ``/dev/ipmi0`` character device will be
 292 created.
 293
 294 Clone and install the collectd IPMI plugin:
 295
 296 .. code:: bash
 297
 298     $ git clone  https://github.com/maryamtahhan/collectd
 299     $ cd collectd
 300     $ git checkout $BRANCH
 301     $ ./build.sh
 302     $ ./configure --enable-syslog --enable-logfile --enable-debug
 303     $ make
 304     $ sudo make install
 305
 306 Where $BRANCH is feat_ipmi_events or feat_ipmi_analog.
 307
 308 This will install collectd to default folder ``/opt/collectd``. The collectd
 309 configuration file (``collectd.conf``) can be found at ``/opt/collectd/etc``. To
 310 configure the IPMI plugin you need to modify the file to include:
 311
 312 .. code:: bash
 313
 314     LoadPlugin ipmi
 315     <Plugin ipmi>
 316        SELEnabled true # only feat_ipmi_events branch supports this
 317     </Plugin>
 318
 319 **Note**: By default, IPMI plugin will read all available analog sensor values,
 320 dispatch the values to collectd and send SEL notifications.
 321
 322 For more information on the IPMI plugin parameters and SEL feature configuration,
 323 please see:
 324
 325 https://github.com/maryamtahhan/collectd/blob/feat_ipmi_events/src/collectd.conf.pod
 326
 327 Extended analog sensors support doesn't require addition configuration. The usual
 328 collectd IPMI documentation can be used.
 329
 330 https://collectd.org/wiki/index.php/Plugin:IPMI
 331 https://collectd.org/documentation/manpages/collectd.conf.5.shtml#plugin_ipmi
 332
 333 IPMI documentation:
 334
 335 https://www.kernel.org/doc/Documentation/IPMI.txt
 336 http://www.intel.com/content/www/us/en/servers/ipmi/ipmi-second-gen-interface-spec-v2-rev1-1.html
 337
 338 Mcelog Plugin:
 339 --------------
 340 Repo: https://github.com/collectd/collectd
 341
 342 Branch: master
 343
 344 Dependencies: mcelog
 345
 346 Start by installing mcelog. Note: The kernel has to have CONFIG_X86_MCE
 347 enabled. For 32bit kernels you need at least a 2.6,30 kernel.
 348
 349 On ubuntu:
 350
 351 .. code:: bash
 352
 353     $ apt-get update && apt-get install mcelog
 354
 355 Or build from source
 356
 357 .. code:: bash
 358
 359     $ git clone git://git.kernel.org/pub/scm/utils/cpu/mce/mcelog.git
 360     $ cd mcelog
 361     $ make
 362     ... become root ...
 363     $ make install
 364     $ cp mcelog.service /etc/systemd/system/
 365     $ systemctl enable mcelog.service
 366     $ systemctl start mcelog.service
 367
 368 Verify you got a /dev/mcelog. You can verify the daemon is running completely
 369 by running:
 370
 371 .. code:: bash
 372
 373      $ mcelog --client
 374
 375 This should query the information in the running daemon. If it prints nothing
 376 that is fine (no errors logged yet). More info @
 377 http://www.mcelog.org/installation.html
 378
 379 Modify the mcelog configuration file "/etc/mcelog/mcelog.conf" to include or
 380 enable:
 381
 382 .. code:: bash
 383
 384     socket-path = /var/run/mcelog-client
 385
 386 Clone and install the collectd mcelog plugin:
 387
 388 .. code:: bash
 389
 390     $ git clone  https://github.com/maryamtahhan/collectd
 391     $ cd collectd
 392     $ git checkout feat_ras
 393     $ ./build.sh
 394     $ ./configure --enable-syslog --enable-logfile --enable-debug
 395     $ make
 396     $ sudo make install
 397
 398 This will install collectd to /opt/collectd
 399 The collectd configuration file can be found at /opt/collectd/etc
 400 To configure the mcelog plugin you need to modify the configuration file to
 401 include:
 402
 403 .. code:: bash
 404
 405     <LoadPlugin mcelog>
 406       Interval 1
 407     </LoadPlugin>
 408     <Plugin "mcelog">
 409        McelogClientSocket "/var/run/mcelog-client"
 410     </Plugin>
 411
 412 For more information on the plugin parameters, please see:
 413 https://github.com/maryamtahhan/collectd/blob/feat_ras/src/collectd.conf.pod
 414
 415 Simulating a Machine Check Exception can be done in one of 3 ways:
 416
 417 * Running $make test in the mcelog cloned directory - mcelog test suite
 418 * using mce-inject
 419 * using mce-test
 420
 421 **mcelog test suite:**
 422
 423 It is always a good idea to test an error handling mechanism before it is
 424 really needed. mcelog includes a test suite. The test suite relies on
 425 mce-inject which needs to be installed and in $PATH.
 426
 427 You also need the mce-inject kernel module configured (with
 428 CONFIG_X86_MCE_INJECT=y), compiled, installed and loaded:
 429
 430 .. code:: bash
 431
 432     $ modprobe mce-inject
 433
 434 Then you can run the mcelog test suite with
 435
 436 .. code:: bash
 437
 438     $ make test
 439
 440 This will inject different classes of errors and check that the mcelog triggers
 441 runs. There will be some kernel messages about page offlining attempts. The
 442 test will also lose a few pages of memory in your system (not significant)
 443 **Note this test will kill any running mcelog, which needs to be restarted
 444 manually afterwards**.
 445
 446 **mce-inject:**
 447
 448 A utility to inject corrected, uncorrected and fatal machine check exceptions
 449
 450 .. code:: bash
 451
 452     $ git clone https://git.kernel.org/pub/scm/utils/cpu/mce/mce-inject.git
 453     $ cd mce-inject
 454     $ make
 455     $ modprobe mce-inject
 456
 457 Modify the test/corrected script to include the following:
 458
 459 .. code:: bash
 460
 461     CPU 0 BANK 0
 462     STATUS 0xcc00008000010090
 463     ADDR 0x0010FFFFFFF
 464
 465 Inject the error:
 466 .. code:: bash
 467
 468     $ ./mce-inject < test/corrected
 469
 470 **Note: the uncorrected and fatal scripts under test will cause a platform reset.
 471 Only the fatal script generates the memory errors**. In order to  quickly
 472 emulate uncorrected memory errors and avoid host reboot following test errors
 473 from mce-test  suite can be injected:
 474
 475 .. code:: bash
 476
 477        $ mce-inject  mce-test/cases/coverage/soft-inj/recoverable_ucr/data/srao_mem_scrub
 478
 479 **mce-test:**
 480
 481 In addition an more in-depth test of the Linux kernel machine check facilities
 482 can be done with the mce-test test suite. mce-test supports testing uncorrected
 483 error handling, real error injection, handling of different soft offlining
 484 cases, and other tests.
 485
 486 **Corrected memory error injection:**
 487
 488 To inject corrected memory errors:
 489
 490 * Remove sb_edac and edac_core kernel modules: rmmod sb_edac rmmod edac_core
 491 * Insert einj module: modprobe einj param_extension=1
 492 * Inject an error by specifying details (last command should be repeated at least two times):
 493
 494 .. code:: bash
 495
 496     $ APEI_IF=/sys/kernel/debug/apei/einj
 497     $ echo 0x8 > $APEI_IF/error_type
 498     $ echo 0x01f5591000 > $APEI_IF/param1
 499     $ echo 0xfffffffffffff000 > $APEI_IF/param2
 500     $ echo 1 > $APEI_IF/notrigger
 501     $ echo 1 > $APEI_IF/error_inject
 502
 503 * Check the MCE statistic: mcelog --client. Check the mcelog log for injected error details: less /var/log/mcelog.
 504
 505
 506 Open vSwitch Plugins
 507 ---------------------
 508 OvS Events Repo: https://github.com/collectd/collectd
 509
 510 OvS Stats Repo: https://github.com/maryamtahhan/collectd
 511
 512 OvS Events Branch: master
 513
 514 OvS Stats Branch:feat_ovs_stats
 515
 516 Dependencies: Open vSwitch, libyajl
 517
 518 On Ubuntu, install the dependencies:
 519
 520 .. code:: bash
 521
 522     $ sudo apt-get install libyajl-dev openvswitch-switch
 523
 524 Start the Open vSwitch service:
 525
 526 .. code:: bash
 527
 528     $ sudo service openvswitch-switch start
 529
 530 configure the ovsdb-server manager:
 531
 532 .. code:: bash
 533
 534     $ sudo ovs-vsctl set-manager ptcp:6640
 535
 536 Clone and install the collectd ovs plugin:
 537
 538 .. code:: bash
 539
 540     $ git clone $REPO
 541     $ cd collectd
 542     $ git checkout $BRANCH
 543     $ ./build.sh
 544     $ ./configure --enable-syslog --enable-logfile --enable-debug
 545     $ make
 546     $ sudo make install
 547
 548 where $REPO is one of the repos listed at the top of this section.
 549
 550 Where $BRANCH is master or feat_ovs_stats.
 551
 552 This will install collectd to /opt/collectd. The collectd configuration file
 553 can be found at /opt/collectd/etc. To configure the OVS events plugin you
 554 need to modify the configuration file to include:
 555
 556 .. code:: bash
 557
 558     <LoadPlugin ovs_events>
 559        Interval 1
 560     </LoadPlugin>
 561     <Plugin "ovs_events">
 562        Port 6640
 563        Socket "/var/run/openvswitch/db.sock"
 564        Interfaces "br0" "veth0"
 565        SendNotification false
 566     </Plugin>
 567
 568 To configure the OVS stats plugin you need to modify the configuration file
 569 to include:
 570
 571 .. code:: bash
 572
 573     <LoadPlugin ovs_stats>
 574        Interval 1
 575     </LoadPlugin>
 576     <Plugin ovs_stats>
 577        Port "6640"
 578        Address "127.0.0.1"
 579        Socket "/var/run/openvswitch/db.sock"
 580        Bridges "br0" "br_ext"
 581     </Plugin>
 582
 583 For more information on the plugin parameters, please see:
 584 https://github.com/collectd/collectd/blob/master/src/collectd.conf.pod
 585 and
 586 https://github.com/maryamtahhan/collectd/blob/feat_ovs_stats/src/collectd.conf.pod
 587
 588 Installing collectd as a service
 589 --------------------------------
 590 Collectd service scripts are available in the collectd/contrib directory.
 591 To install collectd as a service:
 592
 593 .. code:: bash
 594
 595     $ sudo cp contrib/systemd.collectd.service /etc/systemd/system/
 596     $ cd /etc/systemd/system/
 597     $ sudo mv systemd.collectd.service collectd.service
 598     $ sudo chmod +x collectd.service
 599
 600 Modify collectd.service
 601
 602 .. code:: bash
 603
 604     [Service]
 605     ExecStart=/opt/collectd/sbin/collectd
 606     EnvironmentFile=-/opt/collectd/etc/
 607     EnvironmentFile=-/opt/collectd/etc/
 608     CapabilityBoundingSet=CAP_SETUID CAP_SETGID
 609
 610 Reload
 611
 612 .. code:: bash
 613
 614     $ sudo systemctl daemon-reload
 615     $ sudo systemctl start collectd.service
 616     $ sudo systemctl status collectd.service should show success
 617
 618 Additional useful plugins
 619 --------------------------
 620
 621 Exec Plugin
 622 ~~~~~~~~~~~
 623
 624 Can be used to show you when notifications are being generated by calling a
 625 bash script that dumps notifications to file. (handy for debug). Modify
 626 /opt/collectd/etc/collectd.conf:
 627
 628 .. code:: bash
 629
 630    LoadPlugin exec
 631    <Plugin exec>
 632    #   Exec "user:group" "/path/to/exec"
 633       NotificationExec "user" "<path to barometer>/barometer/src/collectd/collectd_sample_configs/write_notification.sh"
 634    </Plugin>
 635
 636 write_notification.sh (just writes the notification passed from exec through
 637 STDIN to a file (/tmp/notifications)):
 638
 639 .. code:: bash
 640
 641    #!/bin/bash
 642    rm -f /tmp/notifications
 643    while read x y
 644    do
 645      echo $x$y >> /tmp/notifications
 646    done
 647
 648 output to /tmp/notifications should look like:
 649
 650 .. code:: bash
 651
 652     Severity:WARNING
 653     Time:1479991318.806
 654     Host:localhost
 655     Plugin:ovs_events
 656     PluginInstance:br-ex
 657     Type:gauge
 658     TypeInstance:link_status
 659     uuid:f2aafeec-fa98-4e76-aec5-18ae9fc74589
 660
 661     linkstate of "br-ex" interface has been changed to "DOWN"
 662
 663 logfile plugin
 664 ~~~~~~~~~~~~~~~
 665 Can be used to log collectd activity. Modify /opt/collectd/etc/collectd.conf to
 666 include:
 667
 668 .. code:: bash
 669
 670     LoadPlugin logfile
 671     <Plugin logfile>
 672         LogLevel info
 673         File "/var/log/collectd.log"
 674         Timestamp true
 675         PrintSeverity false
 676     </Plugin>
 677
 678 Monitoring Interfaces and Openstack Support
 679 -------------------------------------------
 680 .. Figure:: monitoring_interfaces.png
 681
 682    Monitoring Interfaces and Openstack Support
 683
 684 The figure above shows the DPDK L2 forwarding application running on a compute
 685 node, sending and receiving traffic. collectd is also running on this compute
 686 node retrieving the stats periodically from DPDK through the dpdkstat plugin
 687 and publishing the retrieved stats to Ceilometer through the ceilometer plugin.
 688
 689 To see this demo in action please checkout: `Barometer OPNFV Summit demo`_
 690
 691 References
 692 ----------
 693 .. [1] https://collectd.org/wiki/index.php/Naming_schema
 694 .. [2] https://github.com/collectd/collectd/blob/master/src/daemon/plugin.h
 695 .. [3] https://collectd.org/wiki/index.php/Value_list_t
 696 .. [4] https://collectd.org/wiki/index.php/Data_set
 697 .. [5] https://collectd.org/documentation/manpages/types.db.5.shtml
 698 .. [6] https://collectd.org/wiki/index.php/Data_source
 699 .. [7] https://collectd.org/wiki/index.php/Meta_Data_Interface
 700
 701 .. _Barometer OPNFV Summit demo: https://prezi.com/kjv6o8ixs6se/software-fastpath-service-quality-metrics-demo/
 702 .. _ceilometer plugin: https://github.com/openstack/collectd-ceilometer-plugin/tree/stable/mitaka