openshift · JStickler · Feb 4, 2022 · Feb 4, 2022
diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml
@@ -2839,7 +2839,7 @@ Topics:
   - Name: Installing distributed tracing
     File: distr-tracing-installing
   - Name: Configuring the distributed tracing platform
-    File: distr-tracing-deploying
+    File: distr-tracing-deploying-jaeger
   - Name: Configuring distributed tracing data collection
     File: distr-tracing-deploying-otel
   - Name: Upgrading distributed tracing

diff --git a/...cing_install/distr-tracing-deploying.adoc → ...stall/distr-tracing-deploying-jaeger.adoc b/...cing_install/distr-tracing-deploying.adoc → ...stall/distr-tracing-deploying-jaeger.adoc
@@ -2,7 +2,7 @@
 [id="distr-tracing-deploying"]
 = Configuring and deploying distributed tracing
 include::modules/distr-tracing-document-attributes.adoc[]
-:context: deploying-distributed-tracing
+:context: deploying-distr-tracing-platform
 
 toc::[]
 

diff --git a/distr_tracing/distr_tracing_install/distr-tracing-deploying-otel.adoc b/distr_tracing/distr_tracing_install/distr-tracing-deploying-otel.adoc
@@ -2,19 +2,12 @@
 [id="distr-tracing-deploying-otel"]
 = Configuring and deploying distributed tracing data collection
 include::modules/distr-tracing-document-attributes.adoc[]
-:context: deploying-data-collection
+:context: deploying-distr-tracing-data-collection
 
 toc::[]
 
-The {OTELName} Operator uses a custom resource definition (CRD) file that defines the architecture and configuration settings to use when creating and deploying the {OTELShortName} resources. You can either install the default configuration or modify the file to better suit your business requirements.
-
-[IMPORTANT]
-====
-The {OTELName} Operator is a Technology Preview feature only. 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/.
-====
+The {OTELName} Operator uses a custom resource definition (CRD) file that defines the architecture and configuration settings to be used when creating and deploying the {OTELName} resources. You can either install the default configuration or modify the file to better suit your business requirements.
 
 // The following include statements pull in the module files that comprise the assembly.
 
-include::modules/distr-tracing-deploy-otel-collector.adoc[leveloffset=+1]
+include::modules/distr-tracing-config-otel-collector.adoc[leveloffset=+1]
diff --git a/modules/distr-tracing-architecture.adoc b/modules/distr-tracing-architecture.adoc
@@ -3,22 +3,28 @@ This module included in the following assemblies:
 -service_mesh/v2x/ossm-architecture.adoc
 -dist_tracing_arch/distr-tracing-architecture.adoc
 ////
-
+:_content-type: CONCEPT
 [id="distributed-tracing-architecture_{context}"]
 = {DTProductName} architecture
 
 {DTProductName} is made up of several components that work together to collect, store, and display tracing data.
 
-* *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.
+* *{JaegerName}* - This component is based on the open source link:https://www.jaegertracing.io/[Jaeger project].
+
+** *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.
+
+** *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.
+
+** *Jaeger Collector* (Collector, Queue, Workers) - Similar to the Jaeger agent, the Jaeger Collector receives spans and places them in an internal queue for processing. This allows the Jaeger Collector to return immediately to the client/agent instead of waiting for the span to make its way to the storage.
 
-* *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.
+** *Storage* (Data Store) - Collectors require a persistent storage backend. {JaegerName} has a pluggable mechanism for span storage. Note that for this release, the only supported storage is Elasticsearch.
 
-* *Collector* (Jaeger Collector, Queue, Workers) - Similar to the agent, the Collector receives spans and places 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.
+** *Query* (Query Service) - Query is a service that retrieves traces from storage.
 
-* *Storage* (Data Store) - Collectors require a persistent storage backend. {JaegerName} has a pluggable mechanism for span storage. Note that for this release, the only supported storage is Elasticsearch.
+** *Ingester* (Ingester Service) - {DTProductName} can use Apache Kafka as a buffer between the Collector and the actual Elasticsearch backing storage. Ingester is a service that reads data from Kafka and writes to the Elasticsearch storage backend.
 
-* *Query* (Query Service) - Query is a service that retrieves traces from storage.
+** *Jaeger Console* – With the {JaegerName} user interface, you can 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.
 
