diff --git a/src/main/pages/che-7/administration-guide/assembly_installing-the-jaeger-tracing-tool.adoc b/src/main/pages/che-7/administration-guide/assembly_installing-the-jaeger-tracing-tool.adoc new file mode 100644 index 0000000000..fd9a50a574 --- /dev/null +++ b/src/main/pages/che-7/administration-guide/assembly_installing-the-jaeger-tracing-tool.adoc @@ -0,0 +1,30 @@ +// tracing-che + +[id="installing-the-jaeger-tracing-tool_{context}"] += Installing the Jaeger tracing tool + +:context: installing-the-jaeger-tracing-tool + +The following sections describe the installation methods for the Jaeger tracing tool. Jaeger can then be used for gathering metrics in {prod-short}. + +Installation methods available: + +* xref:installing-the-jaeger-tracing-tool-for-che-on-openshift-4_installing-the-jaeger-tracing-tool[] +* xref:installing-jaeger-using-operatorhub-on-openshift-4_installing-the-jaeger-tracing-tool[] +* xref:installing-jaeger-locally-using-a-pre-built-container-image_installing-the-jaeger-tracing-tool[] + +For tracing a {prod-short} instance using Jaeger, version 1.12.0 or above is required. For additional information about Jaeger, see the link:https://www.jaegertracing.io/docs/latest/[Jaeger website]. + +include::proc_installing-the-jaeger-tracing-tool-for-che-on-openshift-4.adoc[leveloffset=+1] + +include::proc_installing-jaeger-using-operatorhub-on-openshift-4.adoc[leveloffset=+1] + +include::proc_installing-jaeger-locally-using-a-pre-built-container-image.adoc[leveloffset=+1] + +//// +.Additional resources + +* A bulleted list of links to other material closely related to the contents of the assembly, including xref links to other assemblies in your collection. +* For more details on writing assemblies, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide]. +* Use a consistent system for file names, IDs, and titles. For tips, see _Anchor Names and File Names_ in link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide]. +//// diff --git a/src/main/pages/che-7/administration-guide/assembly_tracing-che.adoc b/src/main/pages/che-7/administration-guide/assembly_tracing-che.adoc index 1e100ff0a4..4f40959b81 100644 --- a/src/main/pages/che-7/administration-guide/assembly_tracing-che.adoc +++ b/src/main/pages/che-7/administration-guide/assembly_tracing-che.adoc @@ -29,6 +29,7 @@ Tracers live in applications. They record timing and metadata about operations t By default, {prod-short} uses Jaeger as the tracing backend. Jaeger was inspired by Dapper and OpenZipkin, and it is a distributed tracing system released as open source by Uber Technologies. Jaeger extends a more complex architecture for a larger scale of requests and performance. +include::assembly_installing-the-jaeger-tracing-tool.adoc[leveloffset=+1] include::proc_enabling-che-metrics-collections.adoc[leveloffset=+1] diff --git a/src/main/pages/che-7/administration-guide/proc_enabling-che-metrics-collections.adoc b/src/main/pages/che-7/administration-guide/proc_enabling-che-metrics-collections.adoc index b587c9434c..246f5fc181 100644 --- a/src/main/pages/che-7/administration-guide/proc_enabling-che-metrics-collections.adoc +++ b/src/main/pages/che-7/administration-guide/proc_enabling-che-metrics-collections.adoc @@ -3,11 +3,11 @@ .Prerequisites -* Installed Jaeger v1.12.0 or above. See instructions at link:https://www.jaegertracing.io/docs/1.12/getting-started/[Get up and running with Jaeger in your local environment]. +* Installed Jaeger v1.12.0 or above. See instructions at xref:installing-the-jaeger-tracing-tool_tracing-che[] .Procedure -. Enable the following environment variables for {prod-short} deployment: +For Jaeger tracing to work, enable the following environment variables in your {prod-short} deployment: + [source,bash] ---- @@ -31,6 +31,34 @@ JAEGER_SAMPLER_PARAM="1" JAEGER_REPORTER_MAX_QUEUE_SIZE="10000" ---- -.Additional resources +To enable the following environment variables: + +. In the `yaml` source code of the {prod-short} deployment, add the following configuration variables under `spec.server.customCheProperties`. ++ +[source,yaml] +---- +customCheProperties: + CHE_TRACING_ENABLED: 'true' + JAEGER_SAMPLER_TYPE: const + DEFAULT_JAEGER_REPORTER_MAX_QUEUE_SIZE: '10000' + JAEGER_SERVICE_NAME: che-server + JAEGER_ENDPOINT: 'http://jaeger-collector:14268/api/traces' + JAEGER_SAMPLER_MANAGER_HOST_PORT: 'jaeger:5778' + JAEGER_SAMPLER_PARAM: '1' +---- + +. Edit the `JAEGER_ENDPOINT` value to match the name of the Jaeger collector service in your deployment. ++ +From the left menu of the main {ocp} screen, obtain the value of JAEGER_ENDPOINT by navigation to *Networking -> Services*. Alternatively, execute the following `oc` command: ++ +---- +$ oc get services +---- ++ +The requested value is included in the service name that contains the `collector` string. -* List of all link:https://github.com/jaegertracing/jaeger-client-go#environment-variables[Jaeger client environment variables] + + +.Additional resources +* For additional information about custom environment properties and how to define them in CheCluster Customer Resource, see link:https://www.eclipse.org/che/docs/che-7/advanced-configuration-options/[Advanced configuration options]. +* For custom configuration of Jaeger, see the list of link:https://github.com/jaegertracing/jaeger-client-go#environment-variables[Jaeger client environment variables]. diff --git a/src/main/pages/che-7/administration-guide/proc_installing-jaeger-locally-using-a-pre-built-container-image.adoc b/src/main/pages/che-7/administration-guide/proc_installing-jaeger-locally-using-a-pre-built-container-image.adoc new file mode 100644 index 0000000000..d19b9cf6c5 --- /dev/null +++ b/src/main/pages/che-7/administration-guide/proc_installing-jaeger-locally-using-a-pre-built-container-image.adoc @@ -0,0 +1,36 @@ +// installing-the-jaeger-tracing-tool + +[id="installing-jaeger-locally-using-a-pre-built-container-image_{context}"] += Installing Jaeger locally using a pre-built container image + +To install the Jaeger tracing tool locally using a pre-built container image, follow the instructions below. + +.Prerequisites + +* You are logged into a system as a user with sudo privileges. +* Podman is installed. For additional, see the link:https://podman.io/getting-started/installation.html[Podman Installation Instructions] + +.Procedure + +. Start Podman: ++ +---- +$ sudo service podman start +---- + +. Install Jaeger using the pre-built container image. ++ +---- + $ podman run -d --name jaeger \ + -e COLLECTOR_ZIPKIN_HTTP_PORT=9411 \ + -p 5775:5775/udp \ + -p 6831:6831/udp \ + -p 6832:6832/udp \ + -p 5778:5778 \ + -p 16686:16686 \ + -p 14268:14268 \ + -p 9411:9411 \ + jaegertracing/all-in-one:1.15 +---- + +. Navigate to `http://localhost:16686` to access the Jaeger UI. diff --git a/src/main/pages/che-7/administration-guide/proc_installing-jaeger-using-operatorhub-on-openshift-4.adoc b/src/main/pages/che-7/administration-guide/proc_installing-jaeger-using-operatorhub-on-openshift-4.adoc new file mode 100644 index 0000000000..fd4aa56353 --- /dev/null +++ b/src/main/pages/che-7/administration-guide/proc_installing-jaeger-using-operatorhub-on-openshift-4.adoc @@ -0,0 +1,37 @@ +// installing-the-jaeger-tracing-tool + +[id="installing-jaeger-using-operatorhub-on-openshift-4_{context}"] += Installing Jaeger using OperatorHub on OpenShift 4 + +To install the Jaeger tracing tool from the OperatorHub interface in {ocp}, follow the instructions below. + +.Prerequisites + +* The user is logged in to the {ocp} Web Console. +* A {prod-short} instance is deployed in a namespace. + +.Procedure + +. Open the {ocp} console. +. From the left menu of the main {ocp} screen, navigate to *Operators → OperatorHub*. + +. In the *Search by keyword* search bar, type `Jaeger Operator`. + +. Click the `Jaeger Operator` tile. + +. Click the btn:[Install] button in the `Jaeger Operator` pop-up window. + +. Select the installation method: `A specific namespace on the cluster` where the {prod-short} is deployed and leave the rest in its default values. +. Click the *Subscribe* button. +. From the left menu of the main {ocp} screen, navigate to the *Operators → Installed Operators* section. +. Eclipse Che is displayed as an Installed Operator, as indicated by the *InstallSucceeded* status. +. Click the *Jaeger Operator* name in the list of installed operators. +. Navigate to the *Overview* tab. +. In the Conditions sections at the bottom of the page, wait for this message: `install strategy completed with no errors`. +. `Jaeger Operator` and additional `Elasticsearch Operator` is installed. +. Navigate to the *Operators → Installed Operators* section. +. Click *Jaeger Operator* in the list of installed operators. +. The *Jaeger Cluster* page is displayed. +. In the bottom-left corner of the window, click *Create Instance* . +. Click *Save*. +. The Jaeger cluster `jaeger-all-in-one-inmemory` is created. diff --git a/src/main/pages/che-7/administration-guide/proc_installing-the-jaeger-tracing-tool-for-che-on-openshift-4.adoc b/src/main/pages/che-7/administration-guide/proc_installing-the-jaeger-tracing-tool-for-che-on-openshift-4.adoc new file mode 100644 index 0000000000..f3ae97cd34 --- /dev/null +++ b/src/main/pages/che-7/administration-guide/proc_installing-the-jaeger-tracing-tool-for-che-on-openshift-4.adoc @@ -0,0 +1,46 @@ +// installing-the-jaeger-tracing-tool + +[id="installing-the-jaeger-tracing-tool-for-che-on-openshift-4_{context}"] += Installing the Jaeger tracing tool for Che on OpenShift 4 + +To install the Jaeger tracing tool from a Che project in {ocp}, follow the instructions below. + +.Prerequisites + +* The user is logged in to the {ocp} web console. +* {prod-short} is installed in a {ocp} cluster. + +.Procedure + +. In the {prod-short}} installation namespace of the {ocp} cluster, use the `oc` client to create a new application for the Jaeger deployment. ++ +[subs="+quotes,attributes"] +---- +$ oc new-app -f / ${CHE_LOCAL_GIT_REPO}/deploy/openshift/templates/jaeger-all-in-one-template.yml: + +--> Deploying template "____/jaeger-template-all-in-one" for "/home/user/{project-context}-projects/{project-context}/deploy/openshift/templates/jaeger-all-in-one-template.yml" to project ____ + + Jaeger (all-in-one) + --------- + Jaeger Distributed Tracing Server (all-in-one) + + * With parameters: + * Jaeger Service Name=jaeger + * Image version=latest + * Jaeger Zipkin Service Name=zipkin + +--> Creating resources ... + deployment.apps "jaeger" created + service "jaeger-query" created + service "jaeger-collector" created + service "jaeger-agent" created + service "zipkin" created + route.route.openshift.io "jaeger-query" created +--> Success + Access your application via route 'jaeger-query-____.apps.ci-ln-whx0352-d5d6b.origin-ci-int-aws.dev.rhcloud.com' + Run 'oc status' to view your app. +---- + +. Using the *Workloads -> Deployments* from the left menu of main {ocp} screen, monitor the Jaeger deployment until it finishes successfully. + +. Select *Networking -> Routes* from the left menu of the main {ocp} screen, and click the URL link to access the Jaeger dashboard.