openshift · vikram-redhat · Jun 24, 2021 · May 7, 2021
diff --git a/modules/ossm-config-dist-trac.adoc b/modules/ossm-config-dist-trac.adoc
@@ -8,4 +8,4 @@
 
 Distributed Tracing is the process of tracking the performance of individual services in an application by tracing the path of the service calls in the application. Each time a user takes action in an application, a request is executed that might require many services to interact to produce a response. The path of this request is called a distributed transaction.
 
-{ProductName} uses Jaeger to allow developers to visualize call flows in a microservice application. 
+{ProductName} uses Jaeger to allow developers to view call flows in a microservice application. 
diff --git a/modules/ossm-cr-threescale.adoc b/modules/ossm-cr-threescale.adoc
@@ -7,29 +7,31 @@
 
 = 3scale configuration
 
-Here is an example that illustrates the 3scale Istio Adapter parameters for the {ProductName} custom resource and a description of the available parameters with appropriate values.
+The following table explains the parameters for the 3scale Istio Adapter in the `ServiceMeshControlPlane` resource.
 
 .Example 3scale parameters
 [source,yaml]
 ----
-threeScale:
-  enabled: false
-  PARAM_THREESCALE_LISTEN_ADDR: 3333
-  PARAM_THREESCALE_LOG_LEVEL: info
-  PARAM_THREESCALE_LOG_JSON: true
-  PARAM_THREESCALE_LOG_GRPC: false
-  PARAM_THREESCALE_REPORT_METRICS: true
-  PARAM_THREESCALE_METRICS_PORT: 8080
-  PARAM_THREESCALE_CACHE_TTL_SECONDS: 300
-  PARAM_THREESCALE_CACHE_REFRESH_SECONDS: 180
-  PARAM_THREESCALE_CACHE_ENTRIES_MAX: 1000
-  PARAM_THREESCALE_CACHE_REFRESH_RETRIES: 1
-  PARAM_THREESCALE_ALLOW_INSECURE_CONN: false
-  PARAM_THREESCALE_CLIENT_TIMEOUT_SECONDS: 10
-  PARAM_THREESCALE_GRPC_CONN_MAX_SECONDS: 60
-  PARAM_USE_CACHED_BACKEND: false
-  PARAM_BACKEND_CACHE_FLUSH_INTERVAL_SECONDS: 15
-  PARAM_BACKEND_CACHE_POLICY_FAIL_CLOSED: true
+spec:
+  addons:
+    3Scale:
+      enabled: false
+      PARAM_THREESCALE_LISTEN_ADDR: 3333
+      PARAM_THREESCALE_LOG_LEVEL: info
+      PARAM_THREESCALE_LOG_JSON: true
+      PARAM_THREESCALE_LOG_GRPC: false
+      PARAM_THREESCALE_REPORT_METRICS: true
+      PARAM_THREESCALE_METRICS_PORT: 8080
+      PARAM_THREESCALE_CACHE_TTL_SECONDS: 300
+      PARAM_THREESCALE_CACHE_REFRESH_SECONDS: 180
+      PARAM_THREESCALE_CACHE_ENTRIES_MAX: 1000
+      PARAM_THREESCALE_CACHE_REFRESH_RETRIES: 1
+      PARAM_THREESCALE_ALLOW_INSECURE_CONN: false
+      PARAM_THREESCALE_CLIENT_TIMEOUT_SECONDS: 10
+      PARAM_THREESCALE_GRPC_CONN_MAX_SECONDS: 60
+      PARAM_USE_CACHED_BACKEND: false
+      PARAM_BACKEND_CACHE_FLUSH_INTERVAL_SECONDS: 15
+      PARAM_BACKEND_CACHE_POLICY_FAIL_CLOSED: true
 ----
 
 .3scale parameters

diff --git a/modules/ossm-observability-access.adoc b/modules/ossm-observability-access.adoc
@@ -4,39 +4,22 @@
 //* service_mesh/v2x/ossm-observability.adoc
 
 [id="ossm-observability-access-console_{context}"]
-= Accessing the Kiali console
+= Viewing service mesh data
 
