diff --git a/jaeger/jaeger_install/rhbjaeger-deploying.adoc b/jaeger/jaeger_install/rhbjaeger-deploying.adoc index 195f3772d449..8588ac735597 100644 --- a/jaeger/jaeger_install/rhbjaeger-deploying.adoc +++ b/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] diff --git a/jaeger/jaeger_install/rhbjaeger-installation.adoc b/jaeger/jaeger_install/rhbjaeger-installation.adoc index 749e204ea5a1..6b9f004a9c80 100644 --- a/jaeger/jaeger_install/rhbjaeger-installation.adoc +++ b/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 diff --git a/modules/jaeger-config-collector.adoc b/modules/jaeger-config-collector.adoc index bb043409da3b..00abbb298902 100644 --- a/modules/jaeger-config-collector.adoc +++ b/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: diff --git a/modules/jaeger-config-ingester.adoc b/modules/jaeger-config-ingester.adoc index 6b78486240c8..6e80177478c6 100644 --- a/modules/jaeger-config-ingester.adoc +++ b/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: diff --git a/modules/jaeger-config-query.adoc b/modules/jaeger-config-query.adoc index d6cfa8596274..81ccf4b4a7df 100644 --- a/modules/jaeger-config-query.adoc +++ b/modules/jaeger-config-query.adoc @@ -8,7 +8,7 @@ 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"] |=== @@ -16,35 +16,39 @@ Query is a service that retrieves traces from storage and hosts the user interfa |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 diff --git a/modules/jaeger-config-sampling.adoc b/modules/jaeger-config-sampling.adoc index 4bc10a8adb4e..a1c0a66fb50d 100644 --- a/modules/jaeger-config-sampling.adoc +++ b/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 ---- diff --git a/modules/jaeger-config-storage.adoc b/modules/jaeger-config-storage.adoc index e9153459ac3a..2f07da14e61d 100644 --- a/modules/jaeger-config-storage.adoc +++ b/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 diff --git a/modules/jaeger-deployment-best-practices.adoc b/modules/jaeger-deployment-best-practices.adoc new file mode 100644 index 000000000000..d6748089240c --- /dev/null +++ b/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. diff --git a/modules/jaeger-document-attributes.adoc b/modules/jaeger-document-attributes.adoc index cad28a40e7d5..7dfe3bc608ed 100644 --- a/modules/jaeger-document-attributes.adoc +++ b/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 diff --git a/modules/ossm-configuring-external-jaeger.adoc b/modules/ossm-configuring-external-jaeger.adoc new file mode 100644 index 000000000000..788e80b37787 --- /dev/null +++ b/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. diff --git a/modules/ossm-configuring-jaeger.adoc b/modules/ossm-configuring-jaeger.adoc index 18d54f2cd3ed..7e81c7b4c957 100644 --- a/modules/ossm-configuring-jaeger.adoc +++ b/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. diff --git a/modules/ossm-cr-example.adoc b/modules/ossm-cr-example.adoc index 52a596c34c8c..2b8c8737ec2c 100644 --- a/modules/ossm-cr-example.adoc +++ b/modules/ossm-cr-example.adoc @@ -74,8 +74,8 @@ spec: policy: type: Istiod # or Mixer mixer: # only applies if policy.type: Mixer - enableChecks: false - failOpen: false + enableChecks: false + failOpen: false telemetry: type: Istiod # or Mixer @@ -92,15 +92,15 @@ spec: addons: grafana: enabled: true - install: + install: config: - env: {} - envSecrets: {} + env: {} + envSecrets: {} persistence: storageClassName: "" accessMode: ReadWriteOnce - capacity: 5Gi - service: + capacity: 5Gi + service: ingress: contextPath: /grafana tls: @@ -114,14 +114,14 @@ spec: enableGrafana: true enableTracing: true enablePrometheus: true - service: + service: ingress: contextPath: /kiali jaeger: name: jaeger install: storage: - type: Memory # or Elasticsearch + type: Elasticsearch # or Memory memory: maxTraces: 100000 elasticsearch: @@ -159,20 +159,20 @@ The following table lists the parameters for the `ServiceMeshControlPlane` resou |APIVersion defines the versioned schema of this representation of an object. Servers convert recognized schemas to the latest internal value, and may reject unrecognized values. The value for {ProductName} version 2.0 is `maistra.io/v2`. |The value for {ProductName} version 2.0 is maistra.io/v2. -|kind +|`kind` |Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. |Not configurable -|metadata +|`metadata` |Metadata about this `ServiceMeshControlPlane` instance You can provide a name for your control plane installation to keep track of your work, for example, `basic-install`, or `production`. |string -|spec +|`spec` |The specification of the desired state of this `ServiceMeshControlPlane`. This includes the configuration options for all components that comprise the control plane. |For more information, see Table 2. -|status -|The current status of this `ServiceMeshControlPlane` and the components that comprise the control plane. +|`status` +|The current status of this `ServiceMeshControlPlane` and the components that comprise the control plane. |For more information, see Table 3. |=== @@ -207,7 +207,7 @@ The following table lists the specifications for the `ServiceMeshControlPlane` r |`default` |`proxy` -| You use the `proxy` parameter to configure the default behavior for sidecars. +| You use the `proxy` parameter to configure the default behavior for sidecars. |`accessLogging`, `adminPort`, `concurrency`, and `envoyMetricsService` |`runtime` diff --git a/modules/ossm-cr-mixer.adoc b/modules/ossm-cr-mixer.adoc index 42e6b0f9e3e1..2c3b93f023ef 100644 --- a/modules/ossm-cr-mixer.adoc +++ b/modules/ossm-cr-mixer.adoc @@ -55,7 +55,7 @@ mixer: |=== |Type |Parameter |Description |Values |Default -|Requests +|`requests` |`cpu` |The percentage of CPU resources requested for Mixer telemetry. |CPU resources in millicores based on your environment's configuration. @@ -67,7 +67,7 @@ mixer: |Available memory in bytes (for example, 200Ki, 50Mi, 5Gi) based on your environment’s configuration. |`128Mi` -|Limits +|`limits` |`cpu` |The maximum percentage of CPU resources Mixer telemetry is permitted to use. |CPU resources in millicores based on your environment's configuration. diff --git a/modules/ossm-enabling-jaeger.adoc b/modules/ossm-enabling-jaeger.adoc index 62158186f25d..2ee058bf536c 100644 --- a/modules/ossm-enabling-jaeger.adoc +++ b/modules/ossm-enabling-jaeger.adoc @@ -24,4 +24,4 @@ spec: Currently the only tracing type that is supported is `Jaeger`. Jaeger is enabled by default. To disable tracing, set `type` to `None`. -The sampling rate determines how often a trace is generated. You configure `sampling` as a scaled integer representing 0.01% increments. For example setting the value to `1` samples 0.01% of traces and a setting of `10000` samples 100% of traces. +The sampling rate determines how often a trace is generated. You configure `sampling` as a scaled integer representing 0.01% increments. For example, setting the value to `10` samples 0.1% of traces, setting the value to `500` samples 5% of traces, and a setting of `10000` samples 100% of traces. diff --git a/modules/ossm-jaeger-service-mesh.adoc b/modules/ossm-jaeger-service-mesh.adoc index 63be1c044f3f..8609d2fd9c26 100644 --- a/modules/ossm-jaeger-service-mesh.adoc +++ b/modules/ossm-jaeger-service-mesh.adoc @@ -12,7 +12,7 @@ Installing Jaeger with the Service Mesh on {product-title} differs from communit * Jaeger has been enabled by default for {ProductShortName}. * Ingress has been enabled by default for {ProductShortName}. * The name for the Zipkin port name has changed to `jaeger-collector-zipkin` (from `http`) -* Jaeger uses Elasticsearch for storage by default. -* The community version of Istio provides a generic "tracing" route. {ProductName} uses a "jaeger" route that is installed by the Jaeger operator and is already protected by OAuth. +* Jaeger uses Elasticsearch for storage by default when you select either the `production` or `streaming` deployment option. +* The community version of Istio provides a generic "tracing" route. {ProductName} uses a "jaeger" route that is installed by the Jaeger Operator and is already protected by OAuth. * {ProductName} uses a sidecar for the Envoy proxy, and Jaeger also uses a sidecar, for the Jaeger agent. These two sidecars are configured separately and should not be confused with each other. The proxy sidecar creates spans related to the pod's ingress and egress traffic. The agent sidecar receives the spans emitted by the application and sends them to the Jaeger Collector. diff --git a/modules/ossm-tutorial-jaeger-generating-traces.adoc b/modules/ossm-tutorial-jaeger-generating-traces.adoc index ef031440842a..0cc0b83f397f 100644 --- a/modules/ossm-tutorial-jaeger-generating-traces.adoc +++ b/modules/ossm-tutorial-jaeger-generating-traces.adoc @@ -34,7 +34,7 @@ This tutorial uses {ProductShortName} and the Bookinfo tutorial to demonstrate h .. Use the CLI to query for details of the route: + ---- -$ export JAEGER_URL=$(oc get route -n bookinfo jaeger-query -o jsonpath='{.spec.host}') +$ export JAEGER_URL=$(oc get route -n istio-system jaeger-query -o jsonpath='{.spec.host}') ---- + . Launch a browser and navigate to `https://`. diff --git a/service_mesh/v2x/ossm-custom-resources.adoc b/service_mesh/v2x/ossm-custom-resources.adoc index 79c42f939381..e49f67ef1ce1 100644 --- a/service_mesh/v2x/ossm-custom-resources.adoc +++ b/service_mesh/v2x/ossm-custom-resources.adoc @@ -37,6 +37,8 @@ include::modules/ossm-enabling-jaeger.adoc[leveloffset=+2] include::modules/ossm-configuring-jaeger.adoc[leveloffset=+2] +include::modules/ossm-configuring-external-jaeger.adoc[leveloffset=+2] + For example Jaeger resources, see xref:../../jaeger/jaeger_install/rhbjaeger-deploying.adoc[Configuring and deploying Jaeger]. include::modules/ossm-deploying-jaeger.adoc[leveloffset=+2] @@ -45,4 +47,6 @@ For more detailed information about customizing your Jaeger configuration, see For more information about configuring Elasticsearch with {product-title}, see xref:../../logging/config/cluster-logging-log-store.adoc[Configuring the log store] or xref:../../jaeger/jaeger_install/rhbjaeger-deploying.adoc[Configuring and deploying Jaeger]. +For information about connecting to an external Elasticsearch instance, see xref:../../jaeger/jaeger_install/rhbjaeger-deploying.adoc#jaeger-config-external-es_jaeger-deploying[Connecting to an existing Elasticsearch instance]. + include::modules/ossm-cr-threescale.adoc[leveloffset=+1]