aboutsummaryrefslogtreecommitdiffstats
path: root/docs/release/userguide
diff options
context:
space:
mode:
authorEmma Foley <efoley@redhat.com>2021-08-30 10:40:53 +0000
committerGerrit Code Review <gerrit@opnfv.org>2021-08-30 10:40:53 +0000
commit8a212d2bf9cdc0ceb24ee30d319a51b4c5d4f827 (patch)
tree92dac6d42a67f4a3c84e8d8983d26a688fa5a3ed /docs/release/userguide
parent720f19cbcb2c03140d1359c11c78b6a1c34cb4d0 (diff)
parent18e27d1c59cf34373b8079e066a296a5922a5b04 (diff)
Merge changes from topic "update_docs"
* changes: [docs] Update config and post-installation guides [docs][userguide] Use literalinclude instead of duplicating the sample configs
Diffstat (limited to 'docs/release/userguide')
-rw-r--r--docs/release/userguide/feature.userguide.rst191
-rw-r--r--docs/release/userguide/installguide.docker.rst8
2 files changed, 55 insertions, 144 deletions
diff --git a/docs/release/userguide/feature.userguide.rst b/docs/release/userguide/feature.userguide.rst
index c76e79a5..02f8bdaa 100644
--- a/docs/release/userguide/feature.userguide.rst
+++ b/docs/release/userguide/feature.userguide.rst
@@ -1,3 +1,5 @@
+.. _feature-userguide:
+
.. This work is licensed under a Creative Commons Attribution 4.0 International License.
.. http://creativecommons.org/licenses/by/4.0
.. (c) Anuket and others
@@ -212,48 +214,18 @@ Example of specifying custom paths to DPDK headers and 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:
-
-.. code:: bash
-
- LoadPlugin dpdkstat
- <Plugin dpdkstat>
- Coremask "0xf"
- ProcessType "secondary"
- FilePrefix "rte"
- EnabledPortMask 0xffff
- PortName "interface1"
- PortName "interface2"
- </Plugin>
+include (uncomment lines as appropriate):
+.. literalinclude:: ../../../src/collectd/collectd_sample_configs/dpdkstat.conf
+ :start-at: LoadPlugin
+ :language: bash
To configure the dpdkevents plugin you need to modify the configuration file to
-include:
+include (uncomment lines as appropriate):
-.. code:: bash
-
- <LoadPlugin dpdkevents>
- Interval 1
- </LoadPlugin>
-
- <Plugin "dpdkevents">
- <EAL>
- Coremask "0x1"
- MemoryChannels "4"
- FilePrefix "rte"
- </EAL>
- <Event "link_status">
- SendEventsOnUpdate false
- EnabledPortMask 0xffff
- SendNotification true
- </Event>
- <Event "keep_alive">
- SendEventsOnUpdate false
- LCoreMask "0xf"
- KeepAliveShmName "/dpdk_keepalive_shm_name"
- SendNotification true
- </Event>
- </Plugin>
+.. literalinclude:: ../../../src/collectd/collectd_sample_configs/dpdkevents.conf
+ :start-at: LoadPlugin
+ :language: bash
.. note:: Currently, the DPDK library doesn’t support API to de-initialize
the DPDK resources allocated on the initialization. It means, the collectd
@@ -352,16 +324,9 @@ configuration file (``collectd.conf``) can be found at ``/opt/collectd/etc``.
To configure the hugepages plugin you need to modify the configuration file to
include:
-.. code:: bash
-
- LoadPlugin hugepages
- <Plugin hugepages>
- ReportPerNodeHP true
- ReportRootHP true
- ValuesPages true
- ValuesBytes false
- ValuesPercentage false
- </Plugin>
+.. literalinclude:: ../../../src/collectd/collectd_sample_configs/hugepages.conf
+ :start-at: LoadPlugin
+ :language: bash
For more information on the plugin parameters, please see:
https://github.com/collectd/collectd/blob/main/src/collectd.conf.pod
@@ -421,31 +386,12 @@ configuration file (``collectd.conf``) can be found at ``/opt/collectd/etc``.
To configure the PMU plugin you need to modify the configuration file to
include:
-.. code:: bash
-
- <LoadPlugin intel_pmu>
- Interval 1
- </LoadPlugin>
- <Plugin "intel_pmu">
- ReportHardwareCacheEvents true
- ReportKernelPMUEvents true
- ReportSoftwareEvents true
- Cores ""
- </Plugin>
-
-If you want to monitor Intel CPU specific CPU events, make sure to enable the
-additional two options shown below:
+.. literalinclude:: ../../../src/collectd/collectd_sample_configs/intel_pmu.conf
+ :start-at: LoadPlugin
+ :language: bash
-.. code:: bash
-
- <Plugin intel_pmu>
- ReportHardwareCacheEvents true
- ReportKernelPMUEvents true
- ReportSoftwareEvents true
- EventList "$HOME/.cache/pmu-events/GenuineIntel-6-2D-core.json"
- HardwareEvents "L2_RQSTS.CODE_RD_HIT,L2_RQSTS.CODE_RD_MISS" "L2_RQSTS.ALL_CODE_RD"
- Cores ""
- </Plugin>
+If you want to monitor Intel CPU specific CPU events, make sure to uncomment the
+``EventList`` and ``HardwareEvents`` options above.
.. note::
If you set XDG_CACHE_HOME to anything other than the variable above - you will need to modify
@@ -513,14 +459,9 @@ configuration file (``collectd.conf``) can be found at ``/opt/collectd/etc``.
To configure the RDT plugin you need to modify the configuration file to
include:
-.. code:: bash
-
- <LoadPlugin intel_rdt>
- Interval 1
- </LoadPlugin>
- <Plugin "intel_rdt">
- Cores ""
- </Plugin>
+.. literalinclude:: ../../../src/collectd/collectd_sample_configs/rdt.conf
+ :start-at: LoadPlugin
+ :language: bash
For more information on the plugin parameters, please see:
https://github.com/collectd/collectd/blob/main/src/collectd.conf.pod
@@ -726,18 +667,9 @@ configuration file (``collectd.conf``) can be found at ``/opt/collectd/etc``.
To configure the mcelog plugin you need to modify the configuration file to
include:
-.. code:: bash
-
- <LoadPlugin mcelog>
- Interval 1
- </LoadPlugin>
- <Plugin mcelog>
- <Memory>
- McelogClientSocket "/var/run/mcelog-client"
- PersistentNotification false
- </Memory>
- #McelogLogfile "/var/log/mcelog"
- </Plugin>
+.. literalinclude:: ../../../src/collectd/collectd_sample_configs/mcelog.conf
+ :start-at: LoadPlugin
+ :language: bash
For more information on the plugin parameters, please see:
https://github.com/collectd/collectd/blob/main/src/collectd.conf.pod
@@ -881,35 +813,19 @@ Clone and install the collectd ovs plugin:
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 OVS events plugin you need to modify the configuration file to include:
+To configure the OVS events plugin you need to modify the configuration file
+(uncommenting and updating values as appropriate) to include:
-.. code:: bash
-
- <LoadPlugin ovs_events>
- Interval 1
- </LoadPlugin>
- <Plugin ovs_events>
- Port "6640"
- Address "127.0.0.1"
- Socket "/var/run/openvswitch/db.sock"
- Interfaces "br0" "veth0"
- SendNotification true
- </Plugin>
+.. literalinclude:: ../../../src/collectd/collectd_sample_configs/ovs_events.conf
+ :start-at: LoadPlugin
+ :language: bash
To configure the OVS stats plugin you need to modify the configuration file
-to include:
+(uncommenting and updating values as appropriate) to include:
-.. code:: bash
-
- <LoadPlugin ovs_stats>
- Interval 1
- </LoadPlugin>
- <Plugin ovs_stats>
- Port "6640"
- Address "127.0.0.1"
- Socket "/var/run/openvswitch/db.sock"
- Bridges "br0"
- </Plugin>
+.. literalinclude:: ../../../src/collectd/collectd_sample_configs/ovs_stats.conf
+ :start-at: LoadPlugin
+ :language: bash
For more information on the plugin parameters, please see:
https://github.com/collectd/collectd/blob/main/src/collectd.conf.pod
@@ -942,12 +858,11 @@ to include:
.. note:: Exec plugin configuration has to be changed to use appropriate user before starting collectd service.
-ovs_pmd_stat.sh calls the script for OVS PMD stats application with its argument:
-
-.. code:: bash
+``ovs_pmd_stat.sh`` calls the script for OVS PMD stats application with its argument:
- sudo python /usr/local/src/ovs_pmd_stats.py" "--socket-pid-file"
- "/var/run/openvswitch/ovs-vswitchd.pid"
+.. literalinclude:: ../../../src/collectd/collectd_sample_configs/ovs_pmd_stats.sh
+ :start-at: python
+ :language: bash
SNMP Agent Plugin
^^^^^^^^^^^^^^^^^
@@ -1275,29 +1190,23 @@ Additional useful plugins
**Exec Plugin** : Can be used to show you when notifications are being
generated by calling a bash script that dumps notifications to file. (handy
-for debug). Modify /opt/collectd/etc/collectd.conf:
-
-.. code:: bash
+for debug). Modify ``/opt/collectd/etc/collectd.conf`` to include the
+``NotificationExec`` config option, taking care to add the right directory path
+to the ``write_notification.sh`` script:
- LoadPlugin exec
- <Plugin exec>
- # Exec "user:group" "/path/to/exec"
- NotificationExec "user" "<path to barometer>/barometer/src/collectd/collectd_sample_configs/write_notification.sh"
- </Plugin>
+.. literalinclude:: ../../../src/collectd/collectd_sample_configs/exec.conf
+ :start-at: LoadPlugin
+ :emphasize-lines: 6
+ :language: bash
-write_notification.sh (just writes the notification passed from exec through
-STDIN to a file (/tmp/notifications)):
-
-.. code:: bash
+``write_notification.sh`` writes the notification passed from exec through
+STDIN to a file (``/tmp/notifications``):
- #!/bin/bash
- rm -f /tmp/notifications
- while read x y
- do
- echo $x$y >> /tmp/notifications
- done
+.. literalinclude:: ../../../src/collectd/collectd_sample_configs/write_notification.sh
+ :start-at: rm -f
+ :language: bash
-output to /tmp/notifications should look like:
+output to ``/tmp/notifications`` should look like:
.. code:: bash
diff --git a/docs/release/userguide/installguide.docker.rst b/docs/release/userguide/installguide.docker.rst
index 20836af7..38d467a4 100644
--- a/docs/release/userguide/installguide.docker.rst
+++ b/docs/release/userguide/installguide.docker.rst
@@ -1,7 +1,7 @@
+.. _barometer-docker-userguide:
.. This work is licensed under a Creative Commons Attribution 4.0 International License.
.. http://creativecommons.org/licenses/by/4.0
.. (c) Anuket and others
-.. _barometer-docker-userguide:
=====================================
Anuket Barometer Docker Install Guide
@@ -31,7 +31,9 @@ For steps to build and run VES and Kafka images please see section `Build and Ru
For overview of running VES application with Kafka please see the :ref:`VES Application User Guide <barometer-ves-userguide>`
-For an alternative installation method using ansible, please see the :ref:`Barometer One Click Install Guide <barometer-oneclick-userguide>`.
+For an alternative installation method using ansible, please see the :ref:`Barometer One Click Install Guide <barometer-oneclick-userguide>`.
+
+For post-installation verification and troubleshooting, please see the :ref:`Barometer post installation guide <barometer-postinstall>`.
Barometer Docker Images Description
-----------------------------------
@@ -93,7 +95,7 @@ The Barometer project's VES application and Kafka docker images are based on a C
docker image has a dependancy on `Zookeeper <https://zookeeper.apache.org/>`_. Kafka must be able to
connect and register with an instance of Zookeeper that is either running on local or remote host.
Kafka recieves and stores metrics recieved from Collectd. VES application pulls latest metrics from Kafka
-which it normalizes into VES format for sending to a VES collector. Please see details in
+which it normalizes into VES format for sending to a VES collector. Please see details in
:ref:`VES Application User Guide <barometer-ves-userguide>`
Installing Docker