X-Git-Url: https://git.octo.it/?p=collectd.git;a=blobdiff_plain;f=docs%2FBUILD.dpdkstat.md;h=457fc0fa30bcafb9012db9c62767591cd58d88c0;hp=b502edd2d3b462a7bdfd53db090bf27d18fe2de9;hb=d5456237d0de8f9905ea7a32f2bbae52b5e3ea73;hpb=92860d61218a3da1e9b74a2fad37e9df88df8ce8 diff --git a/docs/BUILD.dpdkstat.md b/docs/BUILD.dpdkstat.md index b502edd2..457fc0fa 100644 --- a/docs/BUILD.dpdkstat.md +++ b/docs/BUILD.dpdkstat.md @@ -1,7 +1,17 @@ # The dpdkstat plugin +This plugin is optional and only has a specific use case: monitoring DPDK applications +that don't expose stats in any other way than the DPDK xstats API. + **Data Plane Development Kit** (DPDK) is a set of drivers and libraries for fast -packet processing. +packet processing. Please note that this plugin is a polling based plugin rather +than an events based plugin (using it will drive up core utilization on a system). + +**PLEASE DO NOT USE THIS PLUGIN FOR OVS-DPDK**. dpdkstat is really for DPDK +applications that have no other way of exposing stats. For OVS or OVS-with-DPDK the +Open vSwitch plugins available in collectd 5.8.0 should be used for +collecting stats and events. In addition the OVS plugin is events based rather +than polling based and will have a smaller footprint on the system. ## Summary @@ -51,8 +61,8 @@ instruction set manually: 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 + * To configure the DPDK build for the combined shared library and enable autoload + of pmd drivers modify `config/common_base` in your DPDK as follows # # Compile to share library @@ -60,6 +70,10 @@ instruction set manually: -CONFIG_RTE_BUILD_SHARED_LIB=n +CONFIG_RTE_BUILD_SHARED_LIB=y + # Default driver path (or "" to disable) + -CONFIG_RTE_EAL_PMD_PATH="" + +CONFIG_RTE_EAL_PMD_PATH="/usr/lib/dpdk-pmd/" + * Prepare the configuration for the appropriate target as specified at: http://dpdk.org/doc/guides/linux_gsg/build_dpdk.html. @@ -75,6 +89,14 @@ instruction set manually: sudo make install prefix=/usr + * Create dpdk-pmd folder + + mkdir -p /usr/lib/dpdk-pmd + + * Create symlinks to pmd drivers + + find /usr/lib -type f -name 'librte_pmd*' | while read path ; do ln -s $path /usr/lib/dpdk-pmd/`echo $path | grep -o 'librte_.*so'` ; done + **Note 1:** You must run make install as the configuration of collectd with DPDK expects DPDK to be installed somewhere. @@ -84,6 +106,9 @@ instruction set manually: **Note 3:** If you are not root then use sudo to make install DPDK to the appropriate location. + **Note 4:** You **MUST** create symlink to a NIC driver lib. This way collectd + will be able to work with device bound to dpdk. + * Check that the DPDK library has been installed in `/usr/lib` or `/lib`: ls /usr/lib | grep dpdk @@ -133,34 +158,6 @@ instruction set manually: * Run `ldconfig` to update the shared library cache. -### Static library - -To 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 - ## Build collectd with DPDK **Note:** DPDK 16.04 is the minimum version and currently supported version of @@ -184,33 +181,32 @@ implications. See also: 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 collectd with the DPDK shared library. If DPDK is installed in + custom installation path you can specify headers include path using + LIBDPDK_CPPFLAGS variable and libraries path with LIBDPDK_LDFLAGS. + Example: - ./configure --with-libdpdk=/usr + ./configure -### Build with the static DPDK library + or for custom DPKD installation: -To configure collectd with the DPDK static library: + ./configure LIBDPDK_CPPFLAGS="-I/home/joe/include/dpdk" LIBDPDK_LDFLAGS="-L/home/joe/usr/lib" - * Run *configure* with the following CFLAGS: - - ./configure --with-libdpdk=/usr CFLAGS=" -lpthread -Wl,--whole-archive -Wl,-ldpdk -Wl,-lm -Wl,-lrt -Wl,-lpcap -Wl,-ldl -Wl,--no-whole-archive" - - * Make sure that dpdk and dpdkstat are enabled in the *configure* output. + * Make sure that libdpdk and dpdkstat are enabled in the *configure* output. Expected output: Libraries: ... libdpdk . . . . . . . . yes - + Modules: ... dpdkstat . . . . . . .yes * Build collectd: - make -j && make -j install. + 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: @@ -222,6 +218,12 @@ To configure collectd with the DPDK static library: * The same PCI device configuration should be passed to the primary process as the secondary process uses the same port indexes as the primary. * A blacklist / whitelist of NICs isn't supported yet. + * Plugin initialization time depends on read interval. It requires 5 read + cycles to set up internal buffers and states. During that time no statistics + are submitted. + * If number of DPDK ports is increased while plugin is running, internal + buffers are resized. That requires 3 read cycles and no port statistics + are submitted in that time. ## License