OSSM-11009 [DOCS] Update OSSM metrics docs for ambient mode

modules/ossm-config-openshift-monitoring-ambient-mode.adoc

@@ -0,0 +1,144 @@
+// Module included in the following assemblies:
+//
+// * service-mesh-docs-main/metrics/ossm-metrics.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="ossm-config-openshift-monitoring-ambient-mode_{context}"]
+= Configuring OpenShift Monitoring with Service Mesh ambient mode
+
+[role="_abstract"]
+You can integrate {SMProductName} with user-workload monitoring to enable observability in your service mesh ambient mode. User-workload monitoring provides access to essential built-in tools and is required to run Kiali, the dedicated console for {istio}. 
+
+.Prerequisites
+
+* You have installed the {SMProductName} Operator.
+* You have enabled the user-workload monitoring.
++
+[NOTE]
+====
+You can enable user-workload monitoring by applying the `ConfigMap` change for metrics integration. For more information, see link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/monitoring/configuring-user-workload-monitoring[Configuring user workload monitoring].
+====
+
+.Procedure
+
+. Create a `Service` resource to define a port that uses the metrics exposed by the ztunnel, similar to the following example:
+
++
+[source,yaml]
+----
+apiVersion: v1
+kind: Service
+metadata:
+  name: ztunnel
+  namespace: ztunnel
+  labels:
+    app: ztunnel
+    service: ztunnel
+spec:
+  selector:
+    app: ztunnel
+  ports:
+    - name: http-monitoring
+      protocol: TCP
+      port: 15020
+      targetPort: 15020
+----
+
+. Create a `ServiceMonitor` resource that monitors the {istio} control plane, similar to the following example:
++
+[source,yaml]
+----
+apiVersion: monitoring.coreos.com/v1
+kind: ServiceMonitor
+metadata:
+  name: istiod-monitor
+  namespace: istio-system
+spec:
+  targetLabels:
+  - app
+  selector:
+    matchLabels:
+      istio: pilot
+  endpoints:
+  - port: http-monitoring
+    interval: 30s
+----
+
+. Create a `ServiceMonitor` resource that collects the ztunnel metrics, similar to the following example:
++
+[source,yaml]
+----
+apiVersion: monitoring.coreos.com/v1
+kind: ServiceMonitor
+metadata:
+  name: ztunnel-monitor
+  namespace: ztunnel
+spec:
+  targetLabels:
+  - app
+  selector:
+    matchLabels:
+      service: ztunnel
+  endpoints:
+  - port: http-monitoring
+    interval: 30s
+----
+
+. Optional: Deploy a waypoint proxy to enable the Layer 7 (L7) features, such as HTTP metrics and traces in ambient mode:
+
+.. Deploy a custom waypoint proxy with additional labels and ports, similar to the following example:
++
+[source,yaml]
+----
+ apiVersion: gateway.networking.k8s.io/v1
+kind: Gateway
+metadata:
+  labels:
+    istio.io/waypoint-for: service
+    app: waypoint
+    service: waypoint
+  name: waypoint
+  namespace: bookinfo
+spec:
+  gatewayClassName: istio-waypoint
+  listeners:
+  - name: mesh
+    port: 15008
+    protocol: HBONE
+  - name: http-monitoring
+    protocol: TCP
+    port: 15020
+----
+`<http-monitoring>`:: Specifies an additional port that exposes the metrics used by the waypoint proxy.
+
+.. Enroll the namespace to use the waypoint by running the following command:
++
+[source,terminal]
+----
+$ oc label namespace bookinfo istio.io/use-waypoint=waypoint
+----
+
+.. Create a `ServiceMonitor` resource that collects the waypoint proxy metrics, similar to the following example:
++
+[source,yaml]
+----
+apiVersion: monitoring.coreos.com/v1
+kind: ServiceMonitor
+metadata:
+  name: waypoint-monitor
+  namespace: bookinfo
+spec:
+  targetLabels:
+  - app
+  selector:
+    matchLabels:
+      service: waypoint
+  endpoints:
+  - port: http-monitoring
+    interval: 30s
+----
++
+[NOTE]
+====
+A waypoint proxy generates Layer 4 (L4) and L7 metrics. It scopes these statistics by Envoy proxy functions. The Envoy statistic functions are described in Envoy proxy documentation, for example, `Upstream connection`, `Listener`, `HTTP Connection Manager`, `TCP proxy`, and `Router`.
+====

modules/ossm-config-openshift-monitoring-only.adoc

@@ -6,25 +6,24 @@
 [id="ossm-config-openshift-monitoring-only_{context}"]
 = Configuring OpenShift Monitoring with Service Mesh
 
-// This is WITHOUT Kiali.
-// TP1 content. TP banner is persistent and handled by Tim O'Keefe in a different PR.
-// Possible file name may change
-// Possible assembly file may change
-// Assemblies, topic map info needs to be worked out still for 3.0.
-
+[role="_abstract"]
 You can integrate {SMProductName} with user-workload monitoring to enable observability in your service mesh. User-workload monitoring provides access to essential built-in tools and is required to run Kiali, the dedicated console for {istio}.
 
 .Prerequisites
 
