[enterprise 4.6] OSSMDOC-385: Distributed tracing Release Notes.

_topic_map.yml

@@ -2407,28 +2407,29 @@ Topics:
     File: threescale-adapter
   - Name: Removing Service Mesh
     File: removing-ossm
+
 ---
-Name: Jaeger
+Name: Distributed tracing
 Dir: jaeger
 Distros: openshift-enterprise
 Topics:
-- Name: Jaeger release notes
-  File: rhbjaeger-release-notes
-- Name: Jaeger architecture
+- Name: Distributed tracing release notes
+  File: distributed-tracing-release-notes
+- Name: Distributed tracing architecture
   Dir: jaeger_arch
   Topics:
-  - Name: Jaeger architecture
+  - Name: Distributed tracing architecture
     File: rhbjaeger-architecture
-- Name: Jaeger installation
+- Name: Distributed tracing installation
   Dir: jaeger_install
   Topics:
-  - Name: Installing Jaeger
+  - Name: Installing distributed tracing
     File: rhbjaeger-installation
-  - Name: Configuring Jaeger
+  - Name: Configuring distributed tracing
     File: rhbjaeger-deploying
-  - Name: Upgrading Jaeger
+  - Name: Upgrading distributed tracing
     File: rhbjaeger-updating
-  - Name: Removing Jaeger
+  - Name: Removing distributed tracing
     File: rhbjaeger-removing
 ---
 Name: OpenShift Virtualization

jaeger/distributed-tracing-release-notes.adoc

@@ -0,0 +1,22 @@
+[id="distr-tracing-release-notes"]
+= Distributed tracing release notes
+include::modules/distr-tracing-document-attributes.adoc[]
+:context: distributed-tracing-release-notes
+
+toc::[]
+
+// The following include statements pull in the module files that comprise the assembly.
+
+include::modules/distr-tracing-product-overview.adoc[leveloffset=+1]
+
+include::modules/making-open-source-more-inclusive.adoc[leveloffset=+1]
+
+include::modules/support.adoc[leveloffset=+1]
+
+include::modules/distr-tracing-rn-new-features.adoc[leveloffset=+1]
+
+include::modules/distr-tracing-rn-technology-preview.adoc[leveloffset=+1]
+
+include::modules/distr-tracing-rn-known-issues.adoc[leveloffset=+1]
+
+include::modules/distr-tracing-rn-fixed-issues.adoc[leveloffset=+1]

modules/distr-tracing-document-attributes.adoc

@@ -0,0 +1,39 @@
+// Standard document attributes to be used in the distributed tracing documentation
+//
+// The following are shared by all RH Build of distributed tracing documents:
+:toc:
+:toclevels: 4
+:toc-title:
+:experimental:
+//
+// Product content attributes, that is, substitution variables in the files.
+//
+:product-title: OpenShift Container Platform
+:ProductName: Red Hat OpenShift distributed tracing
+:ProductShortName: distributed tracing
+:ProductRelease:
+:ProductVersion: 2.0
+:product-build:
+:DownloadURL: registry.redhat.io
+:cloud-redhat-com: Red Hat OpenShift Cluster Manager
+:kebab: image:kebab.png[title="Options menu"]
+//
+// Documentation publishing attributes used in the master-docinfo.xml file
+// Note that the DocInfoProductName generates the URL for the product page.
+// Changing the value changes the generated URL.
+//
+
+:DocInfoProductName: Red Hat OpenShift distributed tracing
+:DocInfoProductName: OpenShift distributed tracing
+:DocInfoProductNumber: 2.0
+//
+// Book Names:
+// Defining the book names in document attributes instead of hard-coding them in
+// the master.adoc files and in link references.
+//This makes it easy to change the book name if necessary.
+// Using the pattern ending in 'BookName' makes it easy to grep for occurrences
+// throughout the topics
+//
+:RN_BookName: Red Hat OpenShift distributed tracing Release Notes
+:Install_BookName: Installing Red Hat OpenShift distributed tracing
+:Using_BookName: Using Red Hat Red Hat OpenShift distributed tracing

