[WIP] OSSMDOC-385: Jaeger 1.26 release notes and product name change

_topic_map.yml

@@ -2799,8 +2799,8 @@ Topics:
     File: ossm-troubleshooting-istio
   - Name: Service Mesh configuration reference
     File: ossm-reference-smcp
-  - Name: Jaeger configuration reference
-    File: ossm-reference-jaeger
+  - Name: Distributed tracing configuration reference
+    File: ossm-reference-distributed-tracing
   - Name: Uninstalling Service Mesh
     File: removing-ossm
 - Name: Service Mesh 1.x
@@ -2852,6 +2852,29 @@ Topics:
   - Name: Removing Jaeger
     File: rhbjaeger-removing
 ---
+Name: Distributed Tracing
+Dir: distributed_tracing
+Distros: openshift-enterprise
+Topics:
+- Name: Distributed tracing release notes
+  File: rhos-distributed-tracing-platform-release-notes
+- Name: Platform architecture
+  Dir: distributed_tracing_arch
+  Topics:
+  - Name: Platform architecture
+    File: distributed-tracing-architecture
+- Name: Platform installation
+  Dir: distributed_tracing_install
+  Topics:
+  - Name: Installing platform
+    File: distributed-tracing-installation
+  - Name: Configuring platform
+    File: distributed-tracing-deploying
+  - Name: Upgrading platform
+    File: distributed-tracing-updating
+  - Name: Removing platform
+    File: distributed-tracing-removing
+---
 Name: Virtualization
 Dir: virt
 Distros: openshift-enterprise,openshift-origin

distributed_tracing/distributed_tracing_arch/distributed-tracing-architecture.adoc

@@ -0,0 +1,44 @@
+[id="distributed-tracing-architecture"]
+= Distributed tracing platform architecture
+include::modules/distributed-tracing-document-attributes.adoc[]
+:context: distributed-tracing-architecture
+
+toc::[]
+
+Every time a user takes an action in an application, a request is executed by the architecture that may require dozens of different services to participate to produce a response.
+Red Hat OpenShift distributed tracing platform lets you perform distributed tracing, which records the path of a request through various microservices that make up an application.
+
+_Distributed tracing_ is a technique that is used to tie the information about different units of work together — usually executed in different processes or hosts — to understand a whole chain of events in a distributed transaction.
+Developers can visualize call flows in large microservice architectures with distributed tracing.
+It's valuable for understanding serialization, parallelism, and sources of latency.
+
+Red Hat {ProductName} records the execution of individual requests across the whole stack of microservices, and presents them as traces. A _trace_ is a data/execution path through the system. An end-to-end trace is comprised of one or more spans.
+
+A _span_ represents a logical unit of work in Red Hat {ProductName} that has an operation name, the start time of the operation, and the duration, as well as potentially tags and logs. Spans may be nested and ordered to model causal relationships.
+
+// The following include statements pull in the module files that comprise the assembly.
+
+include::modules/distributed-tracing-product-overview.adoc[leveloffset=+1]
+
+include::modules/distributed-tracing-features.adoc[leveloffset=+1]
+
+include::modules/distributed-tracing-architecture.adoc[leveloffset=+1]
+
+////
+TODO
+WRITE more detailed component docs
+
+include::modules/distributed-tracing-client-java.adoc[leveloffset=+1]
+
+include::modules/distributed-tracing-agent.adoc[leveloffset=+1]
+
+include::modules/distributed-tracing-collector.adoc[leveloffset=+1]
+
+include::modules/distributed-tracing-data-store.adoc[leveloffset=+1]
+
+include::modules/distributed-tracing-query.adoc[leveloffset=+1]
+
+include::modules/distributed-tracing-ingester.adoc[leveloffset=+1]
+
+include::modules/distributed-tracing-console.adoc[leveloffset=+1]
+////

distributed_tracing/distributed_tracing_arch/images

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

