X-Git-Url: https://git.octo.it/?a=blobdiff_plain;f=README;h=4741a7a76513fa04290ec5b2c55f9004df237c18;hb=04f27bdd38966e0b826b283d8790ce31fb467929;hp=2d552e436da19aa7e360f90e5cf858822aa36dd0;hpb=d061c270fabc5dba961cf2b94ebe968e9a89b899;p=collectd.git diff --git a/README b/README index 2d552e43..4741a7a7 100644 --- a/README +++ b/README @@ -96,6 +96,9 @@ Features DNS traffic: Query types, response codes, opcodes and traffic/octets transferred. + - dpdkstat + Collect DPDK interface statistics. + - drbd Collect individual drbd resource statistics. @@ -129,11 +132,16 @@ Features Monitor gps related data through gpsd. - grpc - Receive values over the network using the gRPC framework. + Send and receive values over the network using the gRPC framework. - hddtemp Hard disk temperatures using hddtempd. + - hugepages + Report the number of used and free hugepages. More info on + hugepages can be found here: + https://www.kernel.org/doc/Documentation/vm/hugetlbpage.txt. + - interface Interface traffic: Number of octets, packets and errors for each interface. @@ -1012,6 +1020,141 @@ Crosscompiling * `endianflip' (12345678 -> 87654321) * `intswap' (12345678 -> 56781234) +Configuring with DPDK +--------------------- + +Note: DPDK 16.04 is the minimum version and currently supported version of DPDK +required for the dpdkstat plugin. This is to allow the plugin to take advantage +of functions added to detect if the DPDK primary process is alive. + +Note: For Ubuntu, GCC 4.9 is the minimum version required to build collectd +with DPDK. Ubuntu 14.04, for example, has GCC 4.8 by default and will require +an upgrade: + $ sudo add-apt-repository ppa:ubuntu-toolchain-r/test + $ sudo apt-get update + $ sudo apt-get install gcc-4.9 +Alternatively, if you know that the platform that you wish to run collectd +on supports the SSSE3 instruction set, you can run make as follows: + $ make -j CFLAGS+='-mssse3' + +Build DPDK for use with collectd: + To compile DPDK for use with collectd dpdkstat start by: + - Clone DPDK: + $ git clone git://dpdk.org/dpdk + - Checkout the system requirements at + http://dpdk.org/doc/guides/linux_gsg/sys_reqs.html and make sure you have + the required tools and hugepage setup as specified there. + NOTE: It's recommended to use the 1GB hugepage setup for best performance, + please follow the instruction for "Reserving Hugepages for DPDK Use" + in the link above. + However if you plan on configuring 2MB hugepages on the fly please ensure + to add appropriate commands to reserve hugepages in a system startup script + if collectd is booted at system startup time. These commands include: + mkdir -p /mnt/huge + mount -t hugetlbfs nodev /mnt/huge + echo 64 > /sys/devices/system/node/node0/hugepages/hugepages-2048kB/nr_hugepages + - To configure the DPDK build for the combined shared library modify + config/common_base in your DPDK as follows + # + # Compile to share library + # + -CONFIG_RTE_BUILD_SHARED_LIB=n + +CONFIG_RTE_BUILD_SHARED_LIB=y + - Prepare the configuration for the appropriate target as specified at: + http://dpdk.org/doc/guides/linux_gsg/build_dpdk.html. + For example: + $ make config T=x86_64-native-linuxapp-gcc + - Build the target: + $ make + - Install DPDK to /usr + $ sudo make install prefix=/usr + NOTE 1: You must run make install as the configuration of collectd with + DPDK expects DPDK to be installed somewhere. + NOTE 2: If you don't specify a prefix then DPDK will be installed in /usr/local/ + NOTE 3: If you are not root then use sudo to make install DPDK to the appropriate + location. + - Check that the DPDK library has been installed in /usr/lib or /lib + $ ls /usr/lib | grep dpdk + - Bind the interfaces to use with dpdkstat to DPDK: + DPDK devices can be setup with either the VFIO (for DPDK 1.7+) or UIO modules. + Note: UIO requires inserting an out of tree driver igb_uio.ko that is available + in DPDK. + UIO Setup: + - Insert uio.ko: + $ sudo modprobe uio + - Insert igb_uio.ko: + $ sudo insmod $DPDK_BUILD/kmod/igb_uio.ko + - Bind network device to igb_uio: + $ sudo $DPDK_DIR/tools/dpdk_nic_bind.py --bind=igb_uio eth1 + VFIO Setup: + - VFIO needs to be supported in the kernel and the BIOS. More information can be found + @ http://dpdk.org/doc/guides/linux_gsg/build_dpdk.html. + - Insert the `vfio-pci.ko' module: modprobe vfio-pci + - Set the correct permissions for the vfio device: + $ sudo /usr/bin/chmod a+x /dev/vfio + $ sudo /usr/bin/chmod 0666 /dev/vfio/* + - Bind the network device to vfio-pci: + $ sudo $DPDK_DIR/tools/dpdk_nic_bind.py --bind=vfio-pci eth1 + NOTE: Please ensure to add appropriate commands to bind the network + interfaces to DPDK in a system startup script if collectd is + booted at system startup time. + - Run ldconfig to update the shared library cache. + + Build static DPDK library for use with collectd: + - To configure DPDK to build the combined static library libdpdk.a + ensure that CONFIG_RTE_BUILD_SHARED_LIB is set to n in + config/common_base in your DPDK as follows: + # + # Compile to share library + # + CONFIG_RTE_BUILD_SHARED_LIB=n + - Prepare the configuration for the appropriate target as specified at: + http://dpdk.org/doc/guides/linux_gsg/build_dpdk.html. + For example: + $ make config T=x86_64-native-linuxapp-gcc + - Build the target using -fPIC: + $ make EXTRA_CFLAGS=-fPIC -j + - Install DPDK to /usr + $ sudo make install prefix=/usr + +Configure collectd with DPDK: +NOTE: The Address-Space Layout Randomization (ASLR) security feature in Linux should + be disabled, in order for the same hugepage memory mappings to be present in all + DPDK multi-process applications. Note that this has security implications. + To disable ASLR: + $ echo 0 > /proc/sys/kernel/randomize_va_space + To fully enable ASLR: + $ echo 2 > /proc/sys/kernel/randomize_va_space + See http://dpdk.org/doc/guides/prog_guide/multi_proc_support.html + + - Generate the build script as specified below. (i.e. run `build.sh'). + - Configure collectd with the DPDK shared library: + ./configure --with-libdpdk=/usr + NOTE: To configure collectd with the DPDK static library: + ./configure --with-libdpdk=/usr CFLAGS=" -lpthread -Wl,--whole-archive + -Wl,-ldpdk -Wl,-lm -Wl,-lrt -Wl,-lpcap -Wl,-ldl -Wl,--no-whole-archive" + + Libraries: + ... + libdpdk . . . . . . . . yes + + Modules: + ... + dpdkstat . . . . . . .yes + + + - Make sure that dpdk and dpdkstat are enabled in the configuration log: + + - Build collectd: + $ make -j && make -j install. + NOTE: As mentioned above, if you are building on Ubuntu 14.04 with GCC <= 4.8.X, + you need to use: + $ make -j CFLAGS+='-mssse3' && make -j install + +Usage of dpdkstat: + - The same PCI device configuration should be passed to the primary process + as the secondary process uses the same port indexes as the primary. + NOTE: A blacklist/whitelist of NICs isn't supported yet. Contact ------- @@ -1031,6 +1174,5 @@ Author Sebastian tokkee Harl , and many contributors (see `AUTHORS'). - Please send bug reports and patches to the mailing list, see `Contact' - above. - + Please use GitHub reporting bugs and submitting pull requests. + See CONTRIBUTING.md for details.