diff options
Diffstat (limited to 'docs')
15 files changed, 418 insertions, 145 deletions
diff --git a/docs/release/release-notes/index.rst b/docs/release/release-notes/index.rst index 6185fc97..3f676753 100644 --- a/docs/release/release-notes/index.rst +++ b/docs/release/release-notes/index.rst @@ -12,6 +12,7 @@ Anuket Barometer Release Notes :maxdepth: 1 unreleased + lakelse-release-notes kali-release-notes old-release-notes diff --git a/docs/release/release-notes/lakelse-release-notes.rst b/docs/release/release-notes/lakelse-release-notes.rst new file mode 100644 index 00000000..bf04342e --- /dev/null +++ b/docs/release/release-notes/lakelse-release-notes.rst @@ -0,0 +1,164 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. (c) Anuket and others. + +============================ +Lakelse Release Notes +============================ + +.. _Release Notes_lakelse: + +Lakelse +======= + +.. _Release Notes_lakelse_Release Summary: + +Release Summary +--------------- + +.. docs/release/release-notes/notes/lakelse/add_unix_sock-e29efe16156c5c8e.yaml @ None + +Added unixsock plugin to one-click install. + + +.. docs/release/release-notes/notes/lakelse/ansible-build-containers-b4a4cc9cb70f83b3.yaml @ None + +Add ansible playbook for building the containers locally. + + +.. docs/release/release-notes/notes/lakelse/anuket_containers-21b4206cb26c9975.yaml @ None + +Since the anuket dockerhub repository was created, and containers are being pushed to there, instructions and build scripts have been updated to reflect this. + + +.. docs/release/release-notes/notes/lakelse/collectd-5-v-6-testing-cc821b32bad2794c.yaml @ None + +Testing playbooks were added to compare collectd5 vs collectd6, for the purpose of helping to review new PRs by comparing the generated metrics between versions. + + +.. docs/release/release-notes/notes/lakelse/remove_dpdk_stats_events_plugins-59f366855f6e4261.yaml @ None + +Remove dpdkstats and dpdkevents from Barometer. + + +.. docs/release/release-notes/notes/lakelse/update_logparser_config-0db3d2746e6ad582.yaml @ None + +Enable the Logparser plugin by default when using one-click install. + + +.. _Release Notes_lakelse_Testing Notes: + +Testing Notes +------------- + +.. docs/release/release-notes/notes/lakelse/collectd-5-v-6-testing-cc821b32bad2794c.yaml @ None + +- Added a playbook to compare collectd 5 and collectd 6. The playbook uses + existing ansible roles to build both collectd 5 and collectd 6 container + images, creates a common configuration, then runs the containers and shows + the outputs to let the user inspect the metrics and whether they match. + + +.. _Release Notes_lakelse_Documentation Updates: + +Documentation Updates +--------------------- + +.. docs/release/release-notes/notes/lakelse/anuket_containers-21b4206cb26c9975.yaml @ None + +- Docs have been updated to use anuket/ repository in dockerhub. + Container build instructions now use anuket/ prefix to tag images. + + +.. _Release Notes_lakelse_Container updates: + +Container updates +----------------- + +.. docs/release/release-notes/notes/lakelse/anuket_containers-21b4206cb26c9975.yaml @ None + +- Containers are now pulled from anuket/ repository in dockerhub. + +.. docs/release/release-notes/notes/lakelse/collectd-6-testing-flask-app-2bb0ca1326775dd8.yaml @ None + +- Add a flask app for testing collectd using metrics sent via write_http plugin. + +.. docs/release/release-notes/notes/lakelse/update-grafana-9bee82ecfa11f54a.yaml @ None + +- Grafana container was updated to support both jiffies and percent for cpu metrics. + + +.. _Release Notes_lakelse_Ansible playbook updates: + +Ansible playbook updates +------------------------ + +.. docs/release/release-notes/notes/lakelse/add_unix_sock-e29efe16156c5c8e.yaml @ None + +- Added `unixsock <https://collectd.org/documentation/manpages/collectd-unixsock.5.shtml>`_ + plugin to one-click install, which allows the user to interact with collectd using the + ``collectdctl`` command in the bar-collectd-* containers. + The unixsock plugin is useful for debugging issues in collectd, and can + be used to verify that metrics are being collected without having to + create CSV files or log into the container. + +.. docs/release/release-notes/notes/lakelse/ansible-build-containers-b4a4cc9cb70f83b3.yaml @ None + +- Added a playbook and role for building the collectd containers locally. + This automates the actions described in the docker install guide. The + ``barometer-collectd``, ``barometer-collectd-latest`` and the + ``barometer-collectd-experimental`` containers are now easier to build + locally. The ``barometer-collectd-6`` and + ``barometer-collectd-experimental`` containers can also be built with + arbirtary PRs applied, to aid in testing locally. + +.. docs/release/release-notes/notes/lakelse/anuket_containers-21b4206cb26c9975.yaml @ None + +- Containers are now pulled from anuker/ repository in dockerhub. + +.. docs/release/release-notes/notes/lakelse/update_logparser_config-0db3d2746e6ad582.yaml @ None + +- The logparser plugin is now rendered for all flavours. + The Logparser plugin has been part of collectd since 5.11, however, the ansible playbooks had it marked as experimental, and would not deploy it by default. + + +.. _Release Notes_lakelse_Build script updates: + +Build script updates +-------------------- + +.. docs/release/release-notes/notes/lakelse/update-apply-pr-script-46e6d547d331c5f2.yaml @ None + +- Update collectd_apply_pull_request.sh to rebase only if multiple chanegs are selected. The script will checkout the PR branch if there's only one PR_ID passed. + + +.. _Release Notes_lakelse_Normal Bug Fixes: + +Normal Bug Fixes +---------------- + +.. docs/release/release-notes/notes/lakelse/update-grafana-9bee82ecfa11f54a.yaml @ None + +- Update the grafana dashboard to show metrics in both jffies and percent, depending on what is configured. + + +.. _Release Notes_lakelse_Deprecations: + +Deprecations +------------ + +.. docs/release/release-notes/notes/lakelse/remove_dpdk_stats_events_plugins-59f366855f6e4261.yaml @ None + +- The dpdkstats and dpdkevents plugins were removed from Barometer. These + plugins are still available in collectd, however, will not be deployed by + Barometer. It is recommended that the DPDK telemetry plugin be used instead. + + +.. _Release Notes_lakelse_Other Notes: + +Other Notes +----------- + +.. docs/release/release-notes/notes/lakelse/add-reno-12eb20e3448b663b.yaml @ None + +- Add `reno <https://docs.openstack.org/reno/latest/index.html#>`_ and corresponding tox jobs (compile notes and add new notes) to make compiling release notes easier diff --git a/docs/release/release-notes/notes/add-reno-12eb20e3448b663b.yaml b/docs/release/release-notes/notes/add-reno-12eb20e3448b663b.yaml index c0e8c7e9..2456c099 100644 --- a/docs/release/release-notes/notes/add-reno-12eb20e3448b663b.yaml +++ b/docs/release/release-notes/notes/add-reno-12eb20e3448b663b.yaml @@ -4,4 +4,4 @@ documentation: Release notes are now automatically generated and included in the documentation using `reno <https://docs.openstack.org/reno/latest/index.html>`_. other: - | - Add `reno <https://docs.openstack.org/reno/latest/index.html#>`_ and corresponding tox jobs to make compiling release notes easier + Add `reno <https://docs.openstack.org/reno/latest/index.html#>`_ and corresponding tox jobs (compile notes and add new notes) to make compiling release notes easier diff --git a/docs/release/release-notes/notes/ansible-build-containers-b4a4cc9cb70f83b3.yaml b/docs/release/release-notes/notes/ansible-build-containers-b4a4cc9cb70f83b3.yaml new file mode 100644 index 00000000..aae4b999 --- /dev/null +++ b/docs/release/release-notes/notes/ansible-build-containers-b4a4cc9cb70f83b3.yaml @@ -0,0 +1,11 @@ +release_summary: > + Add ansible playbook for building the containers locally. +ansible: + - | + Added a playbook and role for building the collectd containers locally. + This automates the actions described in the docker install guide. The + ``barometer-collectd``, ``barometer-collectd-latest`` and the + ``barometer-collectd-experimental`` containers are now easier to build + locally. The ``barometer-collectd-6`` and + ``barometer-collectd-experimental`` containers can also be built with + arbirtary PRs applied, to aid in testing locally. diff --git a/docs/release/release-notes/notes/anuket_containers-21b4206cb26c9975.yaml b/docs/release/release-notes/notes/anuket_containers-21b4206cb26c9975.yaml new file mode 100644 index 00000000..75e7e4f0 --- /dev/null +++ b/docs/release/release-notes/notes/anuket_containers-21b4206cb26c9975.yaml @@ -0,0 +1,12 @@ +release_summary: > + Since the anuket dockerhub repository was created, and containers are being pushed to there, instructions and build scripts have been updated to reflect this. +docs: + - | + Docs have been updated to use anuket/ repository in dockerhub. + Container build instructions now use anuket/ prefix to tag images. +containers: + - | + Containers are now pulled from anuket/ repository in dockerhub. +ansible: + - | + Containers are now pulled from anuker/ repository in dockerhub. diff --git a/docs/release/release-notes/notes/collectd-5-v-6-testing-cc821b32bad2794c.yaml b/docs/release/release-notes/notes/collectd-5-v-6-testing-cc821b32bad2794c.yaml new file mode 100644 index 00000000..20013147 --- /dev/null +++ b/docs/release/release-notes/notes/collectd-5-v-6-testing-cc821b32bad2794c.yaml @@ -0,0 +1,10 @@ +release_summary: > + Testing playbooks were added to compare collectd5 vs collectd6, for the + purpose of helping to review new PRs by comparing the generated metrics + between versions. +testing: + - | + Added a playbook to compare collectd 5 and collectd 6. The playbook uses + existing ansible roles to build both collectd 5 and collectd 6 container + images, creates a common configuration, then runs the containers and shows + the outputs to let the user inspect the metrics and whether they match. diff --git a/docs/release/release-notes/notes/collectd-6-testing-flask-app-2bb0ca1326775dd8.yaml b/docs/release/release-notes/notes/collectd-6-testing-flask-app-2bb0ca1326775dd8.yaml new file mode 100644 index 00000000..9c605876 --- /dev/null +++ b/docs/release/release-notes/notes/collectd-6-testing-flask-app-2bb0ca1326775dd8.yaml @@ -0,0 +1,3 @@ +containers: + - | + Add a flask app for testing collectd using metrics sent via write_http plugin. diff --git a/docs/release/release-notes/notes/remove_dpdk_stats_events_plugins-59f366855f6e4261.yaml b/docs/release/release-notes/notes/remove_dpdk_stats_events_plugins-59f366855f6e4261.yaml new file mode 100644 index 00000000..78ab1c4c --- /dev/null +++ b/docs/release/release-notes/notes/remove_dpdk_stats_events_plugins-59f366855f6e4261.yaml @@ -0,0 +1,8 @@ +--- +release_summary: > + Remove dpdkstats and dpdkevents from Barometer. +deprecations: + - | + The dpdkstats and dpdkevents plugins were removed from Barometer. These + plugins are still available in collectd, however, will not be deployed by + Barometer. It is recommended that the DPDK telemetry plugin be used instead. diff --git a/docs/release/release-notes/notes/update-apply-pr-script-46e6d547d331c5f2.yaml b/docs/release/release-notes/notes/update-apply-pr-script-46e6d547d331c5f2.yaml new file mode 100644 index 00000000..de1be994 --- /dev/null +++ b/docs/release/release-notes/notes/update-apply-pr-script-46e6d547d331c5f2.yaml @@ -0,0 +1,3 @@ +build: + - | + Update collectd_apply_pull_request.sh to rebase only if multiple chanegs are selected. The script will checkout the PR branch if there's only one PR_ID passed. diff --git a/docs/release/release-notes/notes/update-grafana-9bee82ecfa11f54a.yaml b/docs/release/release-notes/notes/update-grafana-9bee82ecfa11f54a.yaml new file mode 100644 index 00000000..95e2cbdb --- /dev/null +++ b/docs/release/release-notes/notes/update-grafana-9bee82ecfa11f54a.yaml @@ -0,0 +1,6 @@ +containers: + - | + Grafana container was updated to support both jiffies and percent for cpu metrics. +fixes: + - | + Update the grafana dashboard to show metrics in both jffies and percent, depending on what is configured. diff --git a/docs/release/release-notes/notes/update_logparser_config-0db3d2746e6ad582.yaml b/docs/release/release-notes/notes/update_logparser_config-0db3d2746e6ad582.yaml new file mode 100644 index 00000000..e5be3eff --- /dev/null +++ b/docs/release/release-notes/notes/update_logparser_config-0db3d2746e6ad582.yaml @@ -0,0 +1,6 @@ +release_summary: > + Enable the Logparser plugin by default when using one-click install. +ansible: + - | + The logparser plugin is now rendered for all flavours. + The Logparser plugin has been part of collectd since 5.11, however, the ansible playbooks had it marked as experimental, and would not deploy it by default. diff --git a/docs/release/userguide/feature.userguide.rst b/docs/release/userguide/feature.userguide.rst index 02f8bdaa..2750bd8d 100644 --- a/docs/release/userguide/feature.userguide.rst +++ b/docs/release/userguide/feature.userguide.rst @@ -22,26 +22,15 @@ to support thresholding and notification. Barometer has enabled the following collectd plugins: -* *dpdkstat plugin*: A read plugin that retrieves stats from the DPDK extended - NIC stats API. - -* *dpdkevents plugin*: A read plugin that retrieves DPDK link status and DPDK - forwarding cores liveliness status (DPDK Keep Alive). - * *dpdk_telemetry plugin*: A read plugin to collect dpdk interface stats and - application or global stats from dpdk telemetry library. Both 'dpdkstat' and - 'dpdk_telemetry' plugins provides dpdk NIC Stats, but only 'dpdk_telemetry' - provides the DPDK Application stats. So in other words, 'dpdk_telemetry' is - an advanced version of dpdkstat. This plugin don't deal with dpdk events. - So not in related with 'dpdkevents' plugin. The mimimum dpdk version required - to use this plugin is 19.08. + application or global stats from dpdk telemetry library. The ``dpdk_telemetry`` + plugin provides both DPDK NIC Stats and DPDK application stats. + This plugin doesn't deal with dpdk events. + The mimimum dpdk version required to use this plugin is 19.08. .. note:: - dpdpkstat and dpdk_telemetry should not be used together. Use dpdk_telemetry - if your version of dpdk supports it (i.e. DPDK >= 19.08) and use dpdkstat otherwise. - dpdkstat, dpdkevents and dpdk_telemetry plugins should only be used if your dpdk - application doesn't already have more relevant metrics available(e.g.ovs_stats). - + The ``dpdk_telemetry`` plugin should only be used if your dpdk application + doesn't already have more relevant metrics available (e.g.ovs_stats). * `gnocchi plugin`_: A write plugin that pushes the retrieved stats to Gnocchi. It's capable of pushing any stats read through collectd to @@ -175,15 +164,15 @@ collectd, check out the `collectd-openstack-plugins GSG`_. Below is the per plugin installation and configuration guide, if you only want to install some/particular plugins. -DPDK plugins -^^^^^^^^^^^^^ +DPDK telemetry plugin +^^^^^^^^^^^^^^^^^^^^^ Repo: https://github.com/collectd/collectd Branch: main -Dependencies: `DPDK <https://www.dpdk.org/>`_ +Dependencies: `DPDK <https://www.dpdk.org/>`_ (runtime), libjansson (compile-time) -.. note:: DPDK statistics plugin requires DPDK version 16.04 or later. +.. note:: DPDK telemetry plugin requires DPDK version 19.08 or later. To build and install DPDK to /usr please see: https://github.com/collectd/collectd/blob/main/docs/BUILD.dpdkstat.md @@ -199,53 +188,35 @@ Building and installing collectd: $ make $ sudo make install -.. note:: If DPDK was installed in a non standard location you will need to - specify paths to the header files and libraries using *LIBDPDK_CPPFLAGS* and - *LIBDPDK_LDFLAGS*. You will also need to add the DPDK library symbols to the - shared library path using *ldconfig*. Note that this update to the shared - library path is not persistant (i.e. it will not survive a reboot). - -Example of specifying custom paths to DPDK headers and libraries: - -.. code:: bash - - $ ./configure LIBDPDK_CPPFLAGS="path to DPDK header files" LIBDPDK_LDFLAGS="path to DPDK libraries" - This will install collectd to default folder ``/opt/collectd``. The collectd configuration file (``collectd.conf``) can be found at ``/opt/collectd/etc``. -To configure the dpdkstats plugin you need to modify the configuration file to -include (uncomment lines as appropriate): -.. literalinclude:: ../../../src/collectd/collectd_sample_configs/dpdkstat.conf - :start-at: LoadPlugin - :language: bash +To configure the dpdk_telemetry plugin you need to modify the configuration file to +include: -To configure the dpdkevents plugin you need to modify the configuration file to -include (uncomment lines as appropriate): +.. code:: bash -.. literalinclude:: ../../../src/collectd/collectd_sample_configs/dpdkevents.conf - :start-at: LoadPlugin - :language: bash + LoadPlugin dpdk_telemetry + <Plugin dpdk_telemetry> + #ClientSocketPath "/var/run/.client" + #DpdkSocketPath "/var/run/dpdk/rte/telemetry" + </Plugin> -.. note:: Currently, the DPDK library doesn’t support API to de-initialize - the DPDK resources allocated on the initialization. It means, the collectd - plugin will not be able to release the allocated DPDK resources - (locks/memory/pci bindings etc.) correctly on collectd shutdown or reinitialize - the DPDK library if primary DPDK process is restarted. The only way to release - those resources is to terminate the process itself. For this reason, the plugin - forks off a separate collectd process. This child process becomes a secondary - DPDK process which can be run on specific CPU cores configured by user through - collectd configuration file (“Coremask” EAL configuration option, the - hexadecimal bitmask of the cores to run on). +The plugin uses default values (as shown) for the socket paths, if you use different values, +uncomment and update ``ClientSocketPath`` and ``DpdkSocketPath`` as required. For more information on the plugin parameters, please see: https://github.com/collectd/collectd/blob/main/src/collectd.conf.pod -.. note:: dpdkstat 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. Also, if plugin is running and the number of DPDK - ports is increased, internal buffers are resized. That requires 3 read cycles - and no port statistics are submitted during that time. +.. note:: + + To gather metrics from a DPDK application, telemetry needs to be enabled. + This can be done by setting the ``CONFIG_RTE_LIBRTE_TELEMETRY=y`` config flag. + The application then needs to be run with the ``--telemetry`` EAL option, e.g. + :: + $dpdk/app/testpmd --telemetry -l 2,3,4 -n 4 + +For more information on the ``dpdk_telemetry`` plugin, see the `anuket wiki <https://wiki.anuket.io/display/HOME/DPDK+Telemetry+Plugin>`_. 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 @@ -270,27 +241,6 @@ To fully enable ASLR: For more information on multi-process support, please see: https://doc.dpdk.org/guides/prog_guide/multi_proc_support.html -**DPDK stats plugin limitations:** - -1. The DPDK primary process application should use the same version of DPDK - that collectd DPDK plugin is using; - -2. L2 statistics are only supported; - -3. The plugin has been tested on Intel NIC’s only. - -**DPDK stats known issues:** - -* DPDK port visibility - - When network port controlled by Linux is bound to DPDK driver, the port - will not be available in the OS. It affects the SNMP write plugin as those - ports will not be present in standard IF-MIB. Thus, additional work is - required to be done to support DPDK ports and statistics. - -**DPDK telemetry plugin** - -Please refer to https://wiki.anuket.io/display/HOME/DPDK+Telemetry+Plugin Hugepages Plugin ^^^^^^^^^^^^^^^^^ diff --git a/docs/release/userguide/installguide.docker.rst b/docs/release/userguide/installguide.docker.rst index 38d467a4..9141eef6 100644 --- a/docs/release/userguide/installguide.docker.rst +++ b/docs/release/userguide/installguide.docker.rst @@ -12,14 +12,14 @@ Anuket Barometer Docker Install Guide :local: The intention of this user guide is to outline how to install and test the Barometer project's -docker images. The `OPNFV docker hub <https://hub.docker.com/u/opnfv/?page=1>`_ contains 5 docker +docker images. The `Anuket docker hub <https://hub.docker.com/u/anuket/>`_ contains 5 docker images from the Barometer project: - 1. `Collectd docker image <https://hub.docker.com/r/opnfv/barometer-collectd/>`_ - 2. `Influxdb docker image <https://hub.docker.com/r/opnfv/barometer-influxdb/>`_ - 3. `Grafana docker image <https://hub.docker.com/r/opnfv/barometer-grafana/>`_ - 4. `Kafka docker image <https://hub.docker.com/r/opnfv/barometer-kafka/>`_ - 5. `VES application docker image <https://hub.docker.com/r/opnfv/barometer-ves/>`_ + 1. `Collectd docker image <https://hub.docker.com/r/anuket/barometer-collectd/>`_ + 2. `Influxdb docker image <https://hub.docker.com/r/anuket/barometer-influxdb/>`_ + 3. `Grafana docker image <https://hub.docker.com/r/anuket/barometer-grafana/>`_ + 4. `Kafka docker image <https://hub.docker.com/r/anuket/barometer-kafka>`_ + 5. `VES application docker image <https://hub.docker.com/r/anuket/barometer-ves/>`_ For description of images please see section `Barometer Docker Images Description`_ @@ -305,11 +305,11 @@ are stored in subdirectories of `docker/` directory Download the collectd docker image ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If you wish to use a pre-built barometer image, you can pull the barometer -image from `dockerhub <https://hub.docker.com/r/opnfv/barometer-collectd/>`_ +image from `dockerhub <https://hub.docker.com/r/anuket/barometer-collectd/>`_ .. code:: bash - $ docker pull opnfv/barometer-collectd + $ docker pull anuket/barometer-collectd Build stable collectd container ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -317,7 +317,7 @@ Build stable collectd container .. code:: bash $ cd <BAROMETER_REPO_DIR>/docker/barometer-collectd - $ sudo docker build -t opnfv/barometer-collectd --build-arg http_proxy=`echo $http_proxy` \ + $ sudo docker build -t anuket/barometer-collectd --build-arg http_proxy=`echo $http_proxy` \ --build-arg https_proxy=`echo $https_proxy` --network=host -f Dockerfile . .. note:: @@ -330,12 +330,12 @@ Check the docker images: $ sudo docker images -Output should contain a barometer-collectd image: +Output should contain a ``barometer-collectd`` image: .. code:: REPOSITORY TAG IMAGE ID CREATED SIZE - opnfv/barometer-collectd latest 05f2a3edd96b 3 hours ago 1.2GB + anuket/barometer-collectd latest 39f5e0972178 2 months ago 1.28GB centos 7 196e0ce0c9fb 4 weeks ago 197MB centos latest 196e0ce0c9fb 4 weeks ago 197MB hello-world latest 05a3bd381fc2 4 weeks ago 1.84kB @@ -352,7 +352,7 @@ Build barometer-collectd-latest container .. code:: bash $ cd <BAROMETER_REPO_DIR> - $ sudo docker build -t opnfv/barometer-collectd-latest \ + $ sudo docker build -t anuket/barometer-collectd-latest \ --build-arg http_proxy=`echo $http_proxy` \ --build-arg https_proxy=`echo $https_proxy` --network=host -f \ docker/barometer-collectd-latest/Dockerfile . @@ -374,7 +374,7 @@ COLLECTD_PULL_REQUESTS should be a comma-delimited string of pull request IDs. .. code:: bash $ cd <BAROMETER_REPO_DIR> - $ sudo docker build -t opnfv/barometer-collectd-experimental \ + $ sudo docker build -t anuket/barometer-collectd-experimental \ --build-arg http_proxy=`echo $http_proxy` \ --build-arg https_proxy=`echo $https_proxy` \ --build-arg COLLECTD_PULL_REQUESTS=1234,5678 \ @@ -397,7 +397,7 @@ proposed patches to collectd. .. code:: bash $ cd <BAROMETER_REPO_DIR> - $ sudo docker build -t opnfv/barometer-collectd-6 \ + $ sudo docker build -t anuket/barometer-collectd-6 \ --build-arg COLLECTD_FLAVOR=collectd-6 \ --build-arg COLLECTD_PULL_REQUESTS=1234,5678 \ --network=host -f docker/barometer-collectd-experimental/Dockerfile . @@ -431,7 +431,7 @@ Run the collectd stable docker image $ sudo docker run -ti --net=host -v \ `pwd`/src/collectd/collectd_sample_configs:/opt/collectd/etc/collectd.conf.d \ -v /var/run:/var/run -v /tmp:/tmp -v /sys/fs/resctrl:/sys/fs/resctrl \ - --privileged opnfv/barometer-collectd + --privileged anuket/barometer-collectd .. note:: The docker collectd image contains configuration for all the collectd @@ -450,8 +450,7 @@ Run the collectd stable docker image files should be removed from shared configuration directory (`<BAROMETER_REPO_DIR>/src/collectd/collectd_sample_configs/`) prior to starting barometer-collectd container. By example: in case of missing - `DPDK` functionality on the host, `dpdkstat.conf` and `dpdkevents.conf` - should be removed. + `DPDK` functionality on the host, `dpdk_telemetry.conf` should be removed. Sample configurations can be found at: https://github.com/opnfv/barometer/tree/master/src/collectd/collectd_sample_configs @@ -492,7 +491,7 @@ collectd plugins requiring different configuration files) $ sudo docker run -ti --net=host -v \ `pwd`/src/collectd/collectd_sample_configs-latest:/opt/collectd/etc/collectd.conf.d \ -v /var/run:/var/run -v /tmp:/tmp -v /sys/fs/resctrl:/sys/fs/resctrl \ - --privileged opnfv/barometer-collectd-latest + --privileged anuket/barometer-collectd-latest .. note:: Barometer collectd docker images are sharing some directories with host @@ -534,7 +533,7 @@ collectd container) $ sudo docker run -ti --net=host -v \ `pwd`/src/collectd/collectd_sample_configs-latest:/opt/collectd/etc/collectd.conf.d \ -v /var/run:/var/run -v /tmp:/tmp -v /sys/fs/resctrl:/sys/fs/resctrl --privileged \ - opnfv/barometer-collectd-experimental + anuket/barometer-collectd-experimental .. note:: The Resource Control file system (/sys/fs/resctrl) can be bound from host to @@ -572,7 +571,7 @@ volume folder been mounted. Appropriate example are given in section `Run the Gr Download the InfluxDB and Grafana docker images ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If you wish to use pre-built barometer project's influxdb and grafana images, you can pull the -images from https://hub.docker.com/r/opnfv/barometer-influxdb/ and https://hub.docker.com/r/opnfv/barometer-grafana/ +images from https://hub.docker.com/r/anuket/barometer-influxdb/ and https://hub.docker.com/r/anuket/barometer-grafana/ .. note:: If your preference is to build images locally please see sections `Build InfluxDB Docker Image`_ and @@ -580,8 +579,8 @@ images from https://hub.docker.com/r/opnfv/barometer-influxdb/ and https://hub.d .. code:: bash - $ docker pull opnfv/barometer-influxdb - $ docker pull opnfv/barometer-grafana + $ docker pull anuket/barometer-influxdb + $ docker pull anuket/barometer-grafana .. note:: If you have pulled the pre-built barometer-influxdb and barometer-grafana images there is no @@ -597,7 +596,7 @@ Build influxdb image from Dockerfile .. code:: bash $ cd barometer/docker/barometer-influxdb - $ sudo docker build -t opnfv/barometer-influxdb --build-arg http_proxy=`echo $http_proxy` \ + $ sudo docker build -t anuket/barometer-influxdb --build-arg http_proxy=`echo $http_proxy` \ --build-arg https_proxy=`echo $https_proxy` --network=host -f Dockerfile . .. note:: @@ -615,7 +614,7 @@ Output should contain an influxdb image: .. code:: REPOSITORY TAG IMAGE ID CREATED SIZE - opnfv/barometer-influxdb latest 1e4623a59fe5 3 days ago 191MB + anuket/barometer-influxdb latest c5a09a117067 2 months ago 191MB Build Grafana docker image ^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -625,7 +624,7 @@ Build Grafana image from Dockerfile .. code:: bash $ cd barometer/docker/barometer-grafana - $ sudo docker build -t opnfv/barometer-grafana --build-arg http_proxy=`echo $http_proxy` \ + $ sudo docker build -t anuket/barometer-grafana --build-arg http_proxy=`echo $http_proxy` \ --build-arg https_proxy=`echo $https_proxy` -f Dockerfile . .. note:: @@ -643,7 +642,7 @@ Output should contain an influxdb image: .. code:: REPOSITORY TAG IMAGE ID CREATED SIZE - opnfv/barometer-grafana latest 05f2a3edd96b 3 hours ago 1.2GB + anuket/barometer-grafana latest 3724ab87f0b1 2 months ago 284MB Run the Influxdb and Grafana Images ----------------------------------- @@ -653,7 +652,7 @@ Run the InfluxDB docker image .. code:: bash $ sudo docker run -tid -v /var/lib/influxdb:/var/lib/influxdb --net=host\ - --name bar-influxdb opnfv/barometer-influxdb + --name bar-influxdb anuket/barometer-influxdb Check your docker image is running @@ -714,7 +713,7 @@ changing output location is required: $ cd <BAROMETER_REPO_DIR> $ sudo docker run -ti --name bar-collectd --net=host -v \ `pwd`/src/collectd/collectd_sample_configs:/opt/collectd/etc/collectd.conf.d \ - -v /var/run:/var/run -v /tmp:/tmp --privileged opnfv/barometer-collectd + -v /var/run:/var/run -v /tmp:/tmp --privileged anuket/barometer-collectd Now collectd container will be sending data to InfluxDB container located on remote Host pointed by IP configured in step 3. @@ -729,7 +728,7 @@ Connecting to an influxdb instance running on local system and adding own custom $ cd <BAROMETER_REPO_DIR> $ sudo docker run -tid -v /var/lib/grafana:/var/lib/grafana \ -v ${PWD}/docker/barometer-grafana/dashboards:/opt/grafana/dashboards \ - --name bar-grafana --net=host opnfv/barometer-grafana + --name bar-grafana --net=host anuket/barometer-grafana Connecting to an influxdb instance running on remote system with hostname of someserver and IP address of 192.168.121.111 @@ -738,7 +737,7 @@ of 192.168.121.111 $ sudo docker run -tid -v /var/lib/grafana:/var/lib/grafana --net=host -e \ influxdb_host=someserver --add-host someserver:192.168.121.111 --name \ - bar-grafana opnfv/barometer-grafana + bar-grafana anuket/barometer-grafana Check your docker image is running @@ -786,7 +785,7 @@ Download VES and Kafka docker images ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If you wish to use pre-built barometer project's VES and kafka images, you can pull the -images from https://hub.docker.com/r/opnfv/barometer-ves/ and https://hub.docker.com/r/opnfv/barometer-kafka/ +images from https://hub.docker.com/r/anuket/barometer-ves/ and https://hub.docker.com/r/anuket/barometer-kafka/ .. note:: If your preference is to build images locally please see sections `Build Kafka Docker Image`_ and @@ -794,8 +793,8 @@ images from https://hub.docker.com/r/opnfv/barometer-ves/ and https://hub.docke .. code:: bash - $ docker pull opnfv/barometer-kafka - $ docker pull opnfv/barometer-ves + $ docker pull anuket/barometer-kafka + $ docker pull anuket/barometer-ves .. note:: If you have pulled the pre-built images there is no requirement to complete steps outlined @@ -810,7 +809,7 @@ Build Kafka docker image: .. code:: bash $ cd barometer/docker/barometer-kafka - $ sudo docker build -t opnfv/barometer-kafka --build-arg http_proxy=`echo $http_proxy` \ + $ sudo docker build -t anuket/barometer-kafka --build-arg http_proxy=`echo $http_proxy` \ --build-arg https_proxy=`echo $https_proxy` -f Dockerfile . .. note:: @@ -828,7 +827,7 @@ Output should contain a barometer image: .. code:: REPOSITORY TAG IMAGE ID CREATED SIZE - opnfv/barometer-kafka latest 05f2a3edd96b 3 hours ago 1.2GB + anuket/barometer-kafka latest 75a0860b8d6e 2 months ago 902MB Build VES docker image ^^^^^^^^^^^^^^^^^^^^^^ @@ -838,7 +837,7 @@ Build VES application docker image: .. code:: bash $ cd barometer/docker/barometer-ves - $ sudo docker build -t opnfv/barometer-ves --build-arg http_proxy=`echo $http_proxy` \ + $ sudo docker build -t anuket/barometer-ves --build-arg http_proxy=`echo $http_proxy` \ --build-arg https_proxy=`echo $https_proxy` -f Dockerfile . .. note:: @@ -856,7 +855,7 @@ Output should contain a barometer image: .. code:: REPOSITORY TAG IMAGE ID CREATED SIZE - opnfv/barometer-ves latest 05f2a3edd96b 3 hours ago 1.2GB + anuket/barometer-ves latest 36a4a953e1b4 2 months ago 723MB Run Kafka docker image ^^^^^^^^^^^^^^^^^^^^^^ @@ -881,7 +880,7 @@ Run kafka docker image which connects with a zookeeper instance running on same .. code:: bash - $ sudo docker run -tid --net=host -p 9092:9092 opnfv/barometer-kafka + $ sudo docker run -tid --net=host -p 9092:9092 anuket/barometer-kafka Run kafka docker image which connects with a zookeeper instance running on a node with IP address of @@ -890,7 +889,7 @@ Run kafka docker image which connects with a zookeeper instance running on a nod .. code:: bash $ sudo docker run -tid --net=host -p 9092:9092 --env broker_id=1 --env zookeeper_node=zookeeper --add-host \ - zookeeper:192.168.121.111 opnfv/barometer-kafka + zookeeper:192.168.121.111 anuket/barometer-kafka Run VES Application docker image ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -907,13 +906,13 @@ Run VES docker image with default configuration .. code:: bash - $ sudo docker run -tid --net=host opnfv/barometer-ves + $ sudo docker run -tid --net=host anuket/barometer-ves Run VES docker image with guest.yaml files from barometer/3rd_party/collectd-ves-app/ves_app/yaml/ .. code:: bash - $ sudo docker run -tid --net=host opnfv/barometer-ves guest.yaml + $ sudo docker run -tid --net=host anuket/barometer-ves guest.yaml Run VES docker image with using custom config and yaml files. In example below yaml/ folder cotains @@ -922,7 +921,7 @@ file named custom.yaml .. code:: bash $ sudo docker run -tid --net=host -v ${PWD}/custom.config:/opt/ves/config/ves_app_config.conf \ - -v ${PWD}/yaml/:/opt/ves/yaml/ opnfv/barometer-ves custom.yaml + -v ${PWD}/yaml/:/opt/ves/yaml/ anuket/barometer-ves custom.yaml Run VES Test Collector application ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/release/userguide/installguide.oneclick.rst b/docs/release/userguide/installguide.oneclick.rst index d236b5b1..78203a12 100644 --- a/docs/release/userguide/installguide.oneclick.rst +++ b/docs/release/userguide/installguide.oneclick.rst @@ -231,6 +231,36 @@ Verify that key is added and password is not required to connect. example. For multinode installation keys need to be copied for each node: [collectd_hostname], [influxdb_hostname] etc. +Build the Collectd containers +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This is an optional step, if you do not wish to build the containers locally, please continue to `Download and run Collectd+Influxdb+Grafana containers`_. +This step will build the container images locally, allowing for testing of new changes to collectd. +This is particularly useful for the ``experimental`` flavour for testing PRs, and for building a ``collectd-6`` container. + +To run the playbook and build the containers, run:: + sudo ansible-playbook docker/ansible/collectd_build.yml + +By default, all contaienrs will be built. +Since this can take a while, it is recommended that you choose a flavor to build using tags:: + + sudo ansible-playbook docker/ansible/collectd_build.yml --tags='collectd-6,latest' + +The available tags are: + +* *stable* builds the ``barometer-collectd`` image +* *latest* builds the ``barometer-collectd-latest`` image +* *experimental* builds the ``barometer-collectd-experimental`` container, with optional PRs +* *collectd-6* builds the ``baromter-collectd-6`` container, with optional PR(s) + +* *flask_test* builds a small webapp that displays the metrics sent via the write_http plugin + +.. note:: + The flask_test tag must be explicitly enabled. + This can be done either through the ``--tags='flask_test'`` (to build just + this container) or with ``--tags=all`` to build this and all the other + containers as well. + Download and run Collectd+Influxdb+Grafana containers ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -247,10 +277,10 @@ Check the three containers are running, the output of ``docker ps`` should be si .. code:: bash $ sudo docker ps - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - a033aeea180d opnfv/barometer-grafana "/run.sh" 9 days ago Up 7 minutes bar-grafana - 1bca2e4562ab opnfv/barometer-influxdb "/entrypoint.sh in..." 9 days ago Up 7 minutes bar-influxdb - daeeb68ad1d5 opnfv/barometer-collectd "/run_collectd.sh ..." 9 days ago Up 7 minutes bar-collectd + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + 4c2143fb6bbd anuket/barometer-grafana "/run.sh" 59 minutes ago Up 4 minutes bar-grafana + 5e356cb1cb04 anuket/barometer-influxdb "/entrypoint.sh infl…" 59 minutes ago Up 4 minutes bar-influxdb + 2ddac8db21e2 anuket/barometer-collectd "/run_collectd.sh" About an hour ago Up 4 minutes bar-collectd To make some changes when a container is running run: @@ -284,10 +314,10 @@ Check the containers are running, the output of ``docker ps`` should be similar $ sudo docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 29035be2dab5 zookeeper:3.4.11 "/docker-entrypoint._" 7 minutes ago Up 7 minutes bar-zookeeper - eb8bba3c0b76 opnfv/barometer-ves "./start_ves_app.s..." 6 minutes ago Up 6 minutes bar-ves - 86702a96a68c opnfv/barometer-kafka "/src/start_kafka.sh" 6 minutes ago Up 6 minutes bar-kafka - daeeb68ad1d5 opnfv/barometer-collectd "/run_collectd.sh ..." 6 minutes ago Up 6 minutes bar-collectd + d041d8fff849 zookeeper:3.4.11 "/docker-entrypoint.…" 2 minutes ago Up 2 minutes bar-zookeeper + da67b81274bc anuket/barometer-ves "./start_ves_app.sh …" 2 minutes ago Up 2 minutes bar-ves + 2c25e0c79f93 anuket/barometer-kafka "/src/start_kafka.sh" 2 minutes ago Up 2 minutes bar-kafka + b161260c90ed anuket/barometer-collectd "/run_collectd.sh" 2 minutes ago Up 2 minutes bar-collectd To make some changes when a container is running run: @@ -319,8 +349,9 @@ the following plugins: ``ethstat``, ``ipc``, ``irq``, ``load``, ``memory``, ``numa``, ``processes``, ``swap``, ``turbostat``, ``uuid``, ``uptime``, ``exec``, ``hugepages``, ``intel_pmu``, ``ipmi``, ``write_kafka``, ``logfile``, - ``mcelog``, ``network``, ``intel_rdt``, ``rrdtool``, ``snmp_agent``, - ``syslog``, ``virt``, ``ovs_stats``, ``ovs_events``, ``dpdk_telemetry`` + ``logparser``, ``mcelog``, ``network``, ``intel_rdt``, ``rrdtool``, + ``snmp_agent``, ``syslog``, ``virt``, ``ovs_stats``, ``ovs_events``, + ``dpdk_telemetry``. .. note:: Some of the plugins are loaded depending on specific system requirements and can be omitted if @@ -330,15 +361,6 @@ the following plugins: For instructions on how to disable certain plugins see the `List and description of tags used in ansible scripts`_ section. -.. note:: - The ``dpdkstat`` and ``dpdkevents`` plugins are disabled by default (in - favour of the ``dpdk_telemetry`` plugin) and need to be explicitly enabled - in order to use them: - - .. code:: bash - - $ sudo ansible-playbook -i default.inv collectd_service.yml --tags "all,dpdkstats,dpdkevents" - List and description of tags used in ansible scripts ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -382,7 +404,7 @@ List of available tags: ``contextswitch``, ``cpu``, ``cpufreq``, ``df``, ``disk,`` ``ethstat``, ``ipc``, ``irq``, ``load``, ``memory``, ``numa``, ``processes``, ``swap``, ``turbostat``, ``uptime``, ``exec``, ``hugepages``, ``ipmi``, ``kafka``, - ``logfile``, ``mcelog``, ``network``, ``pmu``, ``rdt``, ``rrdtool``, - ``snmp``, ``syslog``, ``unixsock``, ``virt``, ``ovs_stats``, ``ovs_events``, - ``uuid``, ``dpdkevents``, ``dpdkstat``, ``dpdk_telemetry``. + ``logfile``, ``logparser``, ``mcelog``, ``network``, ``pmu``, ``rdt``, + ``rrdtool``, ``snmp``, ``syslog``, ``unixsock``, ``virt``, ``ovs_stats``, + ``ovs_events``, ``uuid``, ``dpdk_telemetry``. diff --git a/docs/testing/index.rst b/docs/testing/index.rst index 392b39f4..f763ca64 100644 --- a/docs/testing/index.rst +++ b/docs/testing/index.rst @@ -1 +1,79 @@ -.. To be decided +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. (c) Anuket and others + +============================== +Anuket Barometer testing guide +============================== + +This document will describe how to use different tests in this repo. + +There are a number of tools and scripts in Barometer that can be used for testing, whether that is during development, building, code reviews, or run regularly in CI. +Some of the tests are automated, and cover building collectd, others cover particular plugins. + +.. TODO: This guide should also include how to manually verify that collectd plugins are working as expected. + +.. TODO: There might be some troubleshooting guide in here too. + +Porting collectd to version 6 +============================= + +Thre is an ansible playbook for building and running collectd 5 and 6 together to compare the collected metrics. +This is intended to help test porting from collectd 5 to 6, and confirm equivalency across the versions. + +The playbook will:: + + * build collectd-6, collectd-latest and flask app containers + * generate a set of collectd configs + * launch the collectd-6, collectd-latest with the generated configs + * run the flask app which has a http server that receives metrics from + collectd v5 and collectd v6 + * display the received metrics from both versions of collectd + Collectd v5 shows PUTVAL + Collectd v6 shows PUTMETRIC + +To run this comparison, use the following command:: + + $ cd docker/ansible/ + $ sudo ansible-playbook -i default.inv collectd6_test.yml + +The playbook takes the following parameters: + + * PR (optional) + The PRID for an upstream collectd pull request that will be + passed to the collectd 6 container build + + * plugin (optional) + The name of the plugin that is bneing ported + This will filter the received metrics to show the value passed. + +To run the playbook with these configs, pass the extra var to ansible:: + + sudo ansible-playbook -i default.inv -e PR=<PR_ID> -e plugin=<plugin_name> collectd6_test.yml + +The metrics can then be viewed by inspecting the container logs or attaching to the container to view the output:: + + $ docker attach <webserver-container> + $ #OR + $ docker logs <webserver-container> + +Metrics from collectd 5 will appear preceeded with ``PUTVAL``, and metrics from collectd 6 will appear preceeded by ``PUTMETRIC``. + +:: + + PUTVAL fbae30cc-2f20-11b2-a85c-819293100691/hugepages-mm-2048Kb/vmpage_number-free interval=10.000 1629466502.664:0 + PUTVAL fbae30cc-2f20-11b2-a85c-819293100691/hugepages-mm-2048Kb/vmpage_number-used interval=10.000 1629466502.664:0 + PUTVAL fbae30cc-2f20-11b2-a85c-819293100691/hugepages-mm-1048576Kb/vmpage_number-free interval=10.000 1629466502.664:0 + PUTVAL fbae30cc-2f20-11b2-a85c-819293100691/hugepages-mm-1048576Kb/vmpage_number-used interval=10.000 1629466502.664:0 + PUTVAL fbae30cc-2f20-11b2-a85c-819293100691/hugepages-node0-2048Kb/vmpage_number-free interval=10.000 1629466502.664:0 + PUTVAL fbae30cc-2f20-11b2-a85c-819293100691/hugepages-node0-2048Kb/vmpage_number-used interval=10.000 1629466502.664:0 + PUTVAL fbae30cc-2f20-11b2-a85c-819293100691/hugepages-node0-1048576Kb/vmpage_number-used interval=10.000 1629466502.665:0 + PUTVAL fbae30cc-2f20-11b2-a85c-819293100691/hugepages-node0-1048576Kb/vmpage_number-free interval=10.000 1629466502.665:0 + PUTMETRIC collectd_hugepages_vmpage_number type=GAUGE time=1629466501.807 interval=10.000 label:hugepages="mm-2048Kb" label:instance="fbae30cc-2f20-11b2-a85c-819293100691" label:type="free" 0 + PUTMETRIC collectd_hugepages_vmpage_number type=GAUGE time=1629466501.807 interval=10.000 label:hugepages="mm-2048Kb" label:instance="fbae30cc-2f20-11b2-a85c-819293100691" label:type="used" 0 + PUTMETRIC collectd_hugepages_vmpage_number type=GAUGE time=1629466501.808 interval=10.000 label:hugepages="mm-1048576Kb" label:instance="fbae30cc-2f20-11b2-a85c-819293100691" label:type="free" 0 + PUTMETRIC collectd_hugepages_vmpage_number type=GAUGE time=1629466501.808 interval=10.000 label:hugepages="node0-2048Kb" label:instance="fbae30cc-2f20-11b2-a85c-819293100691" label:type="free" 0 + PUTMETRIC collectd_hugepages_vmpage_number type=GAUGE time=1629466501.808 interval=10.000 label:hugepages="node0-2048Kb" label:instance="fbae30cc-2f20-11b2-a85c-819293100691" label:type="used" 0 + PUTMETRIC collectd_hugepages_vmpage_number type=GAUGE time=1629466501.809 interval=10.000 label:hugepages="node0-1048576Kb" label:instance="fbae30cc-2f20-11b2-a85c-819293100691" label:type="free" 0 + PUTMETRIC collectd_hugepages_vmpage_number type=GAUGE time=1629466501.809 interval=10.000 label:hugepages="node0-1048576Kb" label:instance="fbae30cc-2f20-11b2-a85c-819293100691" label:type="used" 0 + PUTMETRIC collectd_hugepages_vmpage_number type=GAUGE time=1629466501.808 interval=10.000 label:hugepages="mm-1048576Kb" label:instance="fbae30cc-2f20-11b2-a85c-819293100691" label:type="used" 0 |