distributed_tracing/distributed_tracing_arch/modules

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

distributed_tracing/distributed_tracing_config/modules

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

distributed_tracing/distributed_tracing_install/distributed-tracing-deploying.adoc

@@ -0,0 +1,79 @@
+[id="distributed-tracing-deploying"]
+= Configuring and Deploying {ProductName}
+include::modules/distributed-tracing-document-attributes.adoc[]
+:context: distributed-tracing-deploying
+
+toc::[]
+
+The Red Hat {ProductName} operator uses a custom resource definition (CRD) file that defines the architecture and configuration settings to be used when creating and deploying the {ProductShortName} resources. You can either install the default configuration or modify the file to better suit your business requirements.
+
+{ProductName} has predefined deployment strategies. You specify a deployment strategy in the custom resource file. When you create a {ProductShortName}  instance the operator uses this configuration file to create the objects necessary for the deployment.
+
+.{ProductName} custom resource file showing deployment strategy
+[source,yaml]
+----
+apiVersion: jaegertracing.io/v1
+kind: Jaeger
+metadata:
+  name: simple-prod
+spec:
+  strategy: production <1>
+----
+
+<1> The Red Hat {ProductName} operator currently supports the following deployment strategies:
+
+* *allInOne* (Default) - This strategy is intended for development, testing, and demo purposes; it is not intended for production use. The main backend components, Agent, Collector and Query service, are all packaged into a single executable which is configured (by default) to use in-memory storage.
++
+[NOTE]
+====
+In-memory storage is not persistent, which means that if the {ProductName}  instance shuts down, restarts, or is replaced, that your trace data will be lost.  And in-memory storage cannot be scaled, since each pod has its own memory. For persistent storage, you must use the `production` or `streaming` strategies, which use Elasticsearch as the default storage.
+====
+
+* *production* - The production strategy is intended for production environments, where long term storage of trace data is important, as well as a more scalable and highly available architecture is required. Each of the backend components is therefore deployed separately.  The Agent can be injected as a sidecar on the instrumented application. The Query and Collector services are configured with a supported storage type - currently Elasticsearch. Multiple instances of each of these components can be provisioned as required for performance and resilience purposes.
+
+* *streaming* - The streaming strategy is designed to augment the production strategy by providing a streaming capability that effectively sits between the Collector and the backend storage (Elasticsearch). This provides the benefit of reducing the pressure on the backend storage, under high load situations, and enables other trace post-processing capabilities to tap into the real time span data directly from the streaming platform (https://access.redhat.com/documentation/en-us/red_hat_amq/7.6/html/using_amq_streams_on_openshift/index[AMQ Streams]/ https://kafka.apache.org/documentation/[Kafka]).
++
+[NOTE]
+====
+The streaming strategy requires an additional Red Hat subscription for AMQ Streams.
+====
+
+[NOTE]
+====
+There are two ways to install and use {ProductName}, as part of a service mesh or as a stand alone component. If you have installed {ProductName} as part of Red Hat OpenShift Service Mesh, you can configure and deploy {ProductName} as part of the xref:../../service_mesh/v2x/installing-ossm.adoc#installing-ossm[ServiceMeshControlPlane] or configure {ProductName} and then xref:../../service_mesh/v2x/ossm-observability.html#ossm-config-external-jaeger_observability[reference your Jaeger configuration in the ServiceMeshControlPlane].
+
+====
+
+// The following include statements pull in the module files that comprise the assembly.
+
+include::modules/distributed-tracing-deploy-default.adoc[leveloffset=+1]
+
+include::modules/distributed-tracing-deploy-production-es.adoc[leveloffset=+1]
+
+include::modules/distributed-tracing-deploy-streaming.adoc[leveloffset=+1]
+
+[id="customizing-jaeger-deployment"]
+== Customizing Jaeger deployment
+
+include::modules/distributed-tracing-deployment-best-practices.adoc[leveloffset=+2]
+
+include::modules/distributed-tracing-config-default.adoc[leveloffset=+2]
+
+include::modules/distributed-tracing-config-collector.adoc[leveloffset=+2]
+
+include::modules/distributed-tracing-config-sampling.adoc[leveloffset=+2]
+
+include::modules/distributed-tracing-config-storage.adoc[leveloffset=+2]
+
+include::modules/distributed-tracing-config-query.adoc[leveloffset=+2]
+
+include::modules/distributed-tracing-config-ingester.adoc[leveloffset=+2]
+
+[id="injecting-sidecars"]
+== Injecting sidecars
+
+{ProductName} relies on a proxy sidecar within the application's pod to provide the agent. The {ProductName} operator can inject Jaeger Agent sidecars into Deployment workloads. You can enable automatic sidecar injection or manage it manually.
+
+include::modules/distributed-tracing-sidecar-automatic.adoc[leveloffset=+2]
+
+include::modules/distributed-tracing-sidecar-manual.adoc[leveloffset=+2]

distributed_tracing/distributed_tracing_install/distributed-tracing-installation.adoc

@@ -0,0 +1,42 @@
+[id="installing-distributed-tracing"]
+= Installing {ProductName}
+include::modules/distributed-tracing-document-attributes.adoc[]
+:context: distributed-tracing-install
+
+toc::[]
+
+You can install Red Hat {ProductName} on {product-title} in either of two ways:
+
+* You can install Red Hat {ProductName} as part of Red Hat OpenShift Service Mesh. Distributed tracing platform is included by default in the Service Mesh installation.  To install distributed tracing platform as part of a service mesh, follow the xref:../../service_mesh/v2x/preparing-ossm-installation.adoc#preparing-ossm-installation[Red Hat Service Mesh Installation] instructions. {ProductName} must be installed in the same namespace as your service mesh, that is, the `ServiceMeshControlPlane` and the distributed tracing platform resources must be in the same namespace.
+
+* If you do not want to install a service mesh, you can use the {ProductName}  operator to install {ProductName} by itself.  To install distributed tracing platform without a service mesh, use the following instructions.
+
+== Prerequisites
+
+Before you can install {ProductName}, review the installation activities, and ensure that you meet the prerequisites:
+
+* Possess an active {product-title} subscription on your Red Hat account. If you do not have a subscription, contact your sales representative for more information.
+
+* Review the xref:../../architecture/architecture-installation.adoc#installation-overview_architecture-installation[{product-title} {product-version} overview].
+* Install {product-title} {product-version}.
+
+** xref:../../installing/installing_aws/installing-aws-account.adoc#installing-aws-account[Install {product-title} {product-version} on AWS]
+** xref:../../installing/installing_aws/installing-aws-user-infra.adoc#installing-aws-user-infra[Install {product-title} {product-version} on user-provisioned AWS]
+** xref:../../installing/installing_bare_metal/installing-bare-metal.adoc#installing-bare-metal[Install {product-title} {product-version} on bare metal]
+** xref:../../installing/installing_vsphere/installing-vsphere.adoc#installing-vsphere[Install {product-title} {product-version} on vSphere]
+* Install the version of the OpenShift CLI (`oc`) that matches your {product-title} version and add it to your path.
+
+* An account with the `cluster-admin` role.
+
+// The following include statements pull in the module files that comprise the assembly.
+
+include::modules/distributed-tracing-install-overview.adoc[leveloffset=+1]
+
+include::modules/distributed-tracing-install-elasticsearch.adoc[leveloffset=+1]
+
+include::modules/distributed-tracing-install.adoc[leveloffset=+1]
+
+////
+== Next steps
+* xref:../../jaeger/jaeger_install/rhbj-deploying.adoc#jaeger-deploying[Deploy {ProductName}].
+////

distributed_tracing/distributed_tracing_install/distributed-tracing-removing.adoc

@@ -0,0 +1,27 @@
+[id="removing-distributed-tracing"]
+= Removing {ProductName}
+include::modules/distributed-tracing-document-attributes.adoc[]
+:context: removing-distributed-tracing
+
+toc::[]
+
+The steps for removing {ProductName} from an {product-title} cluster are as follows:
+
+. Shut down any {ProductName} pods.
+. Remove any {ProductName} instances.
+. Remove the {ProductName}  Operator.
+
+include::modules/distributed-tracing-removing-instance.adoc[leveloffset=+1]
+
+include::modules/distributed-tracing-removing-instance-cli.adoc[leveloffset=+1]
+
+
+== Removing the {ProductName} operator
+
+.Procedure
+
+. Follow the instructions for xref:../../operators/admin/olm-deleting-operators-from-cluster.adoc#olm-deleting-operators-from-a-cluster[Deleting Operators from a cluster].
+
+* Remove the {ProductName} operator.
+
+* After the {ProductName} operator has been removed, if appropriate, remove the OpenShift Elasticsearch Operator.

distributed_tracing/distributed_tracing_install/distributed-tracing-updating.adoc

@@ -0,0 +1,14 @@
+[id="upgrading-distributed-tracing"]
+= Upgrading {ProductName}
+include::modules/distributed-tracing-document-attributes.adoc[]
+:context: upgrading-distributed-tracing
+
+toc::[]
+
+The Operator Lifecycle Manager (OLM) controls the installation, upgrade, and role-based access control (RBAC) of Operators in a cluster. The OLM runs by default in {product-title}.
+The OLM queries for available Operators as well as upgrades for installed Operators.
+For more information about how {product-title} handled upgrades, refer to the xref:../../operators/understanding/olm/olm-understanding-olm.adoc#olm-understanding-olm[Operator Lifecycle Manager] documentation.
+
+The update approach used by the {ProductName} operator upgrades the managed {ProductShortName} instances to the version associated with the operator. Whenever a new version of the {ProductName} operator is installed, all the {ProductShortName} application instances managed by the operator will be upgraded to the operator's version. For example, if version 1.10 is installed (both operator and backend components) and the operator is upgraded to version 1.11, then as soon as the operator upgrade has completed, the Operator will scan for running {ProductName} instances and upgrade them to 1.11 as well.
+
+For specific instructions for how to update the OpenShift Elasticsearch Operator, refer to xref:../../logging/cluster-logging-upgrading.adoc#cluster-logging-upgrading_cluster-logging-upgrading[Updating OpenShift Logging].

distributed_tracing/distributed_tracing_install/modules

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

distributed_tracing/images

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

distributed_tracing/modules

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

distributed_tracing/rhos-distributed-tracing-platform-release-notes.adoc

@@ -0,0 +1,22 @@
+[id="distributed-tracing-release-notes"]
+= Distributed tracing release notes
+include::modules/distributed-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/distributed-tracing-product-overview.adoc[leveloffset=+1]
+
+include::modules/making-open-source-more-inclusive.adoc[leveloffset=+1]
+
+include::modules/support.adoc[leveloffset=+1]
+
+include::modules/distributed-tracing-rn-new-features.adoc[leveloffset=+1]
+
+include::modules/distributed-tracing-rn-technology-preview.adoc[leveloffset=+1]
+
+include::modules/distributed-tracing-rn-known-issues.adoc[leveloffset=+1]
+
+include::modules/distributed-tracing-rn-fixed-issues.adoc[leveloffset=+1]

modules/distributed-tracing-architecture.adoc

@@ -0,0 +1,25 @@
+////
+This CONCEPT module included in the following assemblies:
+-service_mesh/v1x/ossm-architecture.adoc
+-service_mesh/v2x/ossm-architecture.adoc
+-rhbjaeger-architecture.adoc
+////
+
+[id="distributed-tracing-architecture_{context}"]
+= {ProductName} architecture
+
+{ProductName} is made up of several components that work together to collect, store, and display tracing data.
+
+* *Jaeger Client* (Tracer, Reporter, instrumented application, client libraries)- Jaeger clients are language specific implementations of the OpenTracing API. They can be used to instrument applications for distributed tracing either manually or with a variety of existing open source frameworks, such as Camel (Fuse), Spring Boot (RHOAR), MicroProfile (RHOAR/Thorntail), Wildfly (EAP), and many more, that are already integrated with OpenTracing.
+
+* *Jaeger Agent* (Server Queue, Processor Workers) - The Jaeger agent is a network daemon that listens for spans sent over User Datagram Protocol (UDP), which it batches and sends to the collector. The agent is meant to be placed on the same host as the instrumented application. This is typically accomplished by having a sidecar in container environments like Kubernetes.
+
+* *Jaeger Collector* (Queue, Workers) - Similar to the Agent, the Collector is able to receive spans and place them in an internal queue for processing. This allows the collector to return immediately to the client/agent instead of waiting for the span to make its way to the storage.
+
+* *Storage* (Data Store) - Collectors require a persistent storage backend. Jaeger has a pluggable mechanism for span storage. Note that for this release, the only supported storage is Elasticsearch.
+
+* *Query* (Query Service) - Query is a service that retrieves traces from storage.
+
+* *Ingester* (Ingester Service) - Jaeger can use Apache Kafka as a buffer between the collector and the actual backing storage (Elasticsearch). Ingester is a service that reads data from Kafka and writes to another storage backend (Elasticsearch).
+
+* *Jaeger Console* – Jaeger provides a user interface that lets you visualize your distributed tracing data. On the Search page, you can find traces and explore details of the spans that make up an individual trace.

modules/distributed-tracing-config-collector.adoc

@@ -0,0 +1,66 @@
+////
+This REFERENCE module included in the following assemblies:
+-distributed-tracing-deploy.adoc
+////
+
+[id="distributed-tracing-config-collector_{context}"]
+= Jaeger Collector configuration options
+
+The Jaeger Collector is the component responsible for receiving the spans that were captured by the tracer and writing them to a persistent storage (Elasticsearch) when using the `production` strategy, or to AMQ Streams when using the `streaming` strategy.
+
+The collectors are stateless and thus many instances of Jaeger Collector can be run in parallel. Collectors require almost no configuration, except for the location of the Elasticsearch cluster.
+
+.Parameters used by the Operator to define the Jaeger Collector
+[options="header"]
+[cols="l, a, a"]
+|===
+|Parameter |Description |Values
+|collector:
+  replicas:
+|Specifies the number of Collector replicas to create.
+|Integer, for example, `5`
+|===
+
+
+.Jaeger parameters passed to the Collector
+[options="header"]
+[cols="l, a, a"]
+|===
+|Parameter |Description |Values
+|spec:
+ collector:
+  options: {}
+|Configuration options that define the Jaeger Collector.
+|
+
+|options:
+  collector:
+    num-workers:
+|The number of workers pulling from the queue.
+|Integer, for example, `50`
+
+|options:
+  collector:
+    queue-size:
+|The size of the Collector queue.
+|Integer, for example, `2000`
+
+|options:
+  kafka:
+    producer:
+      topic: jaeger-spans
+|The `topic` parameter identifies the Kafka configuration used by the collector to produce the messages, and the ingester to consume the messages.
+|Label for the producer
+
+|options:
+  kafka:
+    producer:
+      brokers: my-cluster-kafka-brokers.kafka:9092
+|Identifies the Kafka configuration used by the Collector to produce the messages.  If brokers are not specified, and you have AMQ Streams 1.4.0+ installed, Jaeger will self-provision Kafka.
+|
+
+|options:
+  log-level:
+|Logging level for the collector.
+|`trace`, `debug`, `info`, `warning`, `error`, `fatal`, `panic`
+|===