Merge pull request #22090 from abrennan89/tracing

Adding docs on Tracing and Jaeger for Serverless

Author: ahardin-rh

_topic_map.yml

@@ -1476,6 +1476,12 @@ Topics:
     File: rhbjaeger-updating
   - Name: Removing Jaeger
     File: rhbjaeger-removing
+# Integrations / cross-product stories
+- Name: Integrating Jaeger
+  Dir: jaeger_config
+  Topics:
+  - Name: Integrating Jaeger with serverless applications using OpenShift Serverless
+    File: serverless-jaeger-integration
 
 ---
 Name: OpenShift virtualization
@@ -1696,6 +1702,8 @@ Topics:
 # HA
 - Name: Configuring high-availability components
   File: serverless-config-HA
+- Name: Tracing requests
+  File: serverless-tracing
 # Knative CLI
 - Name: Knative CLI
   Dir: knative_cli
@@ -1709,8 +1717,6 @@ Topics:
   - Name: How Knative Serving works
     File: serverless-knative-serving
   ### Knative services
-  - Name: Interacting with serverless applications
-    File: interacting-serverless-apps
   - Name: Configuring Knative Serving autoscaling
     File: configuring-knative-serving-autoscaling
   - Name: Cluster logging with OpenShift Serverless

jaeger/jaeger_config/serverless-jaeger-integration.adoc

@@ -0,0 +1,11 @@
+include::modules/serverless-document-attributes.adoc[]
+[id="serverless-jaeger-integration"]
+= Integrating Jaeger with serverless applications using OpenShift Serverless
+:context: serverless-jaeger-integration
+include::modules/common-attributes.adoc[]
+
+toc::[]
+
+Using Jaeger with xref:../../serverless/serverless-getting-started.adoc#serverless-getting-started[{ServerlessProductName}] allows you to enable distributed tracing for your serverless applications on {product-title}.
+
+include::modules/serverless-jaeger-config.adoc[leveloffset=+1]

modules/interacting-serverless-apps-http2-gRPC.adoc

@@ -1,6 +1,6 @@
 // Module included in the following assemblies:
 //
-// * serverless/interacting-serverless-apps.adoc
+// * serverless/serving-creating-managing-apps.adoc
 
 [id="interacting-serverless-apps-http2-gRPC_{context}"]
 = Interacting with a serverless application using HTTP2 / gRPC

modules/jaeger-install-elasticsearch.adoc

@@ -1,7 +1,6 @@
 // Module included in the following assemblies:
 //
 // - service_mesh/service_mesh_install/installing-ossm.adoc
-// - serverless/installing-openshift-serverless.adoc
 // - rhbjaeger-installation.adoc
 
 

modules/serverless-jaeger-config.adoc