modules/distr-tracing-product-overview.adoc

@@ -0,0 +1,27 @@
+////
+This CONCEPT module included in the following assemblies:
+-service_mesh/v2x/ossm-architecture.adoc ??
+-distr-tracing-architecture.adoc
+////
+
+[id="distr-tracing-product-overview_{context}"]
+= OpenShift distributed tracing overview
+
+As a service owner, you can use distributed tracing to instrument your services to gather insights into your service architecture.
+You can use distributed tracing for monitoring, network profiling, and troubleshooting the interaction between components in modern, cloud-native, microservices-based applications.
+
+Using distributed tracing lets you perform the following functions:
+
+* Monitor distributed transactions
+
+* Optimize performance and latency
+
+* Perform root cause analysis
+
+{ProductName} consists of two components:
+
+* *Red Hat OpenShift distributed tracing platform* - This component is based on the open source link:https://www.jaegertracing.io/[Jaeger project].
+
+* *Red Hat OpenShift distributed tracing data collection* - This component is based on the open source link:https://opentelemetry.io/[OpenTelemetry project].
+
+Both of these components are based on the vendor-neutral link:https://opentracing.io/[OpenTracing] APIs and instrumentation.

modules/distr-tracing-rn-fixed-issues.adoc

@@ -0,0 +1,29 @@
+////
+Module included in the following assemblies:
+* distr-tracing-release-notes.adoc
+* service_mesh/v2x/servicemesh-release-notes.adoc
+////
+
+[id="distr-tracing-rn-fixed-issues_{context}"]
+= Distributed tracing fixed issues
+////
+Provide the following info for each issue if possible:
+Consequence - What user action or situation would make this problem appear  (If you have the foo option enabled and did x)? What did the customer experience as a result of the issue? What was the symptom?
+Cause - Why did this happen?
+Fix - What did we change to fix the problem?
+Result - How has the behavior changed as a result?  Try to avoid “It is fixed” or “The issue is resolved” or “The error no longer presents”.
+////
+
+* link:https://issues.redhat.com/browse/TRACING-2009[TRACING-2009] The Jaeger Operator has been updated to include support for the Strimzi Kafka Operator 0.23.0.
+
+* link:https://issues.redhat.com/browse/TRACING-1907[TRACING-1907] The Jaeger agent sidecar injection was failing due to missing config maps in the application namespace. The config maps were getting automatically deleted due to an incorrect `OwnerReference` field setting, and as a result, the application pods were not moving past the "ContainerCreating" stage. The incorrect settings have been removed.
+
+* link:https://issues.redhat.com/browse/TRACING-1725[TRACING-1725] Follow-up to TRACING-1631. Additional fix to ensure that Elasticsearch certificates are properly reconciled when there are multiple Jaeger production instances, using same name but within different namespaces. See also link:https://bugzilla.redhat.com/show_bug.cgi?id=1918920[BZ-1918920].
+
+* link:https://issues.jboss.org/browse/TRACING-1631[TRACING-1631] Multiple Jaeger production instances, using same name but within different namespaces, causing Elasticsearch certificate issue. When multiple service meshes were installed, all of the Jaeger Elasticsearch instances had the same Elasticsearch secret instead of individual secrets, which prevented the OpenShift Elasticsearch Operator from communicating with all of the Elasticsearch clusters.
+
+* link:https://issues.redhat.com/browse/TRACING-1300[TRACING-1300] Failed connection between Agent and Collector when using Istio sidecar. An update of the Jaeger Operator enabled TLS communication by default between a Jaeger sidecar agent and the Jaeger Collector.
+
+* link:https://issues.redhat.com/browse/TRACING-1208[TRACING-1208] Authentication "500 Internal Error" when accessing Jaeger UI. When trying to authenticate to the UI using OAuth, you get a 500 error because the oauth-proxy sidecar does not trust the custom CA bundle defined at installation time with the `additionalTrustBundle`. This was due to the config map with the  `additionalTrustBundle` not being created in the Jaeger namespace.
+
+* link:https://issues.redhat.com/browse/TRACING-1166[TRACING-1166] It is not currently possible to use the Jaeger streaming strategy within a disconnected environment. When a Kafka cluster is being provisioned, it results in a error: `Failed to pull image registry.redhat.io/amq7/amq-streams-kafka-24-rhel7@sha256:f9ceca004f1b7dccb3b82d9a8027961f9fe4104e0ed69752c0bdd8078b4a1076`.

