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