RHIDP-1582: Add docs for enabling metrics collection (#311)

artifacts/attributes.adoc

@@ -25,6 +25,7 @@
 // minimum and current latest supported versions
 :ocp-version-min: 4.12
 :ocp-version: 4.15
+:oc-first: pass:quotes[OpenShift CLI (`oc`)]
 
 // Partner Platforms
 :aws-brand-name: Amazon Web Services

assemblies/assembly-rhdh-observability.adoc

@@ -0,0 +1,17 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="assembly-rhdh-observability"]
+= Enabling observability for {product} on {ocp-short}
+:context: assembly-rhdh-observability
+
+toc::[]
+
+// Metrics
+In {ocp-short}, metrics are exposed through an HTTP service endpoint under the `/metrics` canonical name. You can create a `ServiceMonitor` custom resource (CR) to scrape metrics from a service endpoint in a user-defined project.
+
+include::modules/observability/proc-admin-enabling-metrics-ocp-helm.adoc[leveloffset=+1]
+include::modules/observability/proc-admin-enabling-metrics-ocp-operator.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+[id="additional-resources_{context}"]
+== Additional resources
+* link:https://docs.openshift.com/container-platform/latest/observability/monitoring/managing-metrics.html[{ocp-short} - Managing metrics]

modules/observability/proc-admin-enabling-metrics-ocp-helm.adoc

@@ -0,0 +1,43 @@
+// Module included in the following assemblies:
+//
+// * assemblies/assembly-rhdh-observability.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="proc-admin-enabling-metrics-ocp-helm_{context}"]
+= Enabling metrics monitoring in a Helm chart installation on an {ocp-short} cluster
+
+You can enable and view metrics for a {product} Helm deployment from the *Developer* perspective of the {ocp-short} web console.
+
+.Prerequisites
+
+* Your {ocp-short} cluster has link:https://docs.openshift.com/container-platform/latest/observability/monitoring/enabling-monitoring-for-user-defined-projects.html[monitoring for user-defined projects] enabled.
+* You have installed {product} on {ocp-short} using the Helm chart.
+
+.Procedure
+
+. From the *Developer* perspective in the {ocp-short} web console, select the *Topology* view.
+. Click the overflow menu of the {product} Helm chart, and select *Upgrade*.
++
+image::rhdh/helm-upgrade.png[]
+
+. On the *Upgrade Helm Release* page, select the *YAML view* option in *Configure via*, then configure the `metrics` section in the YAML, as shown in the following example:
++
+[source,yaml]
+----
+upstream:
+# ...
+  metrics:
+    serviceMonitor:
+      enabled: true
+      path: /metrics
+# ...
+----
++
+image::rhdh/upgrade-helm-metrics.png[]
+
+. Click *Upgrade*.
+
+.Verification
+
+. From the *Developer* perspective in the {ocp-short} web console, select the *Observe* view.
+. Click the *Metrics* tab to view metrics for {product} pods.

modules/observability/proc-admin-enabling-metrics-ocp-operator.adoc

@@ -0,0 +1,57 @@
+// Module included in the following assemblies:
+//
+// * assemblies/assembly-rhdh-observability.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="proc-admin-enabling-metrics-ocp-operator_{context}"]
+= Enabling metrics monitoring in a {product} Operator installation on an {ocp-short} cluster
+
+You can enable and view metrics for an Operator-installed {product} instance from the *Developer* perspective of the {ocp-short} web console.
+
+.Prerequisites
+
+* Your {ocp-short} cluster has link:https://docs.openshift.com/container-platform/latest/observability/monitoring/enabling-monitoring-for-user-defined-projects.html[monitoring for user-defined projects] enabled.
+* You have installed {product} on {ocp-short} using the {product} Operator.
+* You have installed the {oc-first}.
+
+.Procedure
+
+Currently, the {product} Operator does not support creating a `ServiceMonitor` custom resource (CR) by default. You must complete the following steps to create a `ServiceMonitor` CR to scrape metrics from the endpoint.
+
+. Create the `ServiceMonitor` CR as a YAML file:
++
+[source,yaml]
+----
+apiVersion: monitoring.coreos.com/v1
+kind: ServiceMonitor
+metadata:
+  name: <custom_resource_name> # <1>
+  namespace: <project_name> # <2>
+  labels:
+    app.kubernetes.io/instance: <custom_resource_name>
+    app.kubernetes.io/name: backstage
+spec:
+  namespaceSelector:
+    matchNames:
+      - <project_name>
+  selector:
+    matchLabels:
+      rhdh.redhat.com/app: backstage-<custom_resource_name>
+  endpoints:
+  - port: backend
+    path: '/metrics'
+----
+<1> Replace `<custom_resource_name>` with the name of your {product} CR.
+<2> Replace `<project_name>` with the name of the {ocp-short} project where your {product} instance is running.
+
+. Apply the `ServiceMonitor` CR by running the following command:
++
+[source,terminal]
+----
+oc apply -f <filename>
+----
+
+.Verification
+
+. From the *Developer* perspective in the {ocp-short} web console, select the *Observe* view.
+. Click the *Metrics* tab to view metrics for {product} pods.

titles/admin-rhdh/title-admin.adoc

@@ -1,4 +1,4 @@
-[id='title-admin']
+[id="title-admin"]
 include::artifacts/attributes.adoc[]
 = Administration guide for {product}
 :context: admin-rhdh