modules/distr-tracing-rn-known-issues.adoc

@@ -0,0 +1,34 @@
+////
+Module included in the following assemblies:
+* service_mesh/v2x/servicemesh-release-notes.adoc
+* distr-tracing--release-notes.adoc
+////
+
+[id="distr-tracing-rn-known-issues_{context}"]
+= Distributed tracing known issues
+
+////
+Consequence - What user action or situation would make this problem appear (Selecting the Foo option with the Bar version 1.3 plugin enabled results in an error message)? What did the customer experience as a result of the issue? What was the symptom?
+Cause (if it has been identified) - Why did this happen?
+Workaround (If there is one)- What can you do to avoid or negate the effects of this issue in the meantime? Sometimes if there is no workaround it is worthwhile telling readers to contact support for advice. Never promise future fixes.
+Result - If the workaround does not completely address the problem.
+////
+
+The following limitations exist in Red Hat OpenShift distributed tracing platform:
+
+* Apache Spark is not supported.
+
+* Jaeger streaming via AMQ/Kafka is unsupported on IBM Z and IBM Power Systems.
+
+These are the known issues in Red Hat OpenShift distributed tracing platform:
+
+* link:https://issues.redhat.com/browse/TRACING-2057[TRACING-2057] The Kafka API has been updated to `v1beta2` to support the Strimzi Kafka Operator 0.23.0.  However, this API version is not supported by AMQ Streams 1.6.3. If you have the following environment, your Jaeger services does not upgrade, and you cannot create new Jaeger services or modify existing Jaeger services:
+
+** Jaeger Operator channel: *1.17.x stable* or *1.20.x stable*
+** AMQ Streams Operator channel: *amq-streams-1.6.x*
++
+To resolve this issue, switch the subscription channel for your AMQ Streams Operator to either *amq-streams-1.7.x* or *stable*.
+
+* link:https://bugzilla.redhat.com/show_bug.cgi?id=1918920[BZ-1918920] The Elasticsearch pods do not get restarted automatically after an update. As a workaround, restart the pods manually.
+
+* link:https://issues.redhat.com/browse/TRACING-809[TRACING-809] Jaeger Ingester is incompatible with Kafka 2.3. When there are two or more instances of the Jaeger Ingester and enough traffic, the Ingester generates continuous rebalancing messages in the logs. The Ingester generates these logs because of a regression in Kafka 2.3. This regression was fixed in Kafka 2.3.1. For more information, see https://github.com/jaegertracing/jaeger/issues/1819[Jaegertracing-1819].

modules/distr-tracing-rn-new-features.adoc