-To access the Kiali console you must have {ProductName} installed and projects configured for the service mesh.
-
-.For administrators
-
-1. Use the perspective switcher to switch to the Administrator perspective. 
-
-2. Click *Home* > *Overview*.
+The Kiali operator works with the telemetry data gathered in {ProductName} to provide graphs and real-time network diagrams of the applications, services, and workloads in your namespace.
 
-3. In the Launcher section, click `Open on Kiali`.
-
-4. Log in to the Kiali console with the same user name and password as you use to access the {product-title} console.
-
-.For developers
+To access the Kiali console you must have {ProductName} installed and projects configured for the service mesh.
 
-1. Use the perspective switcher to switch to the Developer perspective. 
+.Procedure
 
-2. Click *Topology*.
+. Use the perspective switcher to switch to the Administrator perspective. 
 
-3. Click `Kiali` from a node in the topology you have configured for the service mesh. Or click the *Kiali* link in the toolbar.
+. Click *Home* > *Projects*.
 
-4. Log in to the Kiali console with the same user name and password as you use to access the {product-title} console.
+. Click the name of your project. For example click `bookinfo`.
 
-.Procedure from the command line
+. In the Launcher section, click `Kiali`.
 
-. Run this command from the CLI to obtain the route and Kiali URL:
-+
-[source,terminal]
-----
-$ oc get routes
-----
-+
-In the output on the `kiali` line, use the URL in the HOST/PORT column to open the Kiali console. Log in to the Kiali console with the same user name and password as you use to access the {product-title} console. Select the project for your service in the *Namespace* field.
+. Log in to the Kiali console with the same user name and password that you use to access the {product-title} console.
 
 When you first log in to the Kiali Console, you see the Overview page which displays all the namespaces in your mesh that you have permission to view.
diff --git a/modules/ossm-observability-cli.adoc b/modules/ossm-observability-cli.adoc
@@ -0,0 +1,29 @@
+// Module included in the following assemblies:
+//
+//* service_mesh/v2x/ossm-observability.adoc
+
+
+[id="ossm-observability-cli_{context}"]
+= Accessing metrics and tracing data from the CLI
+
+Access the Jaeger, Prometheus, and Grafana consoles to view and manage your data. 
+
+.Procedure
+
+. Switch to the control plane project. In this example, `istio-system` is the control plane project.  Run the following command:
++
+[source,terminal]
+----
+$ oc project istio-system
+----
+
+. Get the routes to {ProductName} components. Run the folowing command:
++
+[source,terminal]
+----
+$ oc get routes
+----
++
+This command returns URLs for the web consoles of Kiali, Jaeger, Prometheus, and Grafana, and any other routes in your service mesh.
+
+. Copy the URL for the component you want from the `HOST/PORT` column into a browser to open the console. 
diff --git a/modules/ossm-observability-visual.adoc b/modules/ossm-observability-visual.adoc
@@ -5,30 +5,43 @@ This module is included in the following assemblies:
 ////
 
 [id="ossm-observability-visual_{context}"]
-= Viewing your service mesh
+= Working with data in the Kiali console
 
-The Kiali operator works with the telemetry data gathered in {ProductName} to provide graphs and real time network diagrams of the applications, services, and workloads in your namespace.
+From the *Graph* menu in the Kiali console, you can use the following graphs and viewing tools to gain deeper insights about data that travels through your service mesh. These tools can help you identify problems with services or workloads.
 
-The Overview page displays all the namespaces that have services in your mesh. You can reveal deeper insights about the data traveling through your Service mesh or help identify problems with services or workloads in your service mesh with the following graphs and visualizations.
+There are several graphs to choose from:
+
+* The *App graph* shows an aggregate workload for all applications that are labeled the same.
+
+* The *Versioned App graph* shows a node for each version of an application. All versions of an application are grouped together.
+
+* The *Workload graph* shows a node for each workload in your service mesh. This graph does not require you to use the application and version labels. If your application does not use version labels, use this the graph.
+
+* The *Service graph* shows a node for each service in your mesh but excludes all applications and workloads from the graph. It provides a high level view and aggregates all traffic for defined services.
+
+To view a summary of metrics, select any node or edge in the graph to display its metric details in the summary details panel.
 
 [id="ossm-observability-topology_{context}"]
 == Namespace graphs
 
