Merge pull request #170 from MartyEwings/SUP-2736

(SUP-2736) Documentation

Author: elainemccloskey

REFERENCE.md

@@ -2,17 +2,13 @@
 #
 # Queries PuppetDB for hosts with the specified Puppet Enterprise profile.
 # Used by this module to query Puppet Enterprise API endpoints.
-
 # Parameters:
 #
-# $profile: the short name of the Puppet Enterprise profile.
-
+# @param profile 
+#   the short name of the Puppet Enterprise profile.
 # Results:
 #
-# $hosts: an array of certnames.
-#
-# Returns ['127.0.0.1'] when PuppetDB returns no hosts.
-
+# @return $hosts: an array of certnames. or ['127.0.0.1'] when PuppetDB returns no hosts.
 function puppet_metrics_collector::hosts_with_pe_profile($profile) {
   # storeconfigs is used here to determine if PuppetDB is available to query.
   # See: https://github.com/puppetlabs/puppet-enterprise-modules/blob/main/docs/pe-modules-next-discussion-outline.txt

functions/hosts_with_pe_profile.pp

@@ -1,3 +1,8 @@
+# Function: version_based_excludes
+#
+# Description: Generates a list of services to exlude based on version of PE
+# @param metrics_type the service currently compiling metrics for
+# @return excludes the list of services to exclude
 function puppet_metrics_collector::version_based_excludes(
   String[1] $metrics_type,
 ) >> Array[String] {

functions/version_based_excludes.pp

@@ -1,13 +1,17 @@
 require 'yaml'
-
+# Function: to_yaml
+#
+# Description: Converts the content of the passed array or hash to YAML
 Puppet::Functions.create_function(:'puppet_metrics_collector::to_yaml') do
+  # @return [String] YAML representation of the passed array or hash
   dispatch :to_yaml do
     param 'Hash', :hash_or_array
   end
+  # @return [String] YAML representation of the passed array or hash
   dispatch :to_yaml do
     param 'Array', :hash_or_array
   end
-
+  # @return [String] YAML representation of the passed array or hash
   def to_yaml(hash_or_array)
     hash_or_array.to_yaml
   end

lib/puppet/functions/puppet_metrics_collector/to_yaml.rb

@@ -71,6 +71,33 @@
 # @param override_metrics_command
 # Optional String: Allows you to define the command that is executed to gather metrics. Default: undef
 # 
+# @param activemq_metrics_ensure
+# Optional String: Collection of ActiveMQ metrics has been removed, but the parameters are left to avoid breaking upgrades
+# @param activemq_hosts
+# Optional String: Collection of ActiveMQ metrics has been removed, but the parameters are left to avoid breaking upgrades
+# @param activemq_port
+# Optional Integer: Collection of ActiveMQ metrics has been removed, but the parameters are left to avoid breaking upgrades
+# @param puppetserver_excludes
+#   An Array of metrics to exclude from the puppetserver metrics collection.
+# @param puppetdb_excludes
+#   An Array of metrics to exclude from the puppetdb metrics collection.
+# @param orchestrator_excludes
+#   An Array of metrics to exclude from the orchestrator_excludes metrics collection.
+# @param ace_excludes
+#   An Array of metrics to exclude from the ace_excludes metrics collection.
+# @param bolt_excludes
+#   An Array of metrics to exclude from the bolt_excludes metrics collection.
+# @param activemq_excludes
+#   Collection of ActiveMQ metrics has been removed, but the parameters are left to avoid breaking upgrades
+# @param metrics_server_hostname
+#   The hostname of the metrics server to send data to. Default: undef
+# @param metrics_server_port
+#   The port number of the metrics server to send data to. Default: undef
+# @param metrics_server_db_name
+#   The database name on the metrics server to send data to.
+#   Required for metrics_server_type of influxdb. Default: undef
+# @param override_metrics_command
+#   Allows you to define the command that is executed to gather metrics. Default: undef
 class puppet_metrics_collector (
   String                  $puppetserver_metrics_ensure = 'present',
   String                  $output_dir                  = '/opt/puppetlabs/puppet-metrics-collector',

manifests/init.pp

@@ -1,4 +1,4 @@
-# Collect Puma or TrapperKeeper Metrics
+# @summary A defined type to manage the configuration of tbe different metrics collection targets
 define puppet_metrics_collector::pe_metric (
   String                    $metrics_type             = $title,
   Enum['absent', 'present'] $metric_ensure            = 'present',

manifests/pe_metric.pp

@@ -1,4 +1,3 @@
-# 
 # @summary
 #   This class manages the collections of SAR metrics
 #   
@@ -13,7 +12,18 @@
 # 
 # @param cron_minute
 #   The minute to run the cron job. Default: '0/5'
+# @param metrics_type 
+#   The string aide to identify the metrics type,
+#   this is used to create the metrics file name.
+#
+# @param metric_ensure
+#   The ensure value for the metrics file. Default: 'present'
+#
+# @param metric_script_file 
+#   The script file to run to collect the metrics. Default: 'system_metrics'
 #
+# @param metrics_shipping_command
+#   The parameter that defines the command for the remote shipping of metrics. Default: '$puppet_metrics_collector::system::metrics_shipping_command'
 define puppet_metrics_collector::sar_metric (
   String                    $metrics_type              = $title,
   Enum['absent', 'present'] $metric_ensure             = 'present',

manifests/sar_metric.pp

@@ -8,6 +8,7 @@
 #
 # @api private
 # 
+# 
 class puppet_metrics_collector::system::postgres (
   String  $metrics_ensure            = $puppet_metrics_collector::system::system_metrics_ensure,
   Integer $collection_frequency      = $puppet_metrics_collector::system::collection_frequency,