Skip to content

Commit 526ec22

Browse files
JSticklerJStickler
committed
OSSMDOC-288: Rebranding Jaeger to distributed tracing.
1 parent 1a31cd7 commit 526ec22

File tree

52 files changed

+2367
-74
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

52 files changed

+2367
-74
lines changed

‎_topic_maps/_topic_map.yml‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -2783,27 +2783,27 @@ Topics:
27832783

27842784
---
27852785
Name: Distributed tracing
2786-
Dir: jaeger
2786+
Dir: distr_tracing
27872787
Distros: openshift-enterprise
27882788
Topics:
27892789
- Name: Distributed tracing release notes
27902790
File: distributed-tracing-release-notes
27912791
- Name: Distributed tracing architecture
2792-
Dir: jaeger_arch
2792+
Dir: distr_tracing_arch
27932793
Topics:
27942794
- Name: Distributed tracing architecture
2795-
File: rhbjaeger-architecture
2795+
File: distr-tracing-architecture
27962796
- Name: Distributed tracing installation
2797-
Dir: jaeger_install
2797+
Dir: distr_tracing_install
27982798
Topics:
27992799
- Name: Installing distributed tracing
2800-
File: rhbjaeger-installation
2800+
File: distr-tracing-installing
28012801
- Name: Configuring distributed tracing
2802-
File: rhbjaeger-deploying
2802+
File: distr-tracing-deploying
28032803
- Name: Upgrading distributed tracing
2804-
File: rhbjaeger-updating
2804+
File: distr-tracing-updating
28052805
- Name: Removing distributed tracing
2806-
File: rhbjaeger-removing
2806+
File: distr-tracing-removing
28072807
---
28082808
Name: Virtualization
28092809
Dir: virt

‎distr_tracing/distr_tracing_arch/distr-tracing-architecture.adoc‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
[id="distr-tracing-architecture"]
2+
= Distributed tracing architecture
3+
include::modules/distr-tracing-document-attributes.adoc[]
4+
:context: distributed-tracing-architecture
5+
6+
toc::[]
7+
8+
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.
9+
{DTProductName} lets you perform distributed tracing, which records the path of a request through various microservices that make up an application.
10+
11+
_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.
12+
Developers can visualize call flows in large microservice architectures with distributed tracing.
13+
It is valuable for understanding serialization, parallelism, and sources of latency.
14+
15+
{DTProductName} 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.
16+
17+
A _span_ represents a logical unit of work in {DTProductName} 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.
18+
19+
// The following include statements pull in the module files that comprise the assembly.
20+
21+
include::modules/distr-tracing-product-overview.adoc[leveloffset=+1]
22+
23+
include::modules/distr-tracing-features.adoc[leveloffset=+1]
24+
25+
include::modules/distr-tracing-architecture.adoc[leveloffset=+1]
26+
27+
////
28+
TODO
29+
WRITE more detailed component docs
30+
31+
include::modules/distr-tracing-client-java.adoc[leveloffset=+1]
32+
33+
include::modules/distr-tracing-agent.adoc[leveloffset=+1]
34+
35+
include::modules/distr-tracing--jaeger-collector.adoc[leveloffset=+1]
36+
37+
include::modules/distr-tracing-otel-collector.adoc[leveloffset=+1]
38+
39+
include::modules/distr-tracing-data-store.adoc[leveloffset=+1]
40+
41+
include::modules/distr-tracing-query.adoc[leveloffset=+1]
42+
43+
include::modules/distr-tracing-ingester.adoc[leveloffset=+1]
44+
45+
include::modules/distr-tracing-console.adoc[leveloffset=+1]
46+
////

‎distr_tracing/distr_tracing_arch/images‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../images/

‎distr_tracing/distr_tracing_arch/modules‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../modules/

‎distr_tracing/distr_tracing_config/images‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../images/

‎distr_tracing/distr_tracing_config/modules‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../modules/