-The namespace graph is a map of the services, deployments and workflows in your namespace and arrows that show how data flows through them. To view a namespace graph:
-
-1. Click *Graph* in the main navigation.
-+
-2. Select `bookinfo` from the *Namespace* menu.
+The namespace graph is a map of the services, deployments, and workflows in your namespace and arrows that show how data flows through them. 
 
+.Prerequisite
 
-If your application uses version tags, like the Bookinfo sample application, you can see a Version graph. Select a graph from the Graph Type drop down menu. There are several graphs to choose from:
+* Install the Bookinfo sample application.
 
-* The App graph shows an aggregate workload for all applications that are labeled the same.
+.Procedure 
 
-* The Versioned App graph shows a node for each version of an app. All versions of an app are grouped together.
+. Send traffic to the mesh by entering the following command several times.
++
+[source,terminal]
+----
+$ curl "http://$GATEWAY_URL/productpage"
+----
++
+This command simulates a user visiting the `productpage` microservice of the application.
 
-* The Workload graph shows a node for each workload in your service mesh. This graph does not require you to use the app and version labels. If your app does not use version labels, use this the graph.
+. In the main navigation, click *Graph* to view a namespace graph.
 
-* The Service graph shows a node for each service in your mesh but excludes all applications and workloads from the graph. It provides a high level view and aggregates all traffic for defined services.
+. Select `bookinfo` from the *Namespace* menu.
 
-To view a summary of metrics, select any node or edge in the graph to display its metric details in the summary details panel.
diff --git a/modules/ossm-tutorial-jaeger-generating-traces.adoc b/modules/ossm-tutorial-jaeger-generating-traces.adoc
@@ -7,18 +7,9 @@ This PROCEDURE module included in the following assemblies:
 [id="generating-sample-traces-analyzing-trace-data_{context}"]
 = Generating example traces and analyzing trace data
 
-Jaeger is an open source distributed tracing system. You use Jaeger  for monitoring and troubleshooting microservices-based distributed systems.  Using Jaeger you can perform a trace, which follows the path of a request through various microservices that make up an application.  Jaeger is installed by default as part of the {ProductShortName}.
+Jaeger is an open source distributed tracing system. With Jaeger, you can perform a trace that follows the path of a request through various microservices which make up an application. Jaeger is installed by default as part of the {ProductShortName}.
 
-This tutorial uses {ProductShortName} and the bookinfo tutorial to demonstrate how you can use Jaeger to perform distributed tracing.
-
-[NOTE]
-====
-The Bookinfo example application allows you to test your {ProductName} {ProductVersion} installation on {product-title}.
-
-Red Hat does not provide support for the Bookinfo application.
-====
-
-This tutorial uses {ProductShortName} and the Bookinfo tutorial to demonstrate how you can perform a trace using the Jaeger component of {ProductName}.
+This tutorial uses {ProductShortName} and the Bookinfo sample application to demonstrate how you can use Jaeger to perform distributed tracing.
 
 .Prerequisites:
 
@@ -28,31 +19,33 @@ This tutorial uses {ProductShortName} and the Bookinfo tutorial to demonstrate h
 * Bookinfo example application installed.
 
 .Procedure
-. After you have deployed the Bookinfo application you will need to generate calls to the Bookinfo application so that you have some trace data to analyze. Access `http://<GATEWAY_URL>/productpage` and refresh the page a few times to generate some trace data.
-. The installation process creates a route to access the Jaeger console.
-.. In the {product-title} console, navigate to *Networking* -> *Routes* and search for the Jaeger route, which is the URL listed under *Location*.
-.. Use the CLI to query for details of the route:
-+
-[NOTE]
-====
-Replace `<control_plane_project>` with the name of your control plane project. In this example, the control plane project is `istio-system`.
-====
+
+. After installing the Bookinfo sample application, send traffic to the mesh. Enter the following command several times.
 +
+[source,terminal]
 ----
-$ export JAEGER_URL=$(oc get route -n <control_plane_project> jaeger -o jsonpath='{.spec.host}')
+$ curl "http://$GATEWAY_URL/productpage"
 ----
 +
