Merge pull request #83995 from max-cx/OBSDOCS-980

OBSDOCS-980: Add Jaeger deprecation notice and migration recommendations to the DT architecture page

Author: xenolinux

modules/distr-tracing-architecture.adoc

@@ -28,8 +28,25 @@
 ** *OpenTelemetry Collector* - The OpenTelemetry Collector is a vendor-agnostic way to receive, process, and export telemetry data. The OpenTelemetry Collector supports open-source observability data formats, for example, Jaeger and Prometheus, sending to one or more open-source or commercial back-ends. The Collector is the default location instrumentation libraries export their telemetry data.
 
 * *{JaegerName}* - This component is based on the open source link:https://www.jaegertracing.io/[Jaeger project].
++
+:FeatureName: The {JaegerName}
+[IMPORTANT]
+====
+[subs="attributes+"]
+{FeatureName} is a deprecated feature. Deprecated functionality is still included in {product-title} and continues to be supported; however, it will be removed in a future release of this product and is not recommended for new deployments.
 
-** *Client* (Jaeger client, Tracer, Reporter, instrumented application, client libraries)- The {JaegerShortName} 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.
+The {JaegerOperator} Operator (Jaeger) will be removed from the `redhat-operators` catalog in a future release. For more information, see the Red Hat Knowledgebase solution link:https://access.redhat.com/solutions/7083722[Jaeger Deprecation and Removal in OpenShift].
+
+Users must migrate to the {TempoOperator} and the {OTELName} for distributed tracing collection and storage.
+
+ifndef::openshift-rosa,openshift-dedicated[]
+For the most recent list of major functionality that has been deprecated or removed within {product-title}, refer to the _Deprecated and removed features_ section of the {product-title} release notes.
+endif::openshift-rosa,openshift-dedicated[]
+====
+// Undefine {FeatureName} attribute, so that any mistakes are easily spotted
+:!FeatureName:
+
+** *Client* (Jaeger client, Tracer, Reporter, instrumented application, client libraries)- The {JaegerShortName} clients are language-specific implementations of the OpenTracing API. They might 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.
 
 ** *Agent* (Jaeger agent, Server Queue, Processor Workers) - The {JaegerShortName} 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 such as Kubernetes.
 

modules/otel-collector-config-options.adoc

@@ -38,7 +38,7 @@ spec:
     processors: {}
     exporters:
       otlp:
-        endpoint: jaeger-production-collector-headless.tracing-system.svc:4317
+        endpoint: otel-collector-headless.tracing-system.svc:4317
         tls:
           ca_file: "/var/run/secrets/kubernetes.io/serviceaccount/service-ca.crt"
       prometheus:
@@ -50,7 +50,7 @@ spec:
         traces:
           receivers: [otlp]
           processors: []
-          exporters: [jaeger]
+          exporters: [otlp]
         metrics:
           receivers: [otlp]
           processors: []
@@ -85,7 +85,7 @@ spec:
 
 |extensions:
 |Optional components for tasks that do not involve processing telemetry data.
-|`bearertokenauth`, `oauth2client`, `jaegerremotesamplin`, `pprof`, `health_check`, `memory_ballast`, `zpages`
+|`bearertokenauth`, `oauth2client`, `jaegerremotesampling`, `pprof`, `health_check`, `memory_ballast`, `zpages`
 |None
 
 |service:

modules/otel-forwarding-traces.adoc

@@ -113,7 +113,7 @@ spec:
           exporters: [otlp]
 ----
 <1> The Collector exporter is configured to export OTLP and points to the Tempo distributor endpoint, `"tempo-simplest-distributor:4317"` in this example, which is already created.
-<2> The Collector is configured with a receiver for Jaeger traces, OpenCensus traces over the OpenCensus protocol, Zipkin traces over the Zipkin protocol, and OTLP traces over the GRPC protocol.
+<2> The Collector is configured with a receiver for Jaeger traces, OpenCensus traces over the OpenCensus protocol, Zipkin traces over the Zipkin protocol, and OTLP traces over the gRPC protocol.
 
 [TIP]
 ====

observability/distr_tracing/distr-tracing-rn.adoc

@@ -106,7 +106,16 @@ The {JaegerName} 3.4 is supported for use with the {es-op} 5.6, 5.7, and 5.8.
 In the {DTProductName} 3.4, Jaeger and support for Elasticsearch remain deprecated, and both are planned to be removed in a future release.
 Red{nbsp}Hat will provide support for these components and fixes for CVEs and bugs with critical and higher severity during the current release lifecycle, but these components will no longer receive feature enhancements.
 