@@ -0,0 +1,65 @@
+// Module included in the following assemblies:
+//
+// * /serverless/serverless-tracing.adoc
+// */jaeger/jaeger_config/serverless-jaeger-integration.adoc
+
+[id="serverless-jaeger-config_{context}"]
+= Configuring Jaeger for use with {ServerlessProductName}
+
+.Prerequisites
+
+To configure Jaeger for use with {ServerlessProductName}, you will need:
+
+* Cluster administrator permissions on an {product-title} cluster.
+* A current installation of {ServerlessOperatorName} and Knative Serving.
+* A current installation of the Jaeger Operator.
+
+.Procedure
+
+. Create and apply the Jaeger custom resource:
++
+----
+$ cat <<EOF | oc apply -f -
+apiVersion: jaegertracing.io/v1
+kind: Jaeger
+metadata:
+  name: jaeger
+  namespace: default
+EOF
+----
+
+. Enable tracing for Knative Serving, by editing the `KnativeServing` resource and adding a YAML configuration for tracing.
++
+.Tracing YAML example
+----
+apiVersion: operator.knative.dev/v1alpha1
+kind: KnativeServing
+metadata:
+  name: knative-serving
+  namespace: knative-serving
+spec:
+  config:
+    tracing:
+      sample-rate: "0.1" <1>
+      backend: zipkin <2>
+      zipkin-endpoint: http://jaeger-collector.default.svc.cluster.local:9411/api/v2/spans <3>
+      debug: "false" <4>
+----
++
+<1> The `sample-rate` defines sampling probability. Using `sample-rate: "0.1"`` means that 1 in 10 traces will be sampled.
+<2> `backend` must be set to `zipkin`.
+<3> The `zipkin-endpoint` must point to your `jaeger-collector` service endpoint. To get this endpoint, substitute the namespace where the Jaeger custom resource is applied.
+<4> Debugging should be set to `false`. Enabling debug mode by setting `debug: "true"` allows all spans to be sent to the server, bypassing sampling.
+
+.Verification  steps
+
+Access the Jaeger web console to see tracing data. You can access the Jaeger web console by using the `jaeger` route.
+
+. Get the `jaeger` route's hostname:
++
+----
+$ oc get route jaeger
+NAME     HOST/PORT                         PATH   SERVICES       PORT    TERMINATION   WILDCARD
+jaeger   jaeger-default.apps.example.com          jaeger-query   <all>   reencrypt     None
+----
+. Open the endpoint address in your browser to view the console.

modules/verifying-serverless-app-deployment.adoc

@@ -1,6 +1,6 @@
 // Module included in the following assemblies:
 //
-// * serverless/interacting-serverless-apps.adoc
+// * serverless/serving-creating-managing-apps.adoc
 
 [id="verifying-serverless-app-deployment_{context}"]
 = Verifying your serverless application deployment

serverless/installing_serverless/upgrading-serverless.adoc

@@ -18,6 +18,6 @@ Before upgrading to the latest Serverless release, you must remove the community
 
 When upgrading from older versions of {ServerlessProductName} to 1.7.0, support for HTTPS requires a change to the format of routes. Knative services created on {ServerlessProductName} 1.6.0 or older versions are no longer reachable at the old format URLs. You must retrieve the new URL for each service after upgrading {ServerlessProductName}.
 
-For more information on retrieving Knative services URLs, see the documentation on xref:../../serverless/knative_serving/interacting-serverless-apps.adoc#interacting-serverless-apps[Interacting with your serverless application].
+For more information on retrieving Knative services URLs, see xref:../../serverless/serving-creating-managing-apps.adoc#serving-creating-managing-apps[Verifying your serverless application deployment].
 
 include::modules/serverless-upgrade-sub-channel.adoc[leveloffset=+1]

serverless/knative_serving/interacting-serverless-apps.adoc

@@ -0,0 +1,21 @@
+include::modules/serverless-document-attributes.adoc[]
+[id="serverless-tracing"]
+= Tracing requests using Jaeger
+:context: serverless-tracing
+include::modules/common-attributes.adoc[]
+
+toc::[]
+
+Using Jaeger with {ServerlessProductName} allows you to enable _distributed tracing_ for your serverless applications on {product-title}.
+
+Distributed tracing records the path of a request through the various services that make up an application.
+
+It is used to tie information about different units of work together, to understand a whole chain of events in a distributed transaction.
+The units of work might be executed in different processes or hosts.
+
+Developers can visualize call flows in large architectures with distributed tracing. which is useful for understanding serialization, parallelism, and sources of latency.
+
+For more information about Jaeger, see xref:../jaeger/jaeger_arch/rhbjaeger-architecture.adoc#rhbjaeger-architecture[Jaeger architecture] and xref:../jaeger/jaeger_install/rhbjaeger-installation.adoc#rhbjaeger-installation[Installing Jaeger].
+
+// Serverless specific modules
+include::modules/serverless-jaeger-config.adoc[leveloffset=+2]

serverless/serverless-tracing.adoc

@@ -20,3 +20,6 @@ For more information about creating applications using the *Developer* perspecti
 
 include::modules/creating-serverless-apps-kn.adoc[leveloffset=+1]
 include::modules/creating-serverless-apps-yaml.adoc[leveloffset=+1]
+
+include::modules/verifying-serverless-app-deployment.adoc[leveloffset=+1]
+include::modules/interacting-serverless-apps-http2-gRPC.adoc[leveloffset=+1]