OSSM 3.0 TP1: OSSM-6974 Distributed tracing content

_topic_maps/_topic_map.yml

@@ -34,6 +34,13 @@ Topics:
 - Name: Using metrics with Service Mesh
   File: ossm-metrics-assembly
 ---
+Name: Distributed tracing
+Dir: traces
+Distros: openshift-service-mesh
+Topics:
+- Name: Configuring distributed tracing with Service Mesh
+  File: ossm-distr-tracing-assembly
+---
 Name: Kiali Operator provided by Red Hat
 Dir: kiali
 Distros: openshift-service-mesh

modules/ossm-config-otel.adoc

@@ -0,0 +1,150 @@
+// Module included in the following assemblies:
+//
+// * service-mesh-docs-main/traces/ossm-distr-tracing-assembly.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="ossm-config-otel_{context}"]
+= Configuring {OTELName} with Service Mesh
+
+You can integrate {SMProductName} with {OTELName} to instrument, generate, collect, and export OpenTelemetry traces, metrics, and logs to analyze and understand your software's performance and behavior.
+
+.Prerequisites
+
+* {TempoOperator} is installed. See: link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.16/html/distributed_tracing/distributed-tracing-platform-tempo#distr-tracing-tempo-install-web-console_dist-tracing-tempo-installing[Installing the Tempo Operator].
+* {OTELOperator} is installed. See: link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.16/html/red_hat_build_of_opentelemetry/install-otel[Installing the Red Hat build of OpenTelemetry]
+* A TempoStack is installed and configured in a `tempo` namespace. See: link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.16/html/distributed_tracing/distributed-tracing-platform-tempo#installing-a-tempostack-instance[Installing a TempoStack instance].
+* An Istio instance is created.
+* An Istio CNI instance is created.
+
+.Procedure
+
+. Navigate to the {OTELOperator} and install the `OpenTelemetryCollector` resource in the `istio-system` namespace:
++
+.Example OpenTelemetry Collector in `istio-system` namespace
+[source, yaml]
+----
+kind: OpenTelemetryCollector
+apiVersion: opentelemetry.io/v1beta1
+metadata:
+  name: otel
+  namespace: istio-system
+spec:
+  observability:
+    metrics: {}
+  deploymentUpdateStrategy: {}
+  config:
+    exporters:
+      otlp:
+        endpoint: 'tempo-sample-distributor.tempo.svc.cluster.local:4317'
+        tls:
+          insecure: true
+    receivers:
+      otlp:
+        protocols:
+          grpc:
+            endpoint: '0.0.0.0:4317'
+          http: {}
+    service:
+      pipelines:
+        traces:
+          exporters:
+            - otlp
+          receivers:
+            - otlp
+----
+
+. Configure {SMProductName} to enable tracing, and define the {OTELShortName} tracing providers in your `meshConfig`:
++
+.Example enabling tracing and defining tracing providers
+[source,yaml]
+----
+apiVersion: sailoperator.io/v1alpha1
+kind: Istio
+metadata:
+#  ...
+  name: default
+spec:
+  namespace: istio-system
+#  ...
+  values:
+    meshConfig:
+      enableTracing: true
+      extensionProviders:
+      - name: otel-tracing
+        opentelemetry:
+          port: 4317
+          service: otel-collector.istio-system.svc.cluster.local # <1>
+----
+<1> The `service` field is the `OpenTelemetry` collector service in the `istio-system` namespace.
+
+. Create an Istio Telemetry resource to enable tracers defined in `spec.values.meshConfig.ExtensionProviders`:
++
+.Example Istio Telemetry resource
+[source,yaml]
+----
+apiVersion: telemetry.istio.io/v1
+kind: Telemetry
+metadata:
+  name: otel-demo
+  namespace: istio-system
+spec:
+  tracing:
+    - providers:
+        - name: otel-tracing
+      randomSamplingPercentage: 100
+----
++
+[NOTE]
+====
+Once you verify that you can see traces, lower the `randomSamplingPercentage` value or set it to `default` to reduce the number of requests.
+====
+
+. Deploy the `bookinfo` application in `bookinfo` namespace:
++
+[source, terminal]
+----
+oc create ns bookinfo
+----
++
+[source, terminal]
+----
+oc label ns <namespace_name> istio.io/rev= # <1>
+----
++
+[source, terminal]
+----
+oc apply -f https://raw.githubusercontent.com/istio/istio/release-1.23/samples/bookinfo/platform/kube/bookinfo.yaml -n bookinfo
+----
+<1> If you named your Istio resource `default` and are using the `InPlace` upgrade strategy, use `oc label ns bookinfo istio-injection=enabled`.
++
+[NOTE]
+====
+To find your `<revision-name>`, run the following command:
+
+[source, terminal]
+----
+oc get istiorevisions.sailoperator.io
+----
+
+.Sample output:
+
+[source,terminal]
+----
+NAME              TYPE    READY   STATUS    IN USE   VERSION   AGE
+default-v1-23-0   Local   True    Healthy   False    v1.23.0   3m33s
+----
+====
+
+. Generate traffic to the `productpage` pod to generate traces:
++
+[source,terminal]
+----
+$ oc exec -it -n bookinfo deployments/productpage-v1 -c istio-proxy -- curl localhost:9080/productpage
+----
+
+. Validate the integration by running the following command to see traces in the UI:
++
+[source,terminal]
+----
+$ kubectl get routes -n tempo tempo-sample-query-frontend
+----

