Update chapter on metric-utility

downstream/assemblies/platform/assembly-ag-controller-backup-and-restore.adoc

@@ -4,7 +4,7 @@
 
 You can backup and restore your system using the {PlatformNameShort} setup playbook. 
 
-For more information, see the xref:controller-backup-restore-clustered-environments[Backup and restore clustered environments] section.
+For more information, see the link:{URLControllerAdminGuide}/index#controller-backup-restore-clustered-environments[Backup and restore clustered environments] section.
 
 [NOTE]
 ====

downstream/assemblies/platform/assembly-metrics-utility.adoc

@@ -9,13 +9,13 @@ ifdef::context[:parent-context-of-metrics-utility: {context}]
 
 :context: metrics-utility
 
-= Subscription consumption
+= Usage reporting with metrics-utility 
 
 The {PlatformNameShort} metrics utility tool (`metrics-utility`) is a command-line utility that is installed on a system containing an instance of {ControllerName}. 
 
-When installed and configured, `metrics-utility` gathers billing-related metrics from your system and creates a consumption-based billing report. Metrics-utility is especially suited for users who have multiple managed hosts and want to use consumption-based billing. Once a report is generated, it is deposited in a target location that you specify in the configuration file. 
+When installed and configured, `metrics-utility` gathers billing-related metrics from your system and creates a consumption-based billing report. The `metrics-utility` tool is especially suited for users who have multiple managed hosts and want to use consumption-based billing. Once a report is generated, it is deposited in a target location that you specify in the configuration file. 
 
-Metrics-utility collects two types of data from your system: configuration data and reporting data. 
+`metrics-utility` collects two types of data from your system: configuration data and reporting data. 
 
 The configuration data includes the following information:
 
@@ -37,8 +37,22 @@ To ensure that `metrics-utility` continues to work as configured, clear your rep
 
 
 include::platform/proc-configuring-the-metrics-utility.adoc[leveloffset=+1]
+include::platform/proc-configure-a-config-map.adoc[leveloffset=+3]
+include::platform/proc-deploy-controller.adoc[leveloffset=+3]
 include::platform/ref-fetching-a-monthly-report.adoc[leveloffset=+1]
 include::platform/proc-modifying-the-run-schedule.adoc[leveloffset=+1]
+include::platform/ref-supported-storage.adoc[leveloffset=+1]
+include::platform/ref-report-types.adoc[leveloffset=+1]
+include::platform/ref-renewal-guidance.adoc[leveloffset=+1]
+include::platform/ref-storage-invocation.adoc[leveloffset=+2]
+include::platform/ref-show-ephemeral-use.adoc[leveloffset=+3]
+include::platform/ref-select-a-date-range.adoc[leveloffset=+3]
+include::platform/ref-ccsp.adoc[leveloffset=+2]
+
+
+
+-
+
 
 
 ifdef::parent-context[:context: {parent-context}]

downstream/modules/platform/proc-configure-a-config-map.adoc

@@ -0,0 +1,30 @@
+[id="proc-configure-a-config-map"]
+
+= Create a ConfigMap in the OpenShift UI YAML view 
+
+. From the navigation panel, select ConfigMaps, and then click the Create ConfigMap button.
+On the next screen, select the YAML view tab.
+In the YAML field, enter the following parameters with the appropriate variables set:
++
+----
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: automationcontroller-metrics-utility-configmap
+data:
+  METRICS_UTILITY_SHIP_TARGET: directory
+  METRICS_UTILITY_SHIP_PATH: /metrics-utility
+  METRICS_UTILITY_REPORT_TYPE: CCSP
+  METRICS_UTILITY_PRICE_PER_NODE: '11' # in USD
+  METRICS_UTILITY_REPORT_SKU: MCT3752MO
+  METRICS_UTILITY_REPORT_SKU_DESCRIPTION: "EX: Red Hat Ansible Automation Platform, Full Support (1 Managed Node, Dedicated, Monthly)"
+  METRICS_UTILITY_REPORT_H1_HEADING: "CCSP Reporting <Company>: ANSIBLE Consumption"
+  METRICS_UTILITY_REPORT_COMPANY_NAME: "Company Name"
+  METRICS_UTILITY_REPORT_EMAIL: "[email protected]"
+  METRICS_UTILITY_REPORT_RHN_LOGIN: "test_login"
+  METRICS_UTILITY_REPORT_COMPANY_BUSINESS_LEADER: "BUSINESS LEADER"
+  METRICS_UTILITY_REPORT_COMPANY_PROCUREMENT_LEADER: "PROCUREMENT LEADER"
+----
++
+. Click btn:[Create].
+. To verify that the ConfigMap was created and the `metric utility` is installed, select ConfigMap from the navigation panel and look for your ConfigMap in the list.