‎distr_tracing/distr_tracing_config/serverless-jaeger-integration.adoc‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
include::modules/serverless-document-attributes.adoc[]
2+
[id="serverless-jaeger-integration"]
3+
= Integrating distributed tracing with serverless applications using OpenShift Serverless
4+
:context: serverless-jaeger-integration
5+
include::modules/common-attributes.adoc[]
6+
7+
toc::[]
8+
9+
You can enable distributed tracing with xref:../../serverless/serverless-getting-started.adoc#serverless-getting-started[{ServerlessProductName}] for your serverless applications on {product-title}.
10+
11+
include::modules/serverless-jaeger-config.adoc[leveloffset=+1]

‎distr_tracing/distr_tracing_install/distr-tracing-deploying.adoc‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
[id="distr-tracing-deploying"]
2+
= Configuring and deploying distributed tracing
3+
include::modules/distr-tracing-document-attributes.adoc[]
4+
:context: deploying-distributed-tracing
5+
6+
toc::[]
7+
8+
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 either install the default configuration or modify the file to better suit your business requirements.
9+
10+
{JaegerName} has predefined deployment strategies. You specify a deployment strategy in the custom resource file. When you create a {JaegerShortName} instance the Operator uses this configuration file to create the objects necessary for the deployment.
11+
12+
.Jaeger custom resource file showing deployment strategy
13+
[source,yaml]
14+
----
15+
apiVersion: jaegertracing.io/v1
16+
kind: Jaeger
17+
metadata:
18+
name: MyConfigFile
19+
spec:
20+
strategy: production <1>
21+
----
22+
23+
<1> The {JaegerName} Operator currently supports the following deployment strategies:
24+
25+
* *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.
26+
+
27+
[NOTE]
28+
====
29+
In-memory storage is not persistent, which means that if the {JaegerShortName} 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.
30+
====
31+
32+
* *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.
33+
34+
* *streaming* - The streaming strategy is designed to augment the production strategy by providing a streaming capability that effectively sits between the Collector and the Elasticsearch backend storage. 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]).
35+
+
36+
[NOTE]
37+
====
38+
The streaming strategy requires an additional Red Hat subscription for AMQ Streams.
39+
====
40+
41+
[NOTE]
42+
====
43+
The streaming deployment strategy is currently unsupported on IBM Z.
44+
====
45+
46+
[NOTE]
47+
====
48+
There are two ways to install and use {DTProductName}, as part of a service mesh or as a stand alone component. If you have installed {DTShortName} as part of Red Hat OpenShift Service Mesh, you can perform basic configuration as part of the xref:../../service_mesh/v2x/installing-ossm.adoc#installing-ossm[ServiceMeshControlPlane] but for completely control you should configure a Jaeger CR and then xref:../../service_mesh/v2x/ossm-observability.html#ossm-config-external-jaeger_observability[reference your distributed tracing configuration file in the ServiceMeshControlPlane].
49+
50+
====
51+
52+
// The following include statements pull in the module files that comprise the assembly.
53+
54+
include::modules/distr-tracing-deploy-default.adoc[leveloffset=+1]
55+
56+
include::modules/distr-tracing-deploy-production-es.adoc[leveloffset=+1]
57+
58+
include::modules/distr-tracing-deploy-streaming.adoc[leveloffset=+1]
59+
60+
[id="customizing-your-deployment"]
61+
== Customizing your deployment
62+
63+
include::modules/distr-tracing-deployment-best-practices.adoc[leveloffset=+2]
64+
65+
include::modules/distr-tracing-config-default.adoc[leveloffset=+2]
66+
67+
include::modules/distr-tracing-config-jaeger-collector.adoc[leveloffset=+2]
68+
69+
//include::modules/distr-tracing-config-otel-collector.adoc[leveloffset=+2]
70+
71+
include::modules/distr-tracing-config-sampling.adoc[leveloffset=+2]
72+
73+
include::modules/distr-tracing-config-storage.adoc[leveloffset=+2]
74+
75+
include::modules/distr-tracing-config-query.adoc[leveloffset=+2]
76+
77+
include::modules/distr-tracing-config-ingester.adoc[leveloffset=+2]
78+
79+
[id="injecting-sidecars"]
80+
== Injecting sidecars
81+
82+
{JaegerName} relies on a proxy sidecar within the application's pod to provide the agent. The {JaegerName} Operator can inject Agent sidecars into Deployment workloads. You can enable automatic sidecar injection or manage it manually.
83+
84+
include::modules/distr-tracing-sidecar-automatic.adoc[leveloffset=+2]
85+
86+
include::modules/distr-tracing-sidecar-manual.adoc[leveloffset=+2]