-. Launch a browser and navigate to `https://<JAEGER_URL>`.
-
-. If necessary, log in using the same user name and password as you use to access the {product-title} console.
+This command simulates a user visiting the `productpage` microservice of the application.
 
-. In the left pane of the Jaeger dashboard, from the Service menu, select "productpage" and click the *Find Traces* button at the bottom of the pane. A list of traces is displayed, as shown in the following image:
-
-+
-image::ossm-jaeger-main-screen.png[]
+. In the {product-title} console, navigate to *Networking* -> *Routes* and search for the Jaeger route, which is the URL listed under *Location*.
+* Alternatively, use the CLI to query for details of the route. In this example, `istio-system` is the control plane namespace:
 +
-. Click one of the traces in the list to open a detailed view of that trace.  If you click on the top (most recent) trace, you see the details that correspond to the latest refresh of the ``/productpage`.
+[source,terminal]
+----
+$ export JAEGER_URL=$(oc get route -n istio-system jaeger -o jsonpath='{.spec.host}')
+----
 +
-image::ossm-jaeger-spans.png[]
+.. Enter the following command to reveal the URL for the Jaeger console. Paste the result in a browser and navigate to that URL.
 +
-The trace in the previous figure consists of a few nested spans, each corresponding to a Bookinfo Service call, all performed in response to a ``/productpage` request. Overall processing time was 2.62s, with the *details* Service taking 3.56ms, the *reviews* Service taking 2.6s, and the *ratings* Service taking 5.32ms. Each of the calls to remote Services is represented by a client-side and server-side span. For example, the *details* client-side span is labeled `productpage details.myproject.svc.cluster.local:9080`. The span nested underneath it, labeled `details details.myproject.svc.cluster.local:9080`, corresponds to the server-side processing of the request. The trace also shows calls to *istio-policy*, which reflect authorization checks made by Istio.
+[source,terminal]
+----
+echo $JAEGER_URL
+----
+
+. Log in using the same user name and password as you use to access the {product-title} console.
+
+. In the left pane of the Jaeger dashboard, from the *Service* menu, select *productpage.bookinfo* and click the *Find Traces* button at the bottom of the pane. A list of traces is displayed.
+
+. Click one of the traces in the list to open a detailed view of that trace.  If you click the first one in the list, which is the most recent trace, you see the details that correspond to the latest refresh of the `/productpage`.
diff --git a/service_mesh/v1x/ossm-observability.adoc b/service_mesh/v1x/ossm-observability.adoc
@@ -7,15 +7,9 @@ toc::[]
 
 You can view your application's topology, health and metrics in the Kiali console. If your service is having issues, the Kiali console offers ways to visualize the data flow through your service. You can view insights about the mesh components at different levels, including abstract applications, services, and workloads. It also provides an interactive graph view of your namespace in real time.
 
-You can observe the data flow through your application if you have one installed. If you don't have your own application installed, you can see how observability works in {ProductName} by installing the xref:../../service_mesh/v1x/prepare-to-deploy-applications-ossm.adoc#ossm-tutorial-bookinfo-overview_deploying-applications-ossm-v1x[Bookinfo sample application].
+.Before you begin
 
-After installing the Bookinfo sample application, send traffic to the mesh. Enter the following command a few times:
-
-----
-$ curl http://$GATEWAY_URL/productpage
-----
-
-If your sample application is configured correctly, this command simulates a user visiting the `productpage` microservice of the application.
+You can observe the data flow through your application if you have an application installed. If you don't have your own application installed, you can see how observability works in {ProductName} by installing the xref:../../service_mesh/v1x/prepare-to-deploy-applications-ossm.adoc#ossm-tutorial-bookinfo-overview_deploying-applications-ossm-v1x[Bookinfo sample application].
 
 include::modules/ossm-observability-access.adoc[leveloffset=+1]
 

diff --git a/service_mesh/v2x/ossm-create-mesh.adoc b/service_mesh/v2x/ossm-create-mesh.adoc
@@ -28,4 +28,4 @@ include::modules/ossm-tutorial-bookinfo-removing.adoc[leveloffset=+2]
 
 == Next steps
 