-* {SMProductName} is installed.
+* You have installed the {SMProductName} Operator.
 
-* User-workload monitoring is enabled. See link:https://docs.openshift.com/container-platform/4.16/observability/monitoring/enabling-monitoring-for-user-defined-projects.html[Enabling monitoring for user-defined projects].
+* You have enabled the user-workload monitoring.
++
+[NOTE]
+====
+You can enable user-workload monitoring by applying the `ConfigMap` change for metrics integration. For more information, see link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/monitoring/configuring-user-workload-monitoring[Configuring user workload monitoring].
+====
 
 .Procedure
 
-. Create a YAML file named `servicemonitor.yml` to monitor the {istio} control plane:
+. Create a `ServiceMonitor` resource that monitors the {istio} control plane, similar to the following example:
 +
-.Example `ServiceMonitor` object
 [source,yaml]
 ----
 apiVersion: monitoring.coreos.com/v1
@@ -43,76 +42,6 @@ spec:
     interval: 30s
 ----
 
-. Apply the YAML file by running the following command:
-+
-[source,terminal]
-----
-$ oc apply -f servicemonitor.yml
-----
-
-. Create a YAML file named `podmonitor.yml` to collect metrics from the {istio} proxies:
-+
-.Example `PodMonitor` object
-[source,yaml]
-----
-apiVersion: monitoring.coreos.com/v1
-kind: PodMonitor
-metadata:
-  name: istio-proxies-monitor
-  namespace: istio-system # <1>
-spec:
-  selector:
-    matchExpressions:
-    - key: istio-prometheus-ignore
-      operator: DoesNotExist
-  podMetricsEndpoints:
-  - path: /stats/prometheus
-    interval: 30s
-    relabelings:
-    - action: keep
-      sourceLabels: ["__meta_kubernetes_pod_container_name"]
-      regex: "istio-proxy"
-    - action: keep
-      sourceLabels: ["__meta_kubernetes_pod_annotationpresent_prometheus_io_scrape"]
-    - action: replace
-      regex: (\d+);(([A-Fa-f0-9]{1,4}::?){1,7}[A-Fa-f0-9]{1,4})
-      replacement: '[$2]:$1'
-      sourceLabels: ["__meta_kubernetes_pod_annotation_prometheus_io_port","__meta_kubernetes_pod_ip"]
-      targetLabel: "__address__"
-    - action: replace
-      regex: (\d+);((([0-9]+?)(\.|$)){4})
-      replacement: '$2:$1'
-      sourceLabels: ["__meta_kubernetes_pod_annotation_prometheus_io_port","__meta_kubernetes_pod_ip"]
-      targetLabel: "__address__"
-    - sourceLabels: ["__meta_kubernetes_pod_label_app_kubernetes_io_name","__meta_kubernetes_pod_label_app"]
-      separator: ";"
-      targetLabel: "app"
-      action: replace
-      regex: "(.+);.*|.*;(.+)"
-      replacement: "${1}${2}"
-    - sourceLabels: ["__meta_kubernetes_pod_label_app_kubernetes_io_version","__meta_kubernetes_pod_label_version"]
-      separator: ";"
-      targetLabel: "version"
-      action: replace
-      regex: "(.+);.*|.*;(.+)"
-      replacement: "${1}${2}"
-    - sourceLabels: ["__meta_kubernetes_namespace"]
-      action: replace
-      targetLabel: namespace
-    - action: replace
-      replacement: "the-mesh-identification-string" # <2>
-      targetLabel: mesh_id
-----
-<1> Specifies that the `PodMonitor` object must be applied in all mesh namespaces, including the Istio control plane namespace, because {ocp-product-title} monitoring ignores the `namespaceSelector` spec in `ServiceMonitor` and `PodMonitor` objects.
-<2> Specify the actual mesh ID.
-
-. Apply the YAML file by running the following command:
-+
-[source,terminal]
-----
-$ oc apply -f podmonitor.yml
-----
-
 . On the {ocp-short-name} Console go to **Observe** -> **Metrics**, and run the query `istio_requests_total`.
 +
 [NOTE]

modules/ossm-verifying-metrics-ambient-mode.adoc