downstream/modules/platform/proc-deploy-controller.adoc

@@ -0,0 +1,26 @@
+[id="proc-deploy-controller"]
+
+= Deploy {ControllerName} 
+
+Deploy {ControllerName} and specify variables for how often `metrics-utility` gathers usage information and generates a report.
+
+. From the navigation panel, select *Installed Operators*.
+. Select {PlatformNameShort}.
+. In the Operator details, select the {ControllerName} tab.
+. Click btn:[Create automation controller].
+. Select the YAML view option. 
+The YAML now shows the default parameters for {ControllerName}. 
+The relevant parameters for `metrics-utility` are the following:
++
+[cols="50%,50%",options="header"]
+|====
+| *Parameter* | *Variable*
+| *`metrics_utility_enabled`* | True.
+| *`metrics_utility_cronjob_gather_schedule`* | @hourly or @daily.
+| *`metrics_utility_cronjob_report_schedule`* | @daily or @monthly.
+|====
++
+. Find the `metrics_utility_enabled` parameter and change the variable to true.
+. Find the `metrics_utility_cronjob_gather_schedule` parameter and enter a variable for how often the utility should gather usage information (for example, `@hourly` or `@daily`).
+. Find the `metrics_utility_cronjob_report_schedule` parameter and enter a variable for how often the utility generates a report (for example, `@daily` or `@monthly`).
+. Click btn:[Create].

downstream/modules/platform/proc-modifying-the-run-schedule.adoc

@@ -8,7 +8,8 @@
 
 You can configure `metrics-utility` to run at specified times and intervals. Run frequency is expressed in cronjobs. See link:https://www.redhat.com/sysadmin/linux-cron-command[How to schedule jobs using the Linux ‘Cron’ utility] for more information. 
 
-== On RHEL
+== On {RHEL}
+
 .Procedure
 
 . From the command line, run: 
@@ -23,13 +24,13 @@ crontab -e
 [source, ]
 ----
 */2 * * * *     metrics-utility gather_automation_controller_billing_data --ship --until=10m
-*/5 * * * *     metrics-utili
-ty build_report
+*/5 * * * *     metrics-utility build_report
 ----
 +
 . Save and close the file.
 
 == On {OCPShort} from the {PlatformNameShort} operator 
+
 .Procedure
 
 . From the navigation panel, select menu:Workloads[Deployments].
@@ -53,3 +54,4 @@ metrics_utility_cronjob_report_schedule:
 . To verify that you have changed the `metrics-utility` running schedule successfully, you can take one or both of the following steps:
 .. return to the `YAML` file and ensure that the parameters described above reflect the correct variables.  
 .. From the navigation menu, select menu:Workloads[Cronjobs] and ensure that your cronjobs show the updated schedule. 
+

downstream/modules/platform/ref-ccsp.adoc