-* *Ingester* (Ingester Service) - {DTProductName} can use Apache Kafka as a buffer between the Collector and the actual Elasticsearch backing storage. Ingester is a service that reads data from Kafka and writes to the Elasticsearch storage backend.
+* *{OTELName}* - This component is based on the open source link:https://opentelemetry.io/[OpenTelemetry project].
 
-* *Jaeger Console* – With the {JaegerName} user interface, you can 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.
+** *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.
diff --git a/modules/distr-tracing-config-default.adoc b/modules/distr-tracing-config-default.adoc
@@ -1,8 +1,8 @@
 ////
 This module included in the following assemblies:
-- distr_tracing_install/distr-tracing-deploying.adoc
+- distr_tracing_install/distr-tracing-deploying-jaeger.adoc
 ////
-
+:_content-type: REFERENCE
 [id="distr-tracing-config-default_{context}"]
 = Distributed tracing default configuration options
 
@@ -109,10 +109,8 @@ spec:
 |Configuration options that define the Ingester service.
 |
 |
-
 |===
 
-
 The following example YAML is the minimum required to create a {JaegerName} deployment using the default settings.
 
 .Example minimum required dist-tracing-all-in-one.yaml

diff --git a/modules/distr-tracing-config-ingester.adoc b/modules/distr-tracing-config-ingester.adoc
@@ -1,8 +1,8 @@
 ////
 This module included in the following assemblies:
-- distr_tracing_install/distr-tracing-deploying.adoc
+- distr_tracing_install/distr-tracing-deploying-jaeger.adoc
 ////
-
+:_content-type: REFERENCE
 [id="distr-tracing-config-ingester_{context}"]
 = Ingester configuration options
 

diff --git a/modules/distr-tracing-config-jaeger-collector.adoc b/modules/distr-tracing-config-jaeger-collector.adoc
@@ -1,8 +1,8 @@
 ////
 This module included in the following assemblies:
-- distr_tracing_install/distr-tracing-deploying.adoc
+- distr_tracing_install/distr-tracing-deploying-jaeger.adoc
 ////
-
+:_content-type: REFERENCE
 [id="distr-tracing-config-jaeger-collector_{context}"]
 = Jaeger Collector configuration options
 

diff --git a/modules/distr-tracing-config-otel-collector.adoc b/modules/distr-tracing-config-otel-collector.adoc
@@ -1,39 +1,132 @@
 ////
 This module included in the following assemblies:
--distr_tracing_install/distributed-tracing-deploying.adoc
-
-STUB TOPIC for documenting OTEL collector options (Duplicated from Jaeger Collector)
+-distr_tracing_install/distributed-tracing-deploying-otel.adoc
 ////
-
+:_content-type: REFERENCE
 [id="distributed-tracing-config-otel-collector_{context}"]
 = OpenTelemetry Collector configuration options
 
-#TECH PREVIEW BOILERPLATE HERE#
-#What is the actual Operator name?#
+[IMPORTANT]
+====
+The {OTELName} Operator is a Technology Preview feature only. 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/.
+====
+
+The OpenTelemetry Collector consists of three components that access telemetry data:
+
+* *Receivers* - A receiver, which can be push or pull based, is how data gets into the Collector. Generally, a receiver accepts data in a specified format, translates it into the internal format and passes it to processors and exporters defined in the applicable pipelines. By default, no receivers are configured. One or more receivers must be configured. Receivers may support one or more data sources.
+
+* *Processors* - (Optional) Processors are run on data between being received and being exported. By default, no processors are enabled. Processors must be enabled for every data source. Not all processors support all data sources. Depending on the data source, it may be recommended that multiple processors be enabled. In addition, it is important to note that the order of processors matters.
+
+* *Exporters* - An exporter, which can be push or pull based, is how you send data to one or more backends/destinations. By default, no exporters are configured. One or more exporters must be configured.  Exporters may support one or more data sources. Exporters may come with default settings, but many require configuration to specify at least the destination and security settings.
+
+You can define multiple instances of components in a custom resource YAML file. Once configured, these components must be enabled through pipelines defined in the `spec.config.service` section of the YAML file.   As a best practice you should only enable the components that you need.
 
-The OpenTelemetry Collector is the component responsible for receiving the spans that were captured by the tracer and writing them to an Elasticsearch persistent storage when using the `production` strategy, or to AMQ Streams when using the `streaming` strategy.
+.sample OpenTelemetry collector custom resource file
+[source,yaml]
+----
+apiVersion: opentelemetry.io/v1alpha1
+kind: OpenTelemetryCollector
+metadata:
+  name: cluster-collector
+  namespace: tracing-system
+spec:
+  mode: deployment
+  config: |
+    receivers:
+      otlp:
+        protocols:
+          grpc:
+          http:
+    processors:
+    exporters:
+      jaeger:
+        endpoint: jaeger-production-collector-headless.tracing-system.svc:14250
+        tls:
+          ca_file: "/var/run/secrets/kubernetes.io/serviceaccount/service-ca.crt"
+    service:
+      pipelines:
+        traces:
+          receivers: [otlp]
+          processors: []
+          exporters: [jaeger]
+----
 
-The Collectors are stateless and thus many instances of OpenTelemetry Collector can be run in parallel. Collectors require almost no configuration, except for the location of the Elasticsearch cluster.
+[NOTE]
+====
+If a component is configured, but not defined within the `service` section then it is not enabled.
+====
 
 .Parameters used by the Operator to define the OpenTelemetry Collector
 [options="header"]
-[cols="l, a, a"]
+[cols="l, a, a, a"]
 |===
-|Parameter |Description |Values
+|Parameter |Description |Values |Default
+|receivers:
+|A receiver is how data gets into the Collector. By default, no receivers are configured. There must be at least one enabled receiver for a configuration to be considered valid. Receivers are enabled by being added to a pipeline.
+|`otlp`, `jaeger`
+|None
+
+|receivers:
+  otlp:
+|The `oltp` and `jaeger` receivers come with default settings, specifying the name of the receiver is enough to configure it.
 |
 |
+
+|processors:
+|Processors run on data between being received and being exported. By default, no processors are enabled.
 |
-|===
+|None
 
+|exporters:
+|An exporter sends data to one or more backends/destinations. By default, no exporters are configured. There must be at least one enabled exporter for a configuration to be considered valid. Exporters are enabled by being added to a pipeline. Exporters may come with default settings, but many require configuration to specify at least the destination and security settings.
+|`logging`, `jaeger`
+|None
 
-.Parameters passed to the Collector
-[options="header"]
-[cols="l, a, a"]
-|===
-|Parameter |Description |Values
-|spec:
- collector:
-  options: {}
+|exporters:
+ jaeger:
+  endpoint:
+
+|The `jaeger` exporter’s endpoint must be of the form `<name>-collector-headless.<namespace>.svc`, with the name and namespace of the Jaeger deployment, for a secure connection to be established.
 |
 |
+
+|exporters:
+ jaeger:
+  tls:
+   ca_file:
+|Path to the CA certificate. For a client this verifies the server certificate. For a server this verifies client certificates. If empty uses system root CA.
+|
+|
+
+|service:
+  pipelines:
+|Components are enabled by adding them to a pipeline under `services.pipeline`.
+|
+|
+
+|service:
+  pipelines:
+    traces:
+      receivers:
+|You enable receivers for tracing by adding them under `service.pipelines.traces`.
+|
+|None
+
+|service:
+  pipelines:
+    traces:
+      processors:
+|You enable processors for tracing by adding them under `service.pipelines.traces`.
+|
+|None
+
+|service:
+  pipelines:
+    traces:
+      exporters:
+|You enable exporters for tracing by adding them under `service.pipelines.traces`.
+|
+|None
 |===
diff --git a/modules/distr-tracing-config-query.adoc b/modules/distr-tracing-config-query.adoc
@@ -1,8 +1,8 @@
 ////
 This module included in the following assemblies:
-- distr_tracing_install/distr-tracing-deploying.adoc
+- distr_tracing_install/distr-tracing-deploying-jaeger.adoc
 ////
-
+:_content-type: REFERENCE
 [id="distr-tracing-config-query_{context}"]
 = Query configuration options
 
@@ -20,7 +20,6 @@ Query is a service that retrieves traces from storage and hosts the user interfa
 |Specifies the number of Query replicas to create.
 |Integer, for example, `2`
 |
-
 |===
 
 

diff --git a/modules/distr-tracing-config-sampling.adoc b/modules/distr-tracing-config-sampling.adoc
@@ -1,8 +1,8 @@
 ////
 This module included in the following assemblies:
-- distr_tracing_install/distr-tracing-deploying.adoc
+- distr_tracing_install/distr-tracing-deploying-jaeger.adoc
 ////
-
+:_content-type: REFERENCE
 [id="distr-tracing-config-sampling_{context}"]
 = Distributed tracing sampling configuration options
 

diff --git a/modules/distr-tracing-config-storage.adoc b/modules/distr-tracing-config-storage.adoc
@@ -1,8 +1,8 @@
 ////
 This module included in the following assemblies:
-- distr_tracing_install/distr-tracing-deploying.adoc
+- distr_tracing_install/distr-tracing-deploying-jaeger.adoc
 ////
-
+:_content-type: REFERENCE
 [id="distr-tracing-config-storage_{context}"]
 = Distributed tracing storage configuration options
 

diff --git a/modules/distr-tracing-deploy-default.adoc b/modules/distr-tracing-deploy-default.adoc
@@ -1,8 +1,8 @@
 ////
 This module included in the following assemblies:
-- distr_tracing_install/distr-tracing-deploying.adoc
+- distr_tracing_install/distr-tracing-deploying-jaeger.adoc
 ////
-
+:_content-type: PROCEDURE
 [id="distr-tracing-deploy-default_{context}"]
 = Deploying the {DTShortName} default strategy from the web console
 

diff --git a/modules/distr-tracing-deploy-production-es.adoc b/modules/distr-tracing-deploy-production-es.adoc
@@ -1,8 +1,8 @@
 ////
 This module included in the following assemblies:
-- distr_tracing_install/distr-tracing-deploying.adoc
+- distr_tracing_install/distr-tracing-deploying-jaeger.adoc
 ////
-
+:_content-type: PROCEDURE
 [id="distr-tracing-deploy-production_{context}"]
 = Deploying the {DTShortName} production strategy from the web console
 

diff --git a/modules/distr-tracing-deploy-streaming.adoc b/modules/distr-tracing-deploy-streaming.adoc
@@ -1,8 +1,8 @@
 ////
 This module included in the following assemblies:
-- distr_tracing_install/distr-tracing-deploying.adoc
+- distr_tracing_install/distr-tracing-deploying-jaeger.adoc
 ////
-
+:_content-type: PROCEDURE
 [id="distr-tracing-deploy-streaming_{context}"]
 = Deploying the {DTShortName} streaming strategy from the web console
 

diff --git a/modules/distr-tracing-deployment-best-practices.adoc b/modules/distr-tracing-deployment-best-practices.adoc
@@ -1,8 +1,8 @@
 ////
 This module included in the following assemblies:
-- distr_tracing_install/distr-tracing-deploying.adoc
+- distr_tracing_install/distr-tracing-deploying-jaeger.adoc
 ////
-
+:_content-type: CONCEPT
 [id="distr-tracing-deployment-best-practices_{context}"]
 = Deployment best practices
 

diff --git a/modules/distr-tracing-rn-new-features.adoc b/modules/distr-tracing-rn-new-features.adoc
@@ -36,7 +36,7 @@ This release marks the rebranding of Red Hat OpenShift Jaeger to {DTProductName}
 
 ** *{JaegerName}* - This component is based on the open source link:https://www.jaegertracing.io/[Jaeger project].
 
-** *{OTELNAME}* - This component is based on the open source link:https://opentelemetry.io/[OpenTelemetry project].
+** *{OTELName}* - This component is based on the open source link:https://opentelemetry.io/[OpenTelemetry project].
 
 * Updates {JaegerName} Operator to Jaeger 1.28. Going forward, {DTProductName} will only support the `stable` Operator channel. Channels for individual releases are no longer supported.
 

diff --git a/modules/distr-tracing-sidecar-automatic.adoc b/modules/distr-tracing-sidecar-automatic.adoc
@@ -1,8 +1,8 @@
 ////
 This module included in the following assemblies:
-- distr_tracing_install/distr-tracing-deploying.adoc
+- distr_tracing_install/distr-tracing-deploying-jaeger.adoc
 ////
-
+:_content-type: REFERENCE
 [id="dist-tracing-sidecar-automatic_{context}"]
 = Automatically injecting sidecars
 

diff --git a/modules/distr-tracing-sidecar-manual.adoc b/modules/distr-tracing-sidecar-manual.adoc
@@ -1,8 +1,8 @@
 ////
 This module included in the following assemblies:
-- distr_tracing_install/distr-tracing-deploying.adoc
+- distr_tracing_install/distr-tracing-deploying-jaeger.adoc
 ////
-
+:_content-type: REFERENCE
 [id="distr-tracing-sidecar-manual_{context}"]
 = Manually injecting sidecars