‎distr_tracing/distr_tracing_install/distr-tracing-installing.adoc‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
[id="installing-distributed-tracing"]
2+
= Installing distributed tracing
3+
include::modules/distr-tracing-document-attributes.adoc[]
4+
:context: install-distributed-tracing
5+
6+
toc::[]
7+
8+
You can install {DTProductName} on {product-title} in either of two ways:
9+
10+
* You can install {DTProductName} as part of Red Hat OpenShift Service Mesh. Distributed tracing is included by default in the Service Mesh installation. To install {DTProductName} 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 must install {DTProductName} in the same namespace as your service mesh, that is, the `ServiceMeshControlPlane` and the {DTProductName} resources must be in the same namespace.
11+
12+
* If you do not want to install a service mesh, you can use the {DTProductName} Operators to install {DTShortName} by itself. To install {DTProductName} without a service mesh, use the following instructions.
13+
14+
== Prerequisites
15+
16+
Before you can install {DTProductName}, review the installation activities, and ensure that you meet the prerequisites:
17+
18+
* 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.
19+
20+
* Review the xref:../../architecture/architecture-installation.adoc#installation-overview_architecture-installation[{product-title} {product-version} overview].
21+
* Install {product-title} {product-version}.
22+
23+
** xref:../../installing/installing_aws/installing-aws-account.adoc#installing-aws-account[Install {product-title} {product-version} on AWS]
24+
** xref:../../installing/installing_aws/installing-aws-user-infra.adoc#installing-aws-user-infra[Install {product-title} {product-version} on user-provisioned AWS]
25+
** xref:../../installing/installing_bare_metal/installing-bare-metal.adoc#installing-bare-metal[Install {product-title} {product-version} on bare metal]
26+
** xref:../../installing/installing_vsphere/installing-vsphere.adoc#installing-vsphere[Install {product-title} {product-version} on vSphere]
27+
* Install the version of the OpenShift CLI (`oc`) that matches your {product-title} version and add it to your path.
28+
29+
* An account with the `cluster-admin` role.
30+
31+
// The following include statements pull in the module files that comprise the assembly.
32+
33+
include::modules/distr-tracing-install-overview.adoc[leveloffset=+1]
34+
35+
include::modules/distr-tracing-install-elasticsearch.adoc[leveloffset=+1]
36+
37+
include::modules/distr-tracing-install-jaeger-operator.adoc[leveloffset=+1]
38+
39+
////
40+
== Next steps
41+
* xref:../../distr_tracing/distr_tracing_install/distr-tracing-deploying.adoc#deploying-distributed-tracing[Deploy {DTProductName}].
42+
////

‎distr_tracing/distr_tracing_install/distr-tracing-removing.adoc‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
[id="removing-distributed-tracing"]
2+
= Removing distributed tracing
3+
include::modules/distr-tracing-document-attributes.adoc[]
4+
:context: removing-distributed-tracing
5+
6+
toc::[]
7+
8+
The steps for removing {DTProductName} from an {product-title} cluster are as follows:
9+
10+
. Shut down any {DTProductName} pods.
11+
. Remove any {DTProductName} instances.
12+
. Remove the {JaegerName} Operator.
13+
. Remove the {OTELName} Operator.
14+
15+
include::modules/distr-tracing-removing-instance.adoc[leveloffset=+1]
16+
17+
include::modules/distr-tracing-removing-instance-cli.adoc[leveloffset=+1]
18+
19+
20+
== Removing the {DTProductName} Operators
21+
22+
.Procedure
23+
24+
. Follow the instructions for xref:../../operators/admin/olm-deleting-operators-from-cluster.adoc#olm-deleting-operators-from-a-cluster[Deleting Operators from a cluster].
25+
26+
* Remove the {JaegerName} Operator.
27+
28+
//* Remove the {OTELName} Operator.
29+
30+
* After the {JaegerName} Operator has been removed, if appropriate, remove the OpenShift Elasticsearch Operator.

0 commit comments

Comments
 (0)