-The {JaegerOperator} Operator link:https://access.redhat.com/solutions/7083722[is planned to be removed] from the `redhat-operators` catalog in a future release. You must xref:../../observability/otel/otel-migrating.adoc#dist-tracing-otel-migrating[migrate] to the xref:../../observability/distr_tracing/distr_tracing_tempo/distr-tracing-tempo-installing.adoc#dist-tracing-tempo-installing[{TempoOperator}] and the xref:../../observability/otel/otel-installing.adoc#install-otel[{OTELName}] for distributed tracing collection and storage.
+The {JaegerOperator} Operator (Jaeger) will be removed from the `redhat-operators` catalog in a future release. For more information, see the Red Hat Knowledgebase solution link:https://access.redhat.com/solutions/7083722[Jaeger Deprecation and Removal in OpenShift].
+
+You must migrate to the {OTELName} Operator and the {TempoOperator} for distributed tracing collection and storage. For more information, see xref:../../observability/otel/otel-migrating.adoc#dist-tracing-otel-migrating[Migrating] in the {OTELShortName} documentation, xref:../../observability/otel/otel-installing.adoc#install-otel[Installing] in the {OTELName} documentation, and xref:../../observability/distr_tracing/distr_tracing_tempo/distr-tracing-tempo-installing.adoc#dist-tracing-tempo-installing[Installing] in the {TempoShortName} documentation.
+
+[role="_additional-resources"]
+.Additional resources
+* link:https://access.redhat.com/solutions/7083722[Jaeger Deprecation and Removal in OpenShift (Red Hat Knowledgebase)]
+* xref:../../observability/otel/otel-migrating.adoc#dist-tracing-otel-migrating[Migrating ({OTELName} documentation)]
+* xref:../../observability/otel/otel-installing.adoc#install-otel[Installing ({OTELName} documentation)]
+* xref:../../observability/distr_tracing/distr_tracing_tempo/distr-tracing-tempo-installing.adoc#dist-tracing-tempo-installing[Installing (Distributed tracing platform (Tempo) documentation)]
 
 [id="distr-tracing_3-4_jaeger-release-notes_bug-fixes_{context}"]
 ==== Bug fixes
@@ -223,12 +232,8 @@ The {JaegerName} 3.3.1 is supported for use with the {es-op} 5.6, 5.7, and 5.8.
 
 In the {DTProductName} 3.3.1, Jaeger and support for Elasticsearch remain deprecated, and both are planned to be removed in a future release.
 Red{nbsp}Hat will provide support for these components and fixes for CVEs and bugs with critical and higher severity during the current release lifecycle, but these components will no longer receive feature enhancements.
-The {TempoOperator} and the {OTELName} are the preferred Operators for distributed tracing collection and storage.
-Users must adopt the OpenTelemetry and Tempo distributed tracing stack because it is the stack to be enhanced going forward.
 
-In the {DTProductName} 3.3.1, the Jaeger agent is deprecated and planned to be removed in the following release.
-Red{nbsp}Hat will provide bug fixes and support for the Jaeger agent during the current release lifecycle, but the Jaeger agent will no longer receive enhancements and will be removed.
-The OpenTelemetry Collector provided by the {OTELName} is the preferred Operator for injecting the trace collector agent.
+The {JaegerOperator} Operator (Jaeger) link:https://access.redhat.com/solutions/7083722[will be removed] from the `redhat-operators` catalog in a future release. Users must xref:../otel/otel-migrating.adoc#dist-tracing-otel-migrating[migrate] to the xref:distr_tracing_tempo/distr-tracing-tempo-installing.adoc#dist-tracing-tempo-installing[{TempoOperator}] and the xref:../otel/otel-installing.adoc#install-otel[{OTELName}] for distributed tracing collection and storage.
 
 ////
 [id="distr-tracing_3-3-1_jaeger-release-notes_removal-notice_{context}"]
@@ -357,7 +362,7 @@ The {JaegerName} 3.3 is supported for use with the {es-op} 5.6, 5.7, and 5.8.
 In the {DTProductName} 3.3, Jaeger and support for Elasticsearch remain deprecated, and both are planned to be removed in a future release.
 Red{nbsp}Hat will provide support for these components and fixes for CVEs and bugs with critical and higher severity during the current release lifecycle, but these components will no longer receive feature enhancements.
 
-The {JaegerOperator} Operator link:https://access.redhat.com/solutions/7083722[will be removed] from the `redhat-operators` catalog in a future release. Users must xref:../otel/otel-migrating.adoc#dist-tracing-otel-migrating[migrate] to the xref:distr_tracing_tempo/distr-tracing-tempo-installing.adoc#dist-tracing-tempo-installing[{TempoOperator}] and the xref:../otel/otel-installing.adoc#install-otel[{OTELName}] for distributed tracing collection and storage.
+The {JaegerOperator} Operator (Jaeger) link:https://access.redhat.com/solutions/7083722[will be removed] from the `redhat-operators` catalog in a future release. Users must xref:../otel/otel-migrating.adoc#dist-tracing-otel-migrating[migrate] to the xref:distr_tracing_tempo/distr-tracing-tempo-installing.adoc#dist-tracing-tempo-installing[{TempoOperator}] and the xref:../otel/otel-installing.adoc#install-otel[{OTELName}] for distributed tracing collection and storage.
 
 ////
 [id="distr-tracing_3-3_jaeger-release-notes_removal-notice_{context}"]

