aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/release/release-notes/notes/ansible-build-containers-b4a4cc9cb70f83b3.yaml11
-rw-r--r--docs/release/release-notes/notes/collectd-5-v-6-testing-cc821b32bad2794c.yaml10
-rw-r--r--docs/release/release-notes/notes/collectd-6-testing-flask-app-2bb0ca1326775dd8.yaml3
-rw-r--r--docs/release/userguide/installguide.oneclick.rst30
-rw-r--r--docs/testing/index.rst80
5 files changed, 133 insertions, 1 deletions
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/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/userguide/installguide.oneclick.rst b/docs/release/userguide/installguide.oneclick.rst
index ef3624cb..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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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