From c1995f75932f2c1bcdfde4c0ce1e63e11389a0cf Mon Sep 17 00:00:00 2001 From: Gwynne Monahan Date: Mon, 19 Aug 2024 13:31:23 -0500 Subject: [PATCH] OSSM-6974 Traces content --- _topic_maps/_topic_map.yml | 7 ++ modules/ossm-config-otel.adoc | 150 ++++++++++++++++++++++++ traces/_attributes | 1 + traces/docinfo.xml | 14 +++ traces/images | 1 + traces/modules | 1 + traces/ossm-distr-tracing-assembly.adoc | 21 ++++ traces/snippets | 1 + 8 files changed, 196 insertions(+) create mode 100644 modules/ossm-config-otel.adoc create mode 120000 traces/_attributes create mode 100644 traces/docinfo.xml create mode 120000 traces/images create mode 120000 traces/modules create mode 100644 traces/ossm-distr-tracing-assembly.adoc create mode 120000 traces/snippets diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index 278b92b0b85f..86390a804d2b 100644 --- a/_topic_maps/_topic_map.yml +++ b/_topic_maps/_topic_map.yml @@ -34,6 +34,13 @@ Topics: - Name: Using metrics with Service Mesh File: ossm-metrics-assembly --- +Name: Distributed tracing +Dir: traces +Distros: openshift-service-mesh +Topics: +- Name: Configuring distributed tracing with Service Mesh + File: ossm-distr-tracing-assembly +--- Name: Kiali Operator provided by Red Hat Dir: kiali Distros: openshift-service-mesh diff --git a/modules/ossm-config-otel.adoc b/modules/ossm-config-otel.adoc new file mode 100644 index 000000000000..4a1ee124c927 --- /dev/null +++ b/modules/ossm-config-otel.adoc @@ -0,0 +1,150 @@ +// Module included in the following assemblies: +// +// * service-mesh-docs-main/traces/ossm-distr-tracing-assembly.adoc + +:_mod-docs-content-type: PROCEDURE +[id="ossm-config-otel_{context}"] += Configuring {OTELName} with Service Mesh + +You can integrate {SMProductName} with {OTELName} to instrument, generate, collect, and export OpenTelemetry traces, metrics, and logs to analyze and understand your software's performance and behavior. + +.Prerequisites + +* {TempoOperator} is installed. See: link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.16/html/distributed_tracing/distributed-tracing-platform-tempo#distr-tracing-tempo-install-web-console_dist-tracing-tempo-installing[Installing the Tempo Operator]. +* {OTELOperator} is installed. See: link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.16/html/red_hat_build_of_opentelemetry/install-otel[Installing the Red Hat build of OpenTelemetry] +* A TempoStack is installed and configured in a `tempo` namespace. See: link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.16/html/distributed_tracing/distributed-tracing-platform-tempo#installing-a-tempostack-instance[Installing a TempoStack instance]. +* An Istio instance is created. +* An Istio CNI instance is created. + +.Procedure + +. Navigate to the {OTELOperator} and install the `OpenTelemetryCollector` resource in the `istio-system` namespace: ++ +.Example OpenTelemetry Collector in `istio-system` namespace +[source, yaml] +---- +kind: OpenTelemetryCollector +apiVersion: opentelemetry.io/v1beta1 +metadata: + name: otel + namespace: istio-system +spec: + observability: + metrics: {} + deploymentUpdateStrategy: {} + config: + exporters: + otlp: + endpoint: 'tempo-sample-distributor.tempo.svc.cluster.local:4317' + tls: + insecure: true + receivers: + otlp: + protocols: + grpc: + endpoint: '0.0.0.0:4317' + http: {} + service: + pipelines: + traces: + exporters: + - otlp + receivers: + - otlp +---- + +. Configure {SMProductName} to enable tracing, and define the {OTELShortName} tracing providers in your `meshConfig`: ++ +.Example enabling tracing and defining tracing providers +[source,yaml] +---- +apiVersion: sailoperator.io/v1alpha1 +kind: Istio +metadata: +# ... + name: default +spec: + namespace: istio-system +# ... + values: + meshConfig: + enableTracing: true + extensionProviders: + - name: otel-tracing + opentelemetry: + port: 4317 + service: otel-collector.istio-system.svc.cluster.local # <1> +---- +<1> The `service` field is the `OpenTelemetry` collector service in the `istio-system` namespace. + +. Create an Istio Telemetry resource to enable tracers defined in `spec.values.meshConfig.ExtensionProviders`: ++ +.Example Istio Telemetry resource +[source,yaml] +---- +apiVersion: telemetry.istio.io/v1 +kind: Telemetry +metadata: + name: otel-demo + namespace: istio-system +spec: + tracing: + - providers: + - name: otel-tracing + randomSamplingPercentage: 100 +---- ++ +[NOTE] +==== +Once you verify that you can see traces, lower the `randomSamplingPercentage` value or set it to `default` to reduce the number of requests. +==== + +. Deploy the `bookinfo` application in `bookinfo` namespace: ++ +[source, terminal] +---- +oc create ns bookinfo +---- ++ +[source, terminal] +---- +oc label ns istio.io/rev= # <1> +---- ++ +[source, terminal] +---- +oc apply -f https://raw.githubusercontent.com/istio/istio/release-1.23/samples/bookinfo/platform/kube/bookinfo.yaml -n bookinfo +---- +<1> If you named your Istio resource `default` and are using the `InPlace` upgrade strategy, use `oc label ns bookinfo istio-injection=enabled`. ++ +[NOTE] +==== +To find your ``, run the following command: + +[source, terminal] +---- +oc get istiorevisions.sailoperator.io +---- + +.Sample output: + +[source,terminal] +---- +NAME TYPE READY STATUS IN USE VERSION AGE +default-v1-23-0 Local True Healthy False v1.23.0 3m33s +---- +==== + +. Generate traffic to the `productpage` pod to generate traces: ++ +[source,terminal] +---- +$ oc exec -it -n bookinfo deployments/productpage-v1 -c istio-proxy -- curl localhost:9080/productpage +---- + +. Validate the integration by running the following command to see traces in the UI: ++ +[source,terminal] +---- +$ kubectl get routes -n tempo tempo-sample-query-frontend +---- \ No newline at end of file diff --git a/traces/_attributes b/traces/_attributes new file mode 120000 index 000000000000..93957f02273f --- /dev/null +++ b/traces/_attributes @@ -0,0 +1 @@ +../_attributes \ No newline at end of file diff --git a/traces/docinfo.xml b/traces/docinfo.xml new file mode 100644 index 000000000000..d101739759dc --- /dev/null +++ b/traces/docinfo.xml @@ -0,0 +1,14 @@ +Distributed Tracing +OpenShift Service Mesh +3.0tp1 +Using distributed tracing with {SMProduct} + + This document provides an overview of distributed tracing in {SMProduct}, and how to configure distributed tracing for {SMProductShortName}. + + + + Red Hat OpenShift Documentation Team + + + + diff --git a/traces/images b/traces/images new file mode 120000 index 000000000000..5e67573196d8 --- /dev/null +++ b/traces/images @@ -0,0 +1 @@ +../images \ No newline at end of file diff --git a/traces/modules b/traces/modules new file mode 120000 index 000000000000..464b823aca16 --- /dev/null +++ b/traces/modules @@ -0,0 +1 @@ +../modules \ No newline at end of file diff --git a/traces/ossm-distr-tracing-assembly.adoc b/traces/ossm-distr-tracing-assembly.adoc new file mode 100644 index 000000000000..36c2a1efd351 --- /dev/null +++ b/traces/ossm-distr-tracing-assembly.adoc @@ -0,0 +1,21 @@ +:_content-type: ASSEMBLY +[id="ossm-distr-tracing-assembly"] += Configuring {DTProductName} with Service Mesh +include::_attributes/common-attributes.adoc[] +:context: ossm-traces-assembly + +toc::[] + +Integrating {DTProductName} with {SMProductName} is made of up two parts: {TempoName} and {OTELName}. + +{TempoName}:: Provides distributed tracing to monitor and troubleshoot transactions in complex distributed systems. Tempo is based on the open source link:https://grafana.com/oss/tempo/[Grafana Tempo] project. ++ +For more about information about {temposhortname}, its features, installation, and configuration, see: link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.16/html/distributed_tracing/distributed-tracing-platform-tempo[{TempoName}]. + +{OTELName}:: Is based on the open source link:https://opentelemetry.io/[OpenTelemetry project], which aims to provide unified, standardized, and vendor-neutral telemetry data collection for cloud-native software. {OTELName} product provides support for deploying and managing the OpenTelemetry Collector and simplifying the workload instrumentation. ++ +The link:https://opentelemetry.io/docs/collector/[OpenTelemetry Collector] can receive, process, and forward telemetry data in multiple formats, making it the ideal component for telemetry processing and interoperability between telemetry systems. The Collector provides a unified solution for collecting and processing metrics, traces, and logs. ++ +For more information about {OTELShortName}, its features, installation, and configuration, see: link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.16/html/red_hat_build_of_opentelemetry/index[{OTELName}]. + +include::modules/ossm-config-otel.adoc[leveloffset=1] \ No newline at end of file diff --git a/traces/snippets b/traces/snippets new file mode 120000 index 000000000000..9f5bc7e4dde0 --- /dev/null +++ b/traces/snippets @@ -0,0 +1 @@ +../snippets \ No newline at end of file