-* xref:../../service_mesh/v2x/prepare-to-deploy-applications-ossm.adoc#deploying-applications-ossm[Enabling sidecar injection] on {ProductName}.
+* To continue the installation process, you must xref:../../service_mesh/v2x/prepare-to-deploy-applications-ossm.adoc#deploying-applications-ossm[enable sidecar injection]. 
diff --git a/service_mesh/v2x/ossm-observability.adoc b/service_mesh/v2x/ossm-observability.adoc
@@ -5,17 +5,11 @@ include::modules/ossm-document-attributes.adoc[]
 
 toc::[]
 
-You can view your application's topology, health and metrics in the Kiali console. If your service is having issues, the Kiali console offers ways to visualize the data flow through your service. You can view insights about the mesh components at different levels, including abstract applications, services, and workloads. It also provides an interactive graph view of your namespace in real time.
+You can view your application's topology, health, and metrics in the Kiali console. If your service is experiencing problems, the Kiali console allows you to view the data flow through your service. You can view insights about the mesh components at different levels, including abstract applications, services, and workloads. It also provides an interactive graph view of your namespace in real time.
 
-You can observe the data flow through your application if you have one installed. If you don't have your own application installed, you can see how observability works in {ProductName} by installing the xref:../../service_mesh/v2x/prepare-to-deploy-applications-ossm.adoc#ossm-tutorial-bookinfo-overview_ossm-create-mesh[Bookinfo sample application].
+You can observe the data flow through your application if you have an application installed. If you do not have your own application installed, you can see how observability works in {ProductName} by installing the xref:../../service_mesh/v2x/prepare-to-deploy-applications-ossm.adoc#ossm-tutorial-bookinfo-overview_ossm-create-mesh[Bookinfo sample application].
 
-After installing the Bookinfo sample application, send traffic to the mesh. Enter the following command a few times:
-
-----
-$ curl http://$GATEWAY_URL/productpage
-----
-
-If your sample application is configured correctly, this command simulates a user visiting the `productpage` microservice of the application.
+include::modules/ossm-observability-cli.adoc[leveloffset=+1]
 
 include::modules/ossm-observability-access.adoc[leveloffset=+1]
 
@@ -29,6 +23,8 @@ include::modules/ossm-config-sampling.adoc[leveloffset=+2]
 
 include::modules/ossm-config-external-jaeger.adoc[leveloffset=+2]
 
+For more information about configuring Jaeger, see the xref:../../jaeger/jaeger_install/rhbjaeger-deploying.adoc#jaeger-deploy-default_jaeger-deploying[Jaeger documentation].
+
 include::modules/ossm-access-grafana.adoc[leveloffset=+1]
 
 include::modules/ossm-access-prometheus.adoc[leveloffset=+1]
diff --git a/service_mesh/v2x/ossm-reference.adoc b/service_mesh/v2x/ossm-reference.adoc
@@ -5,6 +5,8 @@ include::modules/ossm-document-attributes.adoc[]
 
 include::modules/ossm-cr-example.adoc[leveloffset=+1]
 
+include::modules/ossm-cr-threescale.adoc[leveloffset=+1]
+
 == More information
 
 For more information about how to configure the features in the `ServiceMeshControlPlane` see the following link.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -8,4 +8,4 @@

		Distributed Tracing is the process of tracking the performance of individual services in an application by tracing the path of the service calls in the application. Each time a user takes action in an application, a request is executed that might require many services to interact to produce a response. The path of this request is called a distributed transaction.

		{ProductName} uses Jaeger to allow developers to visualize call flows in a microservice application.
		{ProductName} uses Jaeger to allow developers to view call flows in a microservice application.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -28,4 +28,4 @@ include::modules/ossm-tutorial-bookinfo-removing.adoc[leveloffset=+2]

		== Next steps

		* xref:../../service_mesh/v2x/prepare-to-deploy-applications-ossm.adoc#deploying-applications-ossm[Enabling sidecar injection] on {ProductName}.
		* To continue the installation process, you must xref:../../service_mesh/v2x/prepare-to-deploy-applications-ossm.adoc#deploying-applications-ossm[enable sidecar injection].