@@ -0,0 +1,38 @@
+////
+Module included in the following assemblies:
+* distr-tracing--release-notes.adoc
+////
+////
+Feature – Describe the new functionality available to the customer. For enhancements, try to describe as specifically as possible where the customer will see changes.
+Reason – If known, include why has the enhancement been implemented (use case, performance, technology, etc.). For example, showcases integration of X with Y, demonstrates Z API feature, includes latest framework bug fixes.
+Result – If changed, describe the current user experience.
+////
+
+[id="distr-tracing-rn-new-features_{context}"]
+== New features and enhancements {ProductName} 2.0.0
+
+This release marks the rebranding of Red Hat OpenShift Jaeger to {ProductName}.  This effort includes the following:
+
+* Updates {ProductShortName} Operator to Jaeger 1.28.  Going forward, {ProductName} will only support the `stable` Operator channel. Channels for individual releases are no longer supported.
+
+* Introduces a new OpenTelemetry Operator based on OpenTelemetry 0.33.  Note that this Operator is a Technology Preview.
+
+* Adds support for OpenTelemetry protocol (OTLP) to the Query service.
+
+* Introduces a new distributed tracing icon that appears in the OpenShift OperatorHub.
+
+* Includes rolling updates to the documentation to support the name change and new features.
+
+This release also addresses Common Vulnerabilities and Exposures (CVEs) and bug fixes.
+
+== Component versions supported in {ProductName} version {ProductVersion}
+
+|===
+|Component |Version
+
+|Jaeger
+|1.28.0
+
+|OpenTelemetry
+|0.33.0
+|===

modules/distr-tracing-rn-technology-preview.adoc

@@ -0,0 +1,26 @@
+////
+Module included in the following assemblies:
+* distr-tracing--release-notes.adoc
+////
+
+[id="distr-tracing-rn-tech-preview_{context}"]
+= Technology Preview
+////
+Provide the following info for each issue if possible:
+Description -  Describe the new functionality available to the customer.  For enhancements, try to describe as specifically as possible where the customer will see changes.  Avoid the word “supports” as in [product] now supports [feature] to avoid customer confusion with full support.  Say, for example, “available as a Technology Preview.”
+Package - A brief description of what the customer has to install or enable to use the Technology Preview feature.    (e.g., available in quickstart.zip on customer portal, JDF website, container on registry, enable option, etc.)
+////
+
+[IMPORTANT]
+====
+Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production.
+These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process. For more information about the support scope of Red Hat Technology Preview features, see https://access.redhat.com/support/offerings/techpreview/.
+====
+
+== {ProductName} 2.0.0 Technology Preview
+
+This release includes the addition of the distributed tracing data collection, which you install using the OpenTelemetry Operator.
+
+{ProductName} data collection is based on the OpenTelemetry Operator and Collector. The Collector can be used to receive traces in either the OpenTelemetry or Jaeger protocol and send the trace data to the OpenShift distributed tracing platform. Other capabilities of the Collector are not supported at this time.
+
+The OpenTelemetry collector allows developers to instrument their code with vendor agnostic APIs, avoiding vendor lock-in and enabling a growing ecosystem of observability tooling.

modules/making-open-source-more-inclusive.adoc

@@ -0,0 +1,6 @@
+:_module-type: CONCEPT
+
+[id="making-open-source-more-inclusive_{context}"]
+= Making open source more inclusive
+
+Red Hat is committed to replacing problematic language in our code, documentation, and web properties. We are beginning with these four terms: master, slave, blacklist, and whitelist. Because of the enormity of this endeavor, these changes will be implemented gradually over several upcoming releases. For more details, see link:https://www.redhat.com/en/blog/making-open-source-more-inclusive-eradicating-problematic-language[our CTO Chris Wright's message].

service_mesh/v2x/servicemesh-release-notes.adoc

@@ -19,8 +19,8 @@ include::modules/ossm-rn-deprecated-features.adoc[leveloffset=+1]
 
 include::modules/ossm-rn-known-issues.adoc[leveloffset=+1]
 
-include::modules/jaeger-rn-known-issues.adoc[leveloffset=+2]
+include::modules/distr-tracing-rn-known-issues.adoc[leveloffset=+2]
 
 include::modules/ossm-rn-fixed-issues.adoc[leveloffset=+1]
 
-include::modules/jaeger-rn-fixed-issues.adoc[leveloffset=+2]
+include::modules/distr-tracing-rn-fixed-issues.adoc[leveloffset=+2]