observability/distr_tracing/distr_tracing_jaeger/distr-tracing-jaeger-configuring.adoc

@@ -7,7 +7,7 @@ include::_attributes/common-attributes.adoc[]
 toc::[]
 
 :FeatureName: The {JaegerName}
-include::modules/deprecated-feature.adoc[]
+include::snippets/distr-tracing-assembly-tip-for-jaeger-replacements.adoc[]
 
 The {JaegerName} Operator uses a custom resource definition (CRD) file that defines the architecture and configuration settings to be used when creating and deploying the {JaegerShortName} resources. You can install the default configuration or modify the file.
 

observability/distr_tracing/distr_tracing_jaeger/distr-tracing-jaeger-installing.adoc

@@ -7,7 +7,7 @@ include::_attributes/common-attributes.adoc[]
 toc::[]
 
 :FeatureName: The {JaegerName}
-include::modules/deprecated-feature.adoc[]
+include::snippets/distr-tracing-assembly-tip-for-jaeger-replacements.adoc[]
 
 You can install {DTProductName} on {product-title} in either of two ways:
 

observability/distr_tracing/distr_tracing_jaeger/distr-tracing-jaeger-removing.adoc

@@ -7,7 +7,7 @@ include::_attributes/common-attributes.adoc[]
 toc::[]
 
 :FeatureName: The {JaegerName}
-include::modules/deprecated-feature.adoc[]
+include::snippets/distr-tracing-assembly-tip-for-jaeger-replacements.adoc[]
 
 The steps for removing {DTProductName} from an {product-title} cluster are as follows:
 

observability/distr_tracing/distr_tracing_jaeger/distr-tracing-jaeger-updating.adoc

@@ -7,7 +7,7 @@ include::_attributes/common-attributes.adoc[]
 toc::[]
 
 :FeatureName: The {JaegerName}
-include::modules/deprecated-feature.adoc[]
+include::snippets/distr-tracing-assembly-tip-for-jaeger-replacements.adoc[]
 
 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}.
 OLM queries for available Operators as well as upgrades for installed Operators.

observability/otel/otel-config-multicluster.adoc

@@ -42,7 +42,7 @@ spec:
   commonName: ca
   subject:
     organizations:
-      - Organization # <your_organization_name>
+      - <your_organization_name>
     organizationalUnits:
       - Widgets
   secretName: ca-secret

snippets/distr-tracing-assembly-tip-for-jaeger-replacements.adoc

@@ -0,0 +1,31 @@
+// Text snippet included in the following assemblies:
+//
+// * distr-tracing-jaeger-configuring.adoc
+// * distr-tracing-jaeger-installing.adoc
+// * distr-tracing-jaeger-removing.adoc
+// * distr-tracing-jaeger-updating.adoc
+// This text is also added inline in one more assembly due to its different xref level:
+// * distr-tracing-rn.adoc
+//   * [id="distr-tracing_3-4_jaeger-release-notes_deprecated-functionality_{context}"]
+//   * [id="distr-tracing_3-3-1_jaeger-release-notes_deprecated-functionality_{context}"]
+//   * [id="distr-tracing_3-3_jaeger-release-notes_support-for-elasticsearch-operator_{context}"]
+// This text is also added inline in one module without xrefs:
+// * modules/distr-tracing-architecture.adoc
+
+:_mod-docs-content-type: SNIPPET
+
+[IMPORTANT]
+====
+[subs="attributes+"]
+{FeatureName} is a deprecated feature. Deprecated functionality is still included in {product-title} and continues to be supported; however, it will be removed in a future release of this product and is not recommended for new deployments.
+
+The {JaegerOperator} Operator (Jaeger) will be removed from the `redhat-operators` catalog in a future release. For more information, see the Red Hat Knowledgebase solution link:https://access.redhat.com/solutions/7083722[Jaeger Deprecation and Removal in OpenShift].
+
+You must migrate to the {OTELName} Operator and the {TempoOperator} for distributed tracing collection and storage. For more information, see "Migrating" in the {OTELShortName} documentation, "Installing" in the {OTELName} documentation, and "Installing" in the {TempoShortName} documentation.
+
+ifndef::openshift-rosa,openshift-dedicated[]
+For the most recent list of major functionality that has been deprecated or removed within {product-title}, refer to the _Deprecated and removed features_ section of the {product-title} release notes.
+endif::openshift-rosa,openshift-dedicated[]
+====
+// Undefine {FeatureName} attribute, so that any mistakes are easily spotted
+:!FeatureName: