openshift · JStickler · Jan 6, 2022 · Jan 6, 2022
diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml
@@ -2735,7 +2735,7 @@ Topics:
     File: ossm-security
   - Name: Traffic management
     File: ossm-traffic-manage
-  - Name: Metrics and traces
+  - Name: Metrics, logs, and traces
     File: ossm-observability
   - Name: Performance and scalability
     File: ossm-performance-scalability

diff --git a/modules/ossm-access-grafana.adoc b/modules/ossm-access-grafana.adoc
@@ -3,7 +3,7 @@
 // * service_mesh/v2x/ossm-observability.adoc
 
 [id="ossm-access-grafana_{context}"]
-= Accessing Grafana
+= Accessing the Grafana console
 
 Grafana is an analytics tool that you can use to view, query, and analyze your service mesh metrics. In this example, `istio-system` is the control plane namespace. To access Grafana, do the following:
 

diff --git a/modules/ossm-access-prometheus.adoc b/modules/ossm-access-prometheus.adoc
@@ -3,7 +3,7 @@
 // * service_mesh/v2x/ossm-observability.adoc
 
 [id="ossm-access-prometheus_{context}"]
-= Accessing Prometheus
+= Accessing the Prometheus console
 
 Prometheus is a monitoring and alerting tool that you can use to collect multi-dimensional data about your microservices. In this example, `istio-system` is the control plane namespace.
 

diff --git a/modules/ossm-config-dist-trac.adoc b/modules/ossm-config-dist-trac.adoc
diff --git a/modules/ossm-config-external-jaeger.adoc b/modules/ossm-config-external-jaeger.adoc
@@ -1,15 +1,16 @@
-// Module included in the following assemblies:
-//
-// * service_mesh/v2x/ossm-config.adoc
+////
+This module is included in the following assemblies:
+* service_mesh/v2x/ossm-observability.adoc
+////
 
 [id="ossm-config-external-jaeger_{context}"]
-= Connecting standalone Jaeger
+= Connecting an existing distributed tracing instance
 
-If you already use standalone Jaeger for distributed tracing in {product-title}, configure your `ServiceMeshControlPlane` resource to use that standalone Jaeger instance rather than the one installed with {ProductName}.
+If you already have an existing {JaegerName} instance in {product-title}, you can configure your `ServiceMeshControlPlane` resource to use that instance for {DTShortName}.
 
 .Prerequisites
 
-* Configure and deploy a standalone Jaeger instance. For more information, see the Jaeger documentation.
+* {DTProductName} instance installed and configured.
 
 .Procedure
 
@@ -19,19 +20,19 @@ If you already use standalone Jaeger for distributed tracing in {product-title},
 
 . Click the {ProductName} Operator. In the *Istio Service Mesh Control Plane* column, click the name of your `ServiceMeshControlPlane` resource, for example `basic`.
 
-. Add the name of your standalone Jaeger instance to the `ServiceMeshControlPlane`.
+. Add the name of your {JaegerShortName} instance to the `ServiceMeshControlPlane`.
 +
 .. Click the *YAML* tab.
 +
-.. Add the name of your standalone Jaeger instance to `spec.addons.jaeger.name` in your `ServiceMeshControlPlane` resource. In the following example, `simple-prod` is the name of your standalone Jaeger instance.
+.. Add the name of your {JaegerShortName} instance to `spec.addons.jaeger.name` in your `ServiceMeshControlPlane` resource. In the following example, `distr-tracing-production` is the name of the {JaegerShortName} instance.
 +
-.Standalone Jaeger example
+.Example distributed tracing configuration
 [source,yaml]
 ----
 spec:
   addons:
     jaeger:
-      name: simple-prod
+      name: distr-tracing-production
 ----
 +
 .. Click *Save*.

diff --git a/modules/ossm-config-sampling.adoc b/modules/ossm-config-sampling.adoc
@@ -1,6 +1,7 @@
-// Module included in the following assemblies:
-//
-// * service_mesh/v2x/ossm-config.adoc
+////
+This module is included in the following assemblies:
+* service_mesh/v2x/ossm-observability.adoc
+////
 
 [id="ossm-config-sampling_{context}"]
 = Adjusting the sampling rate

diff --git a/modules/ossm-control-plane-cli.adoc b/modules/ossm-control-plane-cli.adoc
@@ -1,6 +1,7 @@
-// Module included in the following assemblies:
-//
-// * service_mesh/v2x/installing-ossm.adoc
+////
+This module is included in the following assemblies:
+* service_mesh/v2x/ossm-observability.adoc
+////
 
 [id="ossm-control-plane-deploy-cli_{context}"]
 = Deploying the control plane from the CLI

diff --git a/modules/ossm-distr-tracing.adoc b/modules/ossm-distr-tracing.adoc
@@ -0,0 +1,12 @@
+////
+This module is included in the following assemblies:
+* service_mesh/v1x/ossm-config.adoc
+* service_mesh/v2x/ossm-observability.adoc
+////
+
+[id="ossm-overview-distr-tracing_{context}"]
+= Distributed tracing
+
+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 {DTProductName} to allow developers to view call flows in a microservice application.
diff --git a/modules/ossm-document-attributes-1x.adoc b/modules/ossm-document-attributes-1x.adoc
@@ -1,4 +1,4 @@
-// Standard document attributes to be used in the Service Mesh documentation
+// Standard document attributes to be used in the Service Mesh documentation v1.x
 //
 // The following are shared by all RHOSSM documents:
 :toc:

diff --git a/modules/ossm-jaeger-accessing-console.adoc b/modules/ossm-jaeger-accessing-console.adoc
@@ -0,0 +1,61 @@
+////
+Module included in the following assemblies:
+* service_mesh/v2x/ossm-observability.adoc
+* service_mesh/v2x/ossm-troubleshooting-istio.adoc
+////
+
+[id="ossm-accessing-jaeger-console_{context}"]
+= Accessing the Jaeger console
+
+To access the Jaeger console you must have {ProductName} installed, {JaegerName} installed and configured.
+
+The installation process creates a route to access the Jaeger console.
+
+If you know the URL for the Jaeger console, you can access it directly.  If you do not know the URL, use the following directions.
+
+.Procedure from OpenShift console
+. Log in to the {product-title} web console as a user with cluster-admin rights. If you use {product-dedicated}, you must have an account with the `dedicated-admin` role.
+
+. Navigate to *Networking* -> *Routes*.
+
+. On the *Routes* page, select the control plane project, for example `istio-system`, from the *Namespace* menu.
++
+The *Location* column displays the linked address for each route.
++
+. If necessary, use the filter to find the `jaeger` route.  Click the route *Location* to launch the console.
+
+. Click *Log In With OpenShift*.
+
+
+.Procedure from Kiali console
+
+. Launch the Kiali console.
+
+. Click *Distributed Tracing* in the left navigation pane.
+
+. Click *Log In With OpenShift*.
+
+
+.Procedure from the CLI
+
+. Log in to the {product-title} CLI as a user with the `cluster-admin` role. If you use Red Hat OpenShift Dedicated, you must have an account with the `dedicated-admin` role.
++
+[source,terminal]
+----
+$ oc login https://{HOSTNAME}:6443
+----
++
+. To query for details of the route using the command line, enter the following command. In this example, `istio-system` is the control plane namespace.
++
+[source,terminal]
+----
+$ export JAEGER_URL=$(oc get route -n istio-system jaeger -o jsonpath='{.spec.host}')
+----
++
+. Launch a browser and navigate to ``\https://<JAEGER_URL>``, where `<JAEGER_URL>` is the route that you discovered in the previous step.
+
+. Log in using the same user name and password that you use to access the {Product-title} console.
+
+. If you have added services to the service mesh and have generated traces, you can use the filters and *Find Traces* button to search your trace data.
++
+If you are validating the console installation, there is no trace data to display.
diff --git a/modules/ossm-kiali-accessing-console.adoc b/modules/ossm-kiali-accessing-console.adoc
@@ -0,0 +1,48 @@
+////
+Module included in the following assemblies:
+* service_mesh/v2x/ossm-observability.adoc
+* service_mesh/v2x/ossm-troubleshooting-istio.adoc
+////
+
+[id="ossm-accessing-kiali-console_{context}"]
+= Accessing the Kiali console
+
+You can view your application's topology, health, and metrics in the Kiali console. If your service is experiencing problems, the Kiali console lets you view the data flow through your service. You can view insights about the mesh components at different levels, including abstract applications, services, and workloads. Kiali also provides an interactive graph view of your namespace in real time.
+
+To access the Kiali console you must have {ProductName} installed, Kiali installed and configured.
+
+The installation process creates a route to access the Kiali console.
+
+If you know the URL for the Kiali console, you can access it directly.  If you do not know the URL, use the following directions.
+
+.Procedure for administrators
+
+. Log in to the {product-title} web console with an administrator role.
+
+. Click *Home* -> *Projects*.
+
+. On the *Projects* page, if necessary, use the filter to find the name of your project.
+
+. Click the name of your project, for example, `bookinfo`.
+
+. On the *Project details* page, in the *Launcher* section, click the *Kiali* link.
+
+. 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 service mesh that you have permission to view.
++
+If you are validating the console installation and namespaces have not yet been added to the mesh, there might not be any data to display other than `istio-system`.
+
+.Procedure for developers
+
+. Log in to the {product-title} web console with a developer role.
+
+. Click *Project*.
+
+. On the *Project Details* page, if necessary, use the filter to find the name of your project.
+
+. Click the name of your project, for example, `bookinfo`.
+
+. On the *Project* page, in the *Launcher* section, click the *Kiali* link.
+
+. Click *Log In With OpenShift*.
diff --git a/modules/ossm-kiali-viewing-logs.adoc b/modules/ossm-kiali-viewing-logs.adoc
@@ -0,0 +1,35 @@
+////
+Module included in the following assemblies:
+* service_mesh/v2x/ossm-observability.adoc
+////
+
+[id="ossm-viewing-logs_{context}"]
+= Viewing logs in the Kiali console
+
+You can view logs for your workloads in the Kiali console.  The *Workload Detail* page includes a *Logs* tab which displays a unified logs view that displays both application and proxy logs. You can select how often you want the log display in Kiali to be refreshed.
+
+To change the logging level on the logs displayed in Kiali, you change the logging configuration for the workload or the proxy.
+
+// TODO once released - Kiali can also add-in trace span information to help identify important traces based on associated logging. More powerful features include substring or regex Show/Hide, full-screen, and the ability to set proxy log level without a pod restart.
+
+.Prerequisites
+
+* Service Mesh installed and configured.
+* Kiali installed and configured.
+* The address for the Kiali console.
+
+.Procedure
+
+. Launch the Kiali console.
+
+. Click *Log In With OpenShift*.
++
+The Kiali Overview page displays namespaces that have been added to the mesh that you have permissions to view.
++
+. Click *Workloads*.
+
+. On the *Workloads* page, select the project from the *Namespace* menu.
+
+. If necessary, use the filter to find the workload whose logs you want to view.  Click the workload *Name*.
+
+. On the *Workload Details* page, click the *Logs* tab to view the logs for the workload.
diff --git a/modules/ossm-kiali-viewing-metrics.adoc b/modules/ossm-kiali-viewing-metrics.adoc
@@ -0,0 +1,42 @@
+////
+Module included in the following assemblies:
+* service_mesh/v2x/ossm-observability.adoc
+////
+
+[id="ossm-viewing-metrics_{context}"]
+= Viewing metrics in the Kiali console
+
+You can view inbound and outbound metrics for your applications, workloads, and services in the Kiali console.  The Detail pages include the following tabs:
+
+* inbound Application metrics
+* outbound Application metrics
+* inbound Workload metrics
+* outbound Workload metrics
+* inbound Service metrics
+
+These tabs display predefined metrics dashboards, tailored to the relevant application, workload or service level. The application and workload detail views show request and response metrics such as volume, duration, size, or TCP traffic. The service detail view shows request and response metrics for inbound traffic only.
+
+Kiali lets you customize the charts by choosing the charted dimensions. Kiali can also present metrics reported by either source or destination proxy metrics. And for troubleshooting, Kiali can overlay trace spans on the metrics.
+
+.Prerequisites
+
+* Service Mesh installed and configured.
+* Kiali installed and configured.
+* The address for the Kiali console.
+* (Optional) Distributed tracing installed and configured.
+
+.Procedure
+
+. Launch the Kiali console.
+
+. Click *Log In With OpenShift*.
++
+The Kiali Overview page displays namespaces that have been added to the mesh that you have permissions to view.
++
+. Click either *Applications*, *Workloads*, or *Services*.
+
+. On the *Applications*, *Workloads*, or *Services* page, select the project from the *Namespace* menu.
+
+. If necessary, use the filter to find the application, workload, or service whose logs you want to view.  Click the *Name*.
+
+. On the *Application Detail*, *Workload Details*, or *Service Details* page, click either the *Inbound Metrics* or *Outbound Metrics* tab to view the metrics.
diff --git a/modules/ossm-observability-addresses.adoc b/modules/ossm-observability-addresses.adoc
@@ -0,0 +1,74 @@
+////
+Module included in the following assemblies:
+* service_mesh/v2x/ossm-observability.adoc
+////
+
+[id="ossm-observability-addresses_{context}"]
+= Discovering console addresses
+
+{ProductName} provides the following consoles to view your service mesh data:
+
+* *Kiali console* - Kiali is the management console for {ProductName}.
+* *Jaeger console* - Jaeger is the management console for {DTProductName}.
+* *Grafana console* - Grafana provides mesh administrators with advanced query and metrics analysis and dashboards for Istio data. Optionally, Grafana can be used to analyze service mesh metrics.
+* *Prometheus console* - {ProductName} uses Prometheus to store telemetry information from services.
+
+When you install the Service Mesh control plane, it automatically generates routes for each of the installed components. Once you have the route address, you can access the Kiali, Jaeger, Prometheus, or Grafana console to view and manage your service mesh data.
+
+.Prerequisite
+
+* The component must be enabled and installed.  For example, if you did not install distributed tracing, you will not be able to access the Jaeger console.
+
+.Procedure from OpenShift console
+
+. Log in to the {product-title} web console as a user with cluster-admin rights. If you use {product-dedicated}, you must have an account with the `dedicated-admin` role.
+
+. Navigate to *Networking* -> *Routes*.
+
+. On the *Routes* page, select the control plane project, for example `istio-system`, from the *Namespace* menu.
++
+The *Location* column displays the linked address for each route.
++
+. If necessary, use the filter to find the component console whose route you want to access.  Click the route *Location* to launch the console.
+
+. Click *Log In With OpenShift*.
+
+.Procedure from the CLI
+. Log in to the {product-title} CLI as a user with the `cluster-admin` role. If you use Red Hat OpenShift Dedicated, you must have an account with the `dedicated-admin` role.
++
+[source,terminal]
+----
+$ oc login https://{HOSTNAME}:6443
+----
++
+. 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
+----
++
+. To get the routes for the various {ProductName} consoles, run the folowing command:
++
+[source,terminal]
+----
+$ oc get routes
+----
++
+This command returns the URLs for the Kiali, Jaeger, Prometheus, and Grafana web consoles, and any other routes in your service mesh. You should see output similar to the following:
++
+
+[source,terminal]
+----
+NAME                    HOST/PORT                         SERVICES              PORT    TERMINATION
+bookinfo-gateway        bookinfo-gateway-yourcompany.com  istio-ingressgateway          http2
+grafana                 grafana-yourcompany.com           grafana               <all>   reencrypt/Redirect
+istio-ingressgateway    istio-ingress-yourcompany.com     istio-ingressgateway  8080
+jaeger                  jaeger-yourcompany.com            jaeger-query          <all>   reencrypt
+kiali                   kiali-yourcompany.com             kiali                 20001   reencrypt/Redirect
+prometheus              prometheus-yourcompany.com        prometheus            <all>   reencrypt/Redirect
+----
+
+. Copy the URL for the console you want to access from the `HOST/PORT` column into a browser to open the console.
+
+. Click *Log In With OpenShift*.