traces/_attributes

@@ -0,0 +1 @@
+../_attributes

traces/docinfo.xml

@@ -0,0 +1,14 @@
+<title>Distributed Tracing</title>
+<productname>OpenShift Service Mesh</productname>
+<productnumber>3.0tp1</productnumber>
+<subtitle>Using distributed tracing with {SMProduct}</subtitle>
+<abstract>
+    <para>This document provides an overview of distributed tracing in {SMProduct}, and how to configure distributed tracing for {SMProductShortName}.
+    </para>
+</abstract>
+<authorgroup>
+    <orgname>Red Hat OpenShift Documentation Team</orgname>
+</authorgroup>
+<xi:include href="Common_Content/Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+<!--Note for Reviewers: this file is needed as part of the mirroring process. It was updated 10/14/2024 because attributes cannot be used.-->

traces/images

@@ -0,0 +1 @@
+../images

traces/modules

@@ -0,0 +1 @@
+../modules

traces/ossm-distr-tracing-assembly.adoc

@@ -0,0 +1,21 @@
+:_content-type: ASSEMBLY
+[id="ossm-distr-tracing-assembly"]
+= Configuring {DTProductName} with Service Mesh
+include::_attributes/common-attributes.adoc[]
+:context: ossm-traces-assembly
+
+toc::[]
+
+Integrating {DTProductName} with {SMProductName} is made of up two parts: {TempoName} and {OTELName}.
+
+{TempoName}:: Provides distributed tracing to monitor and troubleshoot transactions in complex distributed systems. Tempo is based on the open source link:https://grafana.com/oss/tempo/[Grafana Tempo] project.
++
+For more about information about {temposhortname}, its features, installation, and configuration, see: link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.16/html/distributed_tracing/distributed-tracing-platform-tempo[{TempoName}].
+
+{OTELName}:: Is based on the open source link:https://opentelemetry.io/[OpenTelemetry project], which aims to provide unified, standardized, and vendor-neutral telemetry data collection for cloud-native software. {OTELName} product provides support for deploying and managing the OpenTelemetry Collector and simplifying the workload instrumentation.
++
+The link:https://opentelemetry.io/docs/collector/[OpenTelemetry Collector] can receive, process, and forward telemetry data in multiple formats, making it the ideal component for telemetry processing and interoperability between telemetry systems. The Collector provides a unified solution for collecting and processing metrics, traces, and logs.
++
+For more information about {OTELShortName}, its features, installation, and configuration, see: link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.16/html/red_hat_build_of_opentelemetry/index[{OTELName}].
+
+include::modules/ossm-config-otel.adoc[leveloffset=1]

traces/snippets

@@ -0,0 +1 @@
+../snippets