@@ -0,0 +1,76 @@
+[id="ref-ccsp"]
+
+= CCSP
+
+`CCSP` is the original report format. It does not include many of the customization of CCSPv2, and it is intended to be used only for the CCSP partner program.
+
+== Optional collectors for `gather` command
+
+You can use the following optional collectors for the `gather` command:
+
+* *main_jobhostsummary`
+** If present by default, this incrementally collects the `main_jobhostsummary` table from the automation controller database, containing information about jobs runs and managed nodes automated.
+* `main_host`
+** This collects daily snapshots of the `main_host` table from the automation controller database and has managed nodes/hosts present across automation controller inventories,
+* `main_jobevent`
+** This incrementally collects the `main_jobevent` table from the automation controller database and contains information about which modules, roles, and ansible collections are being used.
+* main_indirectmanagednodeaudit
+** This incrementally collects the `main_indirectmanagednodeaudit` table from the automation controller database and contains information about indirectly managed nodes,
+
+----
+# Example with all optional collectors
+export METRICS_UTILITY_OPTIONAL_COLLECTORS="main_host,main_jobevent,main_indirectmanagednodeaudit"
+----
+
+== Optional sheets for `build_report` command
+
+You may use the following optional sheets for the `build_report` command:
+
+* `ccsp_summary`
+** This is a landing page specifically for partners under the CCSP program. It shows managed node usage by each automation controller organization.
+** This report takes additional parameters to customize the summary page. For more information, see the following example:
+
+----
+export METRICS_UTILITY_PRICE_PER_NODE=11.55 # in USD
+export METRICS_UTILITY_REPORT_SKU=MCT3752MO
+export METRICS_UTILITY_REPORT_SKU_DESCRIPTION="EX: Red Hat Ansible Automation Platform, Full Support (1 Managed Node, Dedicated, Monthly)"
+export METRICS_UTILITY_REPORT_H1_HEADING="CCSP Reporting <Company>: ANSIBLE Consumption"
+export METRICS_UTILITY_REPORT_COMPANY_NAME="Company Name"
+export METRICS_UTILITY_REPORT_EMAIL="[email protected]"
+export METRICS_UTILITY_REPORT_RHN_LOGIN="test_login"
+export METRICS_UTILITY_REPORT_COMPANY_BUSINESS_LEADER="BUSINESS LEADER"
+export METRICS_UTILITY_REPORT_COMPANY_PROCUREMENT_LEADER="PROCUREMENT LEADER"
+----
+
+* managed_nodes`
+** This is a deduplicated list of managed nodes automated by automation controller.
+* `indirectly_managed_nodes`
+** This is a deduplicated list of indirect managed nodes automated by automation controller.
+* `inventory_scope`
+** This is a deduplicated list of managed nodes present across all inventories of automation controller.
+* `usage_by_collections`
+** This is a list of Ansible collections used in automation controller job runs.
+* `usage_by_roles`
+** This is a list of roles used in automation controller job runs.
+*`usage_by_modules`
+** This is a list of modules used in automation controller job runs.
+
+----
+# Example with all optional sheets
+export METRICS_UTILITY_OPTIONAL_CCSP_REPORT_SHEETS='ccsp_summary,managed_nodes,indirectly_managed_nodes,inventory_scope,usage_by_collections,usage_by_roles,usage_by_modules'
+----
+
+== Selecting a date range for your CCSP report
+
+The default behavior of this report is to build a report for the previous month. The following examples describe how to override this default behavior to select a specific date range for your report: 
+
+----
+# Builds report for a previous month
+metrics-utility build_report
+
+# Build report for a specific month
+metrics-utility build_report --month=2025-03 
+
+# Build report for a specific month overriding an existing report
+metrics-utility build_report --month=2025-03 --force 
+----

downstream/modules/platform/ref-configuring-metrics-utility.adoc

