[plugins] Update a few common plugins for new help output

Updates four common plugins to provide several examples of how to format
plugin documentation so that the new `help` component is able to provide
useful information on them.

Going forward, new plugins should include docstrings to provide this
help information as part of the initial review process. Existing plugins
will be updated as time allows or as plugins are updated and/or
refactored.

Signed-off-by: Jake Hunsaker <jhunsake@redhat.com>

4 files changed, 67 insertions, 2 deletions

diff --git a/sos/report/plugins/apache.py b/sos/report/plugins/apache.py
index f77117a1..fd3d4e7a 100644
--- a/sos/report/plugins/apache.py
+++ b/sos/report/plugins/apache.py
@@ -11,6 +11,19 @@ from sos.report.plugins import (Plugin, RedHatPlugin, DebianPlugin,
 
 
 class Apache(Plugin):
+    """The Apache plugin covers the upstream Apache webserver project,
+    regardless of the packaged name; apache2 for Debian and Ubuntu, or httpd
+    for Red Hat family distributions.
+
+    The aim of this plugin is for Apache-specific information, not necessarily
+    other projects that happen to place logs or similar files within the
+    standardized apache directories. For example, OpenStack components that log
+    to apache logging directories are excluded from this plugin and collected
+    via their respective OpenStack plugins.
+
+    Users can expect the collection of apachectl command output, apache server
+    logs, and apache configuration files from this plugin.
+    """
 
     short_desc = 'Apache http daemon'
     plugin_name = "apache"
@@ -49,6 +62,15 @@ class Apache(Plugin):
 
 
 class RedHatApache(Apache, RedHatPlugin):
+    """
+    On Red Hat distributions, the Apache plugin will also attempt to collect
+    JBoss Web Server logs and configuration files.
+
+    Note that for Red Hat distributions, this plugin explicitly collects for
+    'httpd' installations. If you have installed apache from source or via any
+    method that uses the name 'apache' instead of 'httpd', these collections
+    will fail.
+    """
     files = (
         '/etc/httpd/conf/httpd.conf',
         '/etc/httpd22/conf/httpd.conf',
diff --git a/sos/report/plugins/filesys.py b/sos/report/plugins/filesys.py
index 01495603..bd85ed6f 100644
--- a/sos/report/plugins/filesys.py
+++ b/sos/report/plugins/filesys.py
@@ -11,6 +11,15 @@ from sos.report.plugins import (Plugin, RedHatPlugin, DebianPlugin,
 
 
 class Filesys(Plugin, DebianPlugin, UbuntuPlugin, CosPlugin):
+    """Collects general information about the local filesystem(s) and mount
+    points as well as optional information about EXT filesystems. Note that
+    information specific filesystems such as XFS or ZFS is not collected by
+    this plugin, as there are specific plugins for those filesystem types.
+
+    This plugin will collect /etc/fstab as well as mount information within
+    /proc/, and is responsible for the 'mount' and 'df' symlinks that appear
+    in an sos archive's root.
+    """
 
     short_desc = 'Local file systems'
 
diff --git a/sos/report/plugins/kernel.py b/sos/report/plugins/kernel.py
index 803f5e30..0578d0d2 100644
--- a/sos/report/plugins/kernel.py
+++ b/sos/report/plugins/kernel.py
@@ -11,6 +11,20 @@ import glob
 
 
 class Kernel(Plugin, IndependentPlugin):
+    """The Kernel plugin is aimed at collecting general information about
+    the locally running kernel. This information should be distribution-neutral
+    using commands and filesystem collections that are ubiquitous across
+    distributions.
+
+    Debugging information from /sys/kernel/debug is collected by default,
+    however care is taken so that these collections avoid areas like
+    /sys/kernel/debug/tracing/trace_pipe which would otherwise cause the
+    sos collection attempt to appear to 'hang'.
+
+    The 'trace' option will enable the collection of the
+    /sys/kernel/debug/tracing/trace file specfically, but will not change the
+    behavior stated above otherwise.
+    """
 
     short_desc = 'Linux kernel'
 
diff --git a/sos/report/plugins/podman.py b/sos/report/plugins/podman.py
index ffc63834..016ddccf 100644
--- a/sos/report/plugins/podman.py
+++ b/sos/report/plugins/podman.py
@@ -12,6 +12,16 @@ from sos.report.plugins import Plugin, RedHatPlugin, UbuntuPlugin, PluginOpt
 
 
 class Podman(Plugin, RedHatPlugin, UbuntuPlugin):
+    """Podman is a daemonless container management engine, and this plugin is
+    meant to provide diagnostic information for both the engine and the
+    containers that podman is managing.
+
+    General status information will be collected from podman commands, while
+    detailed inspections of certain components will provide more insight
+    into specific container problems. This detailed inspection is provided for
+    containers, images, networks, and volumes. Per-entity inspections will be
+    recorded in subdirs within sos_commands/podman/ for each of those types.
+    """
 
     short_desc = 'Podman containers'
     plugin_name = 'podman'
@@ -20,9 +30,19 @@ class Podman(Plugin, RedHatPlugin, UbuntuPlugin):
 
     option_list = [
         PluginOpt('all', default=False,
-                  desc='collect for all containers, even terminated ones'),
+                  desc='collect for all containers, even terminated ones',
+                  long_desc=(
+                    'Enable collection for all containers that exist on the '
+                    'system regardless of their running state. This may cause '
+                    'a significant increase in sos archive size, especially '
+                    'when combined with the \'logs\' option.')),
         PluginOpt('logs', default=False,
-                  desc='collect stdout/stderr logs for containers'),
+                  desc='collect stdout/stderr logs for containers',
+                  long_desc=(
+                    'Capture \'podman logs\' output for discovered containers.'
+                    ' This may be useful or not depending on how/if the '
+                    'container produces stdout/stderr output. Use cautiously '
+                    'when also using the \'all\' option.')),
         PluginOpt('size', default=False,
                   desc='collect image sizes for podman ps')
     ]