@@ -0,0 +1,34 @@
+// Module included in the following assemblies:
+//
+// * service-mesh-docs-main/metrics/ossm-metrics.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="ossm-validating-metrics-ambient-mode_{context}"]
+= Verifying metrics in ambient mode
+
+[role="_abstract"]
+You can verify that the metrics for the Bookinfo application that are available in the OpenShift Console.
+
+.Prerequisites
+
+* You have deployed the Bookinfo application in ambient mode to use the following example. For more information, see https://docs.redhat.com/en/documentation/red_hat_openshift_service_mesh/3.2/html/installing/ossm-istio-ambient-mode#ossm-deploying-bookinfo-application-istio-ambient-mode_ossm-istio-ambient-mode[Deploying the Bookinfo application in Istio ambient mode].
+
+.Procedure
+
+. On the {ocp-short-name} Console go to *Observe* -> *Targets*.
+
+. Find the status of `Metrics Targets` by searching for targets such as `istiod-monitor`, `ztunnel-monitor` and `waypoint-monitor`.
++
+[NOTE]
+====
+The `ServiceMonitor` resource configuration can take a few minutes to show in the `Metrics Targets` results.
+====
+
+. Send some traffic to the Bookinfo `productpage` service for generating metrics, by running the following command:
++
+[source,terminal]
+----
+$ curl "http://${GATEWAY_URL}/productpage" | grep "<title>"
+----
+
+. On the {ocp-short-name} Console go to *Observe* -> *Metrics* and run a query such as, `istio_build`, `istio_tcp_received_bytes_total`, or `istio_requests_total`.

observability/metrics/ossm-metrics.adoc

@@ -6,16 +6,17 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
+[role="_abstract"]
 Monitoring stack components are deployed by default in every {ocp-product-title} installation and are managed by the Cluster Monitoring Operator (CMO). These components include Prometheus, Alertmanager, Thanos Querier, and others. The CMO also deploys the Telemeter Client, which sends a subset of data from platform Prometheus instances to Red{nbsp}Hat to facilitate Remote Health Monitoring for clusters.
 
-// If there is an attribute for Cluster Monitoring Operator, it is not part of the common-attributes file for service-mesh-docs-main as of 08/27/2024. If it is added before Aug 30, 2024, this will be updated accordingly. Due to time constraints, it may be a post-TP1/in-time-for GA update.
-
 When you have added your application to the mesh, you can monitor the in-cluster health and performance of your applications running on {ocp-product-title} with metrics and customized alerts for CPU and memory usage, network connectivity, and other resource usage.
 
+When you have added your application to the mesh in ambient mode, you can monitor the {istio} standard metrics of your application from the `ztunnel` resource and the waypoint proxies. The ztunnel also exposes a variety of DNS and debugging metrics.
+
+Ambient mode uses two proxy layers, which results in two types of metrics for each application service. You can collect Layer 4 (L4) TCP metrics from both the ztunnel and the waypoint proxies. You can collect Layer 7 (L7) metrics, such as HTTP traffic metrics, from the waypoint proxies.
+
 include::modules/ossm-config-openshift-monitoring-only.adoc[leveloffset=+1]
 
-// There will be more metric things for GA. This is what is ready for TP
-// TP1 content. TP banner is persistent and handled by a different PR from Tim O'Keefe.
-// Possible file name may change
-// Possible assembly file may change
-// Assemblies, topic map info needs to be worked out still for 3.0.
+include::modules/ossm-config-openshift-monitoring-ambient-mode.adoc[leveloffset=+1]
+
+include::modules/ossm-verifying-metrics-ambient-mode.adoc[leveloffset=+2]

observability/ossm-observability-service-mesh.adoc

@@ -6,6 +6,7 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
+[role="_abstract"]
 Red{nbsp}Hat OpenShift Observability provides real-time visibility, monitoring, and analysis of various system metrics, logs, and events to help you quickly diagnose and troubleshoot issues before they impact systems or applications.
 
 Red{nbsp}Hat OpenShift Observability connects open-source observability tools and technologies to create a unified Observability solution. The components of Red Hat OpenShift Observability work together to help you collect, store, deliver, analyze, and visualize data.
@@ -20,11 +21,7 @@ Red{nbsp}Hat OpenShift Observability connects open-source observability tools an
 * Kiali provided by Red{nbsp}Hat, a powerful console for visualizing and managing your service mesh.
 * {SMPlugin}, an {ocp-product-title} console plugin that seamlessly integrates Kiali console features into your {ocp-short-name} console.
 
-//Observability attributes are not part of the Service Mesh standalone attributes file as of 10/22/2024
-//There are Kiali attributes forthcoming.
-//Kiali Operator provided by Red Hat is the official, approved name, and the name that appears in the console UI when presented with Kiali Operator options to install.
-//There is a Jira created to add a number of attributes to the _attributes file for OSSM 3.0 GA.
-//There are more things coming for Metrics, distributed tracing, and Kiali. The Service Mesh Console (OSSMC) plugin, for example, will be added to the Kiali distro. It is unclear what is necessary for GA and what is  being pushed post-GA, so the directories and respective assemblies have been left for traces, metrics, and kiali.
+The following components in {SMProduct} ambient mode generate a detailed telemetry for all service communications within a mesh:
 
-// TP 1 content. Banner handled separately by different PR handled by Tim O'Keefe. Per Tim, banner should appear across all 3.0 content, nothing needs to be added to this file
-// Content may change, file names may change, directories may change, the order of directories may change, everything may change.
+* Ztunnel generates Layer 4 (L4) telemetry such as TCP metrics.
+* Waypoint proxies generates Layer 7 (L7) telemetry for HTTP, HTTP/2, gRPC traffic metrics, and distributed traces.