adding usage examples

_topic_map.yml

@@ -871,6 +871,8 @@ Topics:
     File: metering-storage-locations
 - Name: Using metering
   File: metering-using-metering
+- Name: Examples of using metering
+  File: metering-usage-examples
 - Name: Troubleshooting and debugging
   File: metering-troubleshooting-debugging
 ---

metering/metering-usage-examples.adoc

@@ -0,0 +1,18 @@
+[id="metering-usage-examples"]
+= Examples of using metering
+include::modules/common-attributes.adoc[]
+:context: metering-usage-examples
+
+toc::[]
+
+Use the following example Reports to get started measuring capacity, usage, and utilization in your cluster. These examples showcase the various types of reports metering offers, along with a selection of the predefined queries.
+
+.Prerequisites
+* xref:../metering/metering-installing-metering.adoc#metering-install-operator_installing-metering[Install Metering]
+* Review the details about xref:../metering/metering-using-metering#using-metering[writing and viewing reports].
+
+include::modules/metering-cluster-capacity-examples.adoc[leveloffset=+1]
+
+include::modules/metering-cluster-usage-examples.adoc[leveloffset=+1]
+
+include::modules/metering-cluster-utilization-examples.adoc[leveloffset=+1]

modules/metering-cluster-capacity-examples.adoc

@@ -0,0 +1,48 @@
+// Module included in the following assemblies:
+//
+// * metering/metering-usage-examples.adoc
+
+[id="metering-cluster-capacity-examples_{context}"]
+= Measure cluster capacity hourly and daily
+
+The following Report demonstrates how to measure cluster capacity both hourly and daily. The daily Report works by aggregating the hourly Report's results.
+
+The following report measures cluster CPU capacity every hour.
+
+.Hourly CPU capacity by cluster example
+
+[source,yaml]
+----
+apiVersion: metering.openshift.io/v1
+kind: Report
+metadata:
+  name: cluster-cpu-capacity-hourly
+spec:
+  query: "cluster-cpu-capacity"
+  schedule:
+    period: "hourly" <1>
+----
+<1> You could change this period to `daily` to get a daily report, but with larger data sets it is more efficient to use an hourly report, then aggregate your hourly data into a daily report.
+
+The following report aggregates the hourly data into a daily report.
+
+.Daily CPU capacity by cluster example
+
+[source,yaml]
+----
+apiVersion: metering.openshift.io/v1
+kind: Report
+metadata:
+  name: cluster-cpu-capacity-daily <1>
+spec:
+  query: "cluster-cpu-capacity" <2>
+  inputs: <3>
+  - name: ClusterCpuCapacityReportName
+    value: cluster-cpu-capacity-hourly
+  schedule:
+    period: "daily"
+----
+
+<1> To stay organized, remember to change the name of your Report if you change any of the other values.
+<2> You can also measure `cluster-memory-capacity`. Remember to update the query in the associated hourly report as well.
+<3> The `inputs` section configures this report to aggregate the hourly report. Specifically, `value: cluster-cpu-capacity-hourly` is the name of the hourly report that gets aggregated.

modules/metering-cluster-usage-examples.adoc

@@ -0,0 +1,27 @@
+// Module included in the following assemblies:
+//
+// * metering/metering-usage-examples.adoc
+
+[id="metering-cluster-usage-examples_{context}"]
+= Measure cluster usage with a one-time Report
+
+The following Reports to measure cluster usage from a specific starting date forward. The Report only runs once, after you save it and apply it.
+
+.CPU usage by cluster example
+
+[source,yaml]
+----
+apiVersion: metering.openshift.io/v1
+kind: Report
+metadata:
+  name: cluster-cpu-usage-2019 <1>
+spec:
+  reportingStart: '2019-01-01T00:00:00Z' <2>
+  reportingEnd: '2019-12-30T23:59:59Z'
+  query: cluster-cpu-usage <3>
+  runImmediately: true <4>
+----
+<1> To say organized, remember to change the name of your Report if you change any of the other values.
+<2> Configures the Reports to start using data from the `reportingStart` timestamp until the `reportingEnd` timestamp. 
+<3> Adjust your query here. You can also measure cluster usage with the `cluster-memory-usage` query.
+<4> This tells the Report to run immediately after saving it an applying it.

modules/metering-cluster-utilization-examples.adoc

@@ -0,0 +1,26 @@
+// Module included in the following assemblies:
+//
+// * metering/metering-usage-examples.adoc
+
+[id="metering-cluster-utilization-examples_{context}"]
+= Measure cluster utilization using cron expressions
+
+You can also use cron expressions when configuring the period of your repots. The following report measure cluster utilization by looking at CPU utilization from 9am-5pm every weekday.
+
+.Weekday CPU utilization by cluster example
+
+[source,yaml]
+----
+apiVersion: metering.openshift.io/v1
+kind: Report
+metadata:
+  name: cluster-cpu-utilization-weekdays <1>
+spec:
+  query: "cluster-cpu-utilization" <2>
+  schedule:
+    period: "cron"
+      expression: 0 0 * * 1-5 <3>
+----
+<1> To say organized, remember to change the name of your Report if you change any of the other values.
+<2> Adjust your query here. You can also measure cluster utilization with the `cluster-memory-utilization` query.
+<3> For cron periods, normal cron expressions are valid.