@@ -0,0 +1,133 @@
+:_newdoc-version: 2.18.3
+:_template-generated: 2024-07-15
+
+:_mod-docs-content-type: REFERENCE
+
+[id="ref-configuring-metrics-utility_{context}"]
+= Configuring metrics-utility 
+
+== On {RHEL}
+
+.Prerequisites
+
+* An active {PlatformName} subscription
+* An existing installation of {PlatformName} on {RHEL}
+
+`metrics-utility` is included with {PlatformName}, so you do not need a separate installation. The following commands gather the relevant data and generate a link:https://connect.redhat.com/en/programs/certified-cloud-service-provider[CCSP] report containing your usage metrics. 
+You can configure these commands as cron jobs to ensure they run at the beginning of every month. See link:https://www.redhat.com/en/blog/linux-cron-command[How to schedule jobs using the Linux 'cron' utility] for more on configuring using the cron syntax.
+
+.Procedure
+. In the `cron` file, set the correct variables to ensure `metrics-utility` gathers the relevant data. To open the cron file for editing, run:
++
+`crontab -e`
+
+. Specify the following variables to indicate where the report is deposited in your file system:
++
+----
+export METRICS_UTILITY_SHIP_TARGET=directory
+export METRICS_UTILITY_SHIP_PATH=/awx_devel/awx-dev/metrics-utility/shipped_data/billing
+----
+. Set these variables to generate a report:
++
+----
+export METRICS_UTILITY_REPORT_TYPE=CCSP
+export METRICS_UTILITY_PRICE_PER_NODE=11.55 # in USD
+export METRICS_UTILITY_REPORT_SKU=MCT3752MO
+export METRICS_UTILITY_REPORT_SKU_DESCRIPTION="EX: Red Hat Ansible Automation Platform, Full Support (1 Managed Node, Dedicated, Monthly)"
+export METRICS_UTILITY_REPORT_H1_HEADING="CCSP Reporting <Company>: ANSIBLE Consumption"
+export METRICS_UTILITY_REPORT_COMPANY_NAME="Company Name"
+export METRICS_UTILITY_REPORT_EMAIL="[email protected]"
+export METRICS_UTILITY_REPORT_RHN_LOGIN="test_login"
+export METRICS_UTILITY_REPORT_COMPANY_BUSINESS_LEADER="BUSINESS LEADER"
+export METRICS_UTILITY_REPORT_COMPANY_PROCUREMENT_LEADER="PROCUREMENT LEADER"
+----
+
+. Run the following command to gather and store the data in the provided `SHIP_PATH` directory:
++
+`metrics-utility gather_automation_controller_billing_data --ship --until=10m`
+
+. To configure the run schedule, add the following parameters to the end of the file and specify how often you want `metrics-utility` to gather information and build a report using link:https://www.redhat.com/en/blog/linux-cron-command[cron syntax]. 
+In the following example, the `gather` command is configured to run every hour at 00 minutes. The `build_report` command is configured to run every second day of each month at 4:00 AM.
++
+----
+0 */1 * * * metrics-utility gather_automation_controller_billing_data --ship --until=10m
+0 4 2 * *  metrics-utility build_report
+----
+
+. Save and close the file.
+. To verify that you saved your changes, run:
++
+`crontab -l`
+
+. You can also check the logs to ensure that data is being collected. Run:
++
+`cat /var/log/cron`
+
+. The following is an example of the output. Note that time and date might vary depending on how your configure the run schedule:
++
+----
+May  8 09:45:03 ip-10-0-6-24 CROND[51623]: (root) CMDOUT (No billing data for month: 2024-04)
+May  8 09:45:03 ip-10-0-6-24 CROND[51623]: (root) CMDEND (metrics-utility build_report)
+May  8 09:45:19 ip-10-0-6-24 crontab[51619]: (root) END EDIT (root)
+May  8 09:45:34 ip-10-0-6-24 crontab[51659]: (root) BEGIN EDIT (root)
+May  8 09:46:01 ip-10-0-6-24 CROND[51688]: (root) CMD (metrics-utility gather_automation_controller_billing_data --ship --until=10m)
+May  8 09:46:03 ip-10-0-6-24 CROND[51669]: (root) CMDOUT (/tmp/9e3f86ee-c92e-4b05-8217-72c496e6ffd9-2024-05-08-093402+0000-2024-05-08-093602+0000-0.tar.gz)
+May  8 09:46:03 ip-10-0-6-24 CROND[51669]: (root) CMDEND (metrics-utility gather_automation_controller_billing_data --ship --until=10m)
+May  8 09:46:26 ip-10-0-6-24 crontab[51659]: (root) END EDIT (root)
+----
+
+. Run the following command to build a report for the previous month:
++
+`metrics-utility build_report`
+
+. The generated report will have the default name `CCSP-<YEAR>-<MONTH>.xlsx` and is located in the ship path that you specified in step 2.
+
+
+== On {OCPShort} from the {PlatformNameShort} operator
+
+`metrics-utility` is included in the {OCPShort} image beginning with version 4.12. 
+If your system does not have `metrics-utility` installed, update your OpenShift image to the latest version.
+Follow the steps below to configure the run schedule for metrics-utility on {OCPShort} using the {PlatformName} Operator.
+
+. Prerequisites:
+
+* A running OpenShift cluster
+* An operator-based installation of {PlatformNameShort} on {OCPShort}.
++
+[Note]
+====
+`metrics-utility` runs as indicated by the parameters you set in the configuration file. 
+The utility cannot be run manually on {OCPShort}.
+====
+
+== Create a ConfigMap in the OpenShift UI YAML view 
+
+.Procedure
+. From the navigation panel, select menu::ConfigMaps[].
+. Click btn:[Create ConfigMap].
+. On the next screen, select the YAML view tab.
+. In the YAML field, enter the following parameters with the appropriate variables set:
++
+----
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: automationcontroller-metrics-utility-configmap
+data:
+  METRICS_UTILITY_SHIP_TARGET: directory
+  METRICS_UTILITY_SHIP_PATH: /metrics-utility
+  METRICS_UTILITY_REPORT_TYPE: CCSP
+  METRICS_UTILITY_PRICE_PER_NODE: '11' # in USD
+  METRICS_UTILITY_REPORT_SKU: MCT3752MO
+  METRICS_UTILITY_REPORT_SKU_DESCRIPTION: "EX: Red Hat Ansible Automation Platform, Full Support (1 Managed Node, Dedicated, Monthly)"
+  METRICS_UTILITY_REPORT_H1_HEADING: "CCSP Reporting <Company>: ANSIBLE Consumption"
+  METRICS_UTILITY_REPORT_COMPANY_NAME: "Company Name"
+  METRICS_UTILITY_REPORT_EMAIL: "[email protected]"
+  METRICS_UTILITY_REPORT_RHN_LOGIN: "test_login"
+  METRICS_UTILITY_REPORT_COMPANY_BUSINESS_LEADER: "BUSINESS LEADER"
+  METRICS_UTILITY_REPORT_COMPANY_PROCUREMENT_LEADER: "PROCUREMENT LEADER"
+----
+
+. Click btn:[Create].
+
+. To verify that the ConfigMap was created and `metric utility` is installed, select menu::ConfigMap[] from the navigation panel and look for your ConfigMap in the list.

downstream/modules/platform/ref-controller-cluster-instance-behavior.adoc

@@ -13,4 +13,4 @@ Rsyslog:: The log processing service used to deliver logs to various external lo
 {ControllerNameStart} is configured so that if any of these services or their components fail, then all services are restarted. 
 If these fail often in a short span of time, then the entire instance is placed offline in an automated fashion to allow remediation without causing unexpected behavior.
 
-For backing up and restoring a clustered environment, see the xref:controller-backup-restore-clustered-environments[Backup and restore clustered environments] section.
+For backing up and restoring a clustered environment, see the link:{URLControllerAdminGuide}/index#controller-backup-restore-clustered-environments[Backup and restore clustered environments] section.