OSSMDOC169 Update CR configuring Jaeger.

jaeger/jaeger_install/rhbjaeger-deploying.adoc

@@ -48,13 +48,15 @@ There are two ways to install and use Jaeger, as part of a service mesh or as a
 
 include::modules/jaeger-deploy-default.adoc[leveloffset=+1]
 
-include::modules/jaeger-deploy-production-es.adoc[leveloffset=1]
+include::modules/jaeger-deploy-production-es.adoc[leveloffset=+1]
 
-include::modules/jaeger-deploy-streaming.adoc[leveloffset=1]
+include::modules/jaeger-deploy-streaming.adoc[leveloffset=+1]
 
 [id="customizing-jaeger-deployment"]
 == Customizing Jaeger deployment
 
+include::modules/jaeger-deployment-best-practices.adoc[leveloffset=+2]
+
 include::modules/jaeger-config-default.adoc[leveloffset=+2]
 
 include::modules/jaeger-config-collector.adoc[leveloffset=+2]
@@ -72,6 +74,6 @@ include::modules/jaeger-config-ingester.adoc[leveloffset=+2]
 
 {ProductName} relies on a proxy sidecar within the application’s pod to provide the agent. The Jaeger Operator can inject Jaeger Agent sidecars into Deployment workloads. You can enable automatic sidecar injection or manage it manually.
 
-include::modules/jaeger-sidecar-automatic.adoc[leveloffset=2]
+include::modules/jaeger-sidecar-automatic.adoc[leveloffset=+2]
 
-include::modules/jaeger-sidecar-manual.adoc[leveloffset=2]
+include::modules/jaeger-sidecar-manual.adoc[leveloffset=+2]

jaeger/jaeger_install/rhbjaeger-installation.adoc

@@ -7,9 +7,9 @@ toc::[]
 
 You can install Jaeger on {product-title} in either of two ways:
 
-* You can install Jaeger as part of Red Hat OpenShift Service Mesh. Jaeger is included by default in the Service Mesh installation.  To install Jaeger 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.
+* You can install Jaeger as part of Red Hat OpenShift Service Mesh. Jaeger is included by default in the Service Mesh installation.  To install Jaeger 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.  Jaeger must be installed in the same namespace as your service mesh, that is, the `ServiceMeshControlPlane` and the Jaeger resources must be in the same namespace.
 
-* If you do not want to install a service mesh, you can use the Jaeger Operator to install the Red Hat build of Jaeger by itself.  To install Jaeger without a service mesh, use the following instructions.
+* If you do not want to install a service mesh, you can use the Jaeger Operator to install {ProductName} by itself.  To install Jaeger without a service mesh, use the following instructions.
 
 
 == Prerequisites

modules/jaeger-config-collector.adoc

@@ -10,21 +10,11 @@ The Jaeger Collector is the component responsible for receiving the spans that w
 
 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.
 
-.Jaeger Collector parameters used by the Operator
+.Parameters used by the Operator to define the Jaeger Collector
 [options="header"]
 [cols="l, a, a"]
 |===
 |Parameter |Description |Values
-|collector:
-  num-workers:
-|The number of workers pulling from the queue.
-|Integer, for example, `50`
-
-|collector:
-  queue-size:
-|The size of the Collector queue.
-|Integer, for example, `2000`
-
 |collector:
   replicas:
 |Specifies the number of Collector replicas to create.
@@ -43,6 +33,18 @@ The collectors are stateless and thus many instances of Jaeger Collector can be
 |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:

modules/jaeger-config-ingester.adoc

@@ -8,31 +8,23 @@ This REFERENCE module included in the following assemblies:
 
 Ingester is a service that reads from a Kafka topic and writes to another storage backend (Elasticsearch).  If you are using the `allInOne` or `production` deployment strategies, you do not need to configure the Ingester service.
 
-.Jaeger Ingester parameters used by the Operator
-[options="header"]
-[cols="l, a, a"]
-|===
-|Parameter |Description |Values
-|ingester:
-  deadlockInterval:
-| Specifies the interval (in seconds or minutes) that the Ingester should wait for a message before terminating.
-The deadlock interval is disabled by default (set to 0), to avoid the Ingester being terminated when no messages arrive while the system is being initialized.
-|Minutes and seconds, for example, `1m0s`.  Default value is `0`.
-|===
-
-
 .Jaeger parameters passed to the Ingester
 [options="header"]
 [cols="l, a, a"]
 |===
 |Parameter |Description |Values
 |spec:
-  strategy: streaming
   ingester:
     options: {}
 |Configuration options that define the Ingester service.
 |
 
+|options:
+  deadlockInterval:
+|Specifies the interval (in seconds or minutes) that the Ingester should wait for a message before terminating.
+The deadlock interval is disabled by default (set to 0), to avoid the Ingester being terminated when no messages arrive while the system is being initialized.
+|Minutes and seconds, for example, `1m0s`.  Default value is `0`.
+
 |options:
   kafka:
     consumer:

modules/jaeger-config-query.adoc

@@ -8,43 +8,47 @@ This REFERENCE module included in the following assemblies:
 
 Query is a service that retrieves traces from storage and hosts the user interface to display them.
 
-.Jaeger Query parameters
+.Parameters used by the Operator to define Jaeger Query
 [options="header"]
 [cols="l, a, a, a"]
 |===
 |Parameter |Description |Values |Default value
 
 |spec:
   query:
-   options: {}
-   resources: {}
-|Configuration options that define the Query service.
-|
+    replicas:
+|Specifies the number of Query replicas to create.
+|Integer, for example, `2`
 |
 
-|query:
-  additional-headers:
-|Additional HTTP response headers. Can be specified multiple times.
-|Format: "Key: Value"
-|
+|===
 
-|query:
-  base-path:
-|The base path for all jaeger-query HTTP routes can be set to a non-root value, for example, `/jaeger` would cause all UI URLs to start with `/jaeger`. This can be useful when running jaeger-query behind a reverse proxy.
-|/{path}
-|
 
-|query:
-  port:
-|The port for the query service.
+.Jaeger parameters passed to Query
+[options="header"]
+[cols="l, a, a, a"]
+|===
+|Parameter |Description |Values |Default value
+
+|spec:
+  query:
+    options: {}
+|Configuration options that define the Query service.
+|
 |
-|16686
 
 |options:
   log-level:
 |Logging level for Query.
 |Possible values: `trace`, `debug`, `info`, `warning`, `error`, `fatal`, `panic`.
 |
+
+|options:
+  query:
+    base-path:
+|The base path for all jaeger-query HTTP routes can be set to a non-root value, for example, `/jaeger` would cause all UI URLs to start with `/jaeger`. This can be useful when running jaeger-query behind a reverse proxy.
+|/{path}
+|
 |===
 
 .Sample Query configuration

modules/jaeger-config-sampling.adoc

@@ -19,40 +19,39 @@ When a service receives a request that contains no trace context, the Jaeger tra
 
 Jaeger libraries support the following samplers:
 
-* *Constant* - The sampler always makes the same decision for all traces. It either samples all traces (sampling.param=1) or none of them (sampling.param=0).
-
 * *Probabilistic* - The sampler makes a random sampling decision with the probability of sampling equal to the value of the `sampling.param` property. For example, with sampling.param=0.1 approximately 1 in 10 traces will be sampled.
 
 * *Rate Limiting* - The sampler uses a leaky bucket rate limiter to ensure that traces are sampled with a certain constant rate. For example, when sampling.param=2.0 it will sample requests with the rate of 2 traces per second.
 
-* *Remote* - The sampler consults the Jaeger agent for the appropriate sampling strategy to use in the current service. This allows controlling the sampling strategies in the services from a central configuration in the Jaeger backend.
-
-.Jaeger sampling parameters
+.Jaeger sampling options
 [options="header"]
 [cols="l, a, a, a"]
 |===
 |Parameter |Description |Values |Default value
-
 |spec:
  sampling:
   options: {}
+    default_strategy:
+    service_strategy:
 |Configuration options that define the sampling strategies for tracing.
 |
-|
+|If you do not provide configuration, the collectors will return the default probabilistic sampling policy with probability 0.001 (0.1%) for all services.
 
-|sampling:
+|default_strategy:
+  type:
+service_strategy:
   type:
 |Sampling strategy to use. (See descriptions above.)
-|Valid values are `const`, `probabilistic`, `ratelimiting`, and `remote`.
-|`remote`
-
-|sampling:
-  options:
-    type:
-    param:
-|Parameters for the selected sampling strategy. (See examples above.)
+|Valid values are `probabilistic`, and `ratelimiting`.
+|`probabilistic`
+
+|default_strategy:
+  param:
+service_strategy:
+  param:
+|Parameters for the selected sampling strategy.
 |Decimal and integer values (0, .1, 1, 10)
-|N/A
+|1
 |===
 
 This example defines a default sampling strategy that is probabilistic, with a 50% chance of the trace instances being sampled.
@@ -65,11 +64,36 @@ kind: Jaeger
 metadata:
   name: with-sampling
 spec:
-  strategy: allInOne
   sampling:
     options:
       default_strategy:
         type: probabilistic
-        param: 50
+        param: 0.5
+      service_strategies:
+        - service: alpha
+          type: probabilistic
+          param: 0.8
+          operation_strategies:
+            - operation: op1
+              type: probabilistic
+              param: 0.2
+            - operation: op2
+              type: probabilistic
+              param: 0.4
+        - service: beta
+          type: ratelimiting
+          param: 5
+----
+
+If there are no user-supplied configurations, Jaeger uses the following settings.
 
+.default sampling
+[source,yaml]
+----
+spec:
+  sampling:
+    options:
+      default_strategy:
+        type: probabilistic
+        param: 1
 ----

modules/jaeger-config-storage.adoc

@@ -8,20 +8,15 @@ This REFERENCE module included in the following assemblies:
 
 You configure storage for the Collector, Ingester, and Query services under `spec:storage`. Multiple instances of each of these components can be provisioned as required for performance and resilience purposes.
 
-.Jaeger general storage parameters
+.General storage parameters used by the Operator to define Jaeger storage
+
 [options="header"]
 [cols="l, a, a, a"]
 |===
 |Parameter |Description |Values |Default value
 |spec:
- storage:
-  options: {}
-|Configuration options that define the storage.
-|
-|
-
-|storage:
-  type:
+  storage:
+    type:
 |Type of storage to use for the deployment.
 |`memory` or `elasticsearch`.
 Memory storage is only appropriate for development, testing, demonstrations, and proof of concept environments as the data does not persist if the pod is shut down. For production environments Jaeger supports Elasticsearch for persistent storage.
@@ -32,6 +27,12 @@ Memory storage is only appropriate for development, testing, demonstrations, and
 |Name of the secret, for example `jaeger-secret`.
 |
 |N/A
+
+|storage:
+  options: {}
+|Configuration options that define the storage.
+|
+|
 |===
 
 .Elasticsearch index cleaner parameters

modules/jaeger-deployment-best-practices.adoc

@@ -0,0 +1,15 @@
+////
+This module included in the following assemblies:
+*  /jaeger/jaeger_install/rhbjaeger-deploying.adoc
+////
+
+[id="jager-deployment-best-practices_{context}"]
+= Deployment best practices
+:pantheon-module-type: CONCEPT
+
+
+* Jaeger instance names must be unique. If you want to have multiple Jaeger instances and are using sidecar injected Jaeger agents, then the Jaeger instances should have unique names, and the injection annotation should explicitly specify the Jaeger instance name the tracing data should be reported to.
+
+* If you have a multitenant implementation and tenants are separated by namespaces, deploy a Jaeger instance to each tenant namespace.
+
+* If you are installing Jaeger as part of Red Hat OpenShift Service Mesh, Jaeger resources must be installed in the same namespace as the `ServiceMeshControlPlane` resource.

modules/jaeger-document-attributes.adoc

@@ -12,7 +12,7 @@
 :ProductName: OpenShift Jaeger
 :ProductShortName: Jaeger
 :ProductRelease:
-:ProductVersion: 1.20.0
+:ProductVersion: 1.20.3
 :product-build:
 :DownloadURL: registry.redhat.io
 :cloud-redhat-com: Red Hat OpenShift Cluster Manager
@@ -25,7 +25,7 @@
 
 :DocInfoProductName: Red Hat OpenShift Jaeger
 :DocInfoProductName: OpenShift Jaeger
-:DocInfoProductNumber: 1.20.0
+:DocInfoProductNumber: 1.20.3
 //
 // Book Names:
 // Defining the book names in document attributes instead of hard-coding them in

modules/ossm-configuring-external-jaeger.adoc

@@ -0,0 +1,9 @@
+// Module included in the following assemblies:
+//
+// * service_mesh/v2x/customizing-installation-ossm.adoc
+
+
+[id="ossm-specifying-external-jaeger_{context}"]
+= Specifying an external Jaeger
+
+You can configure and deploy a standalone Jaeger instance and then specify the `name` of the Jaeger resource as the value for `spec.addons.jaeger.name` in the `ServiceMeshControlPlane` resource.  If a Jaeger resource matching the value of `name` exists, the control plane will use the existing installation.  This approach lets you fully customize your Jaeger configuration.

modules/ossm-configuring-jaeger.adoc

@@ -4,12 +4,8 @@
 
 
 [id="ossm-specifying-jaeger-configuration_{context}"]
-= Specifying Jaeger Configuration
+= Specifying Jaeger configuration in the SMCP
 
 You configure Jaeger under the `addons` section of `ServiceMeshControlPlane` resource.
 
-You can specify your Jaeger configuration in either of two ways:
-
-* Specify the Jaeger configuration in the `ServiceMeshControlPlane` resource under `spec.addons.jaeger.install`.  There are some limitations with this approach.  For example, you cannot configure a `streaming` deployment strategy via the control plane.
-
-* Configure and deploy a Jaeger instance and then specify the `name` of the Jaeger resource as the value for `spec.addons.jaeger.name` in the `ServiceMeshControlPlane` resource.  If a Jaeger resource matching the value of `name` exists, the control plane will use the existing installation.  This approach lets you fully customize your Jaeger configuration.
+You can specify your Jaeger configuration in the `ServiceMeshControlPlane` resource under `spec.addons.jaeger.install`.  There are some limitations with this approach.  For example, you cannot configure a `streaming` deployment strategy via the control plane.