diff --git a/modules/ossm-config-dt-ambient-mode.adoc b/modules/ossm-config-dt-ambient-mode.adoc new file mode 100644 index 000000000000..e428a634b132 --- /dev/null +++ b/modules/ossm-config-dt-ambient-mode.adoc @@ -0,0 +1,107 @@ +// Module included in the following assemblies: +// +// * service-mesh-docs-main/traces/ossm-distr-tracing-assembly.adoc + +:_mod-docs-content-type: PROCEDURE +[id="ossm-config-dt-ambient-mode_{context}"] += Configuring {TempoName} with Service Mesh ambient mode + +[role="_abstract"] +You can configure a {TempoShortName} with {SMProduct} ambient mode by using waypoint or gateway proxies to generate Layer 7 (L7) spans. The `ztunnel` component generates only Layer 4 (L4) data, so L7 trace spans appear only when a workload or service uses an attached waypoint or gateway proxy, The trace spans include telemetry from those proxies. + +.Prerequisites + +* You have installed the {TempoOperator}. See: link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/distributed_tracing/distr-tracing-tempo-installing#installing-the-tempo-operator_distr-tracing-tempo-installing[Installing the Tempo Operator]. +* You have installed the {OTELOperator}. See: link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/red_hat_build_of_opentelemetry/install-otel[Installing the Red Hat build of OpenTelemetry] +* You have installed a `TempoStack` which is configured in a `tempo` namespace. See: link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/distributed_tracing/distr-tracing-tempo-installing#installing-a-tempostack-instance_distr-tracing-tempo-installing[Installing a TempoStack instance]. +* You have created an {istio} instance. + +.Procedure + +. Navigate to the {OTELOperator} and install the `OpenTelemetryCollector` resource in the `istio-system` namespace, similar to the following example: ++ +[source, yaml] +---- +kind: OpenTelemetryCollector +apiVersion: opentelemetry.io/v1beta1 +metadata: + name: otel + namespace: istio-system +spec: + mode: deployment + 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 +---- + +* `exporters.otlp.endpoint` defines the Tempo sample distributor service in a namespace such as `tempo`. + +. Configure {SMProductName} {istio} custom resource (CR) to define a tracing provider in the `spec.values.meshConfig` field, similar to the following example: ++ +[source, yaml] +---- +apiVersion: sailoperator.io/v1 +kind: Istio +metadata: +# ... + name: default +spec: + namespace: istio-system + profile: ambient +# ... + values: + meshConfig: + enableTracing: true + extensionProviders: + - name: otel + opentelemetry: + port: 4317 + service: otel-collector.istio-system.svc.cluster.local + pilot: + trustedZtunnelNamespace: ztunnel +---- + +* `spec.values.meshConfig.extensionProviders.opentelemetry.service` defines the OpenTelemetry collector service in the `istio-system` namespace. + +. Create an {istio} Telemetry CR to enable the tracing provider defined in the `spec.values.meshConfig.ExtensionProviders` field, similar to the following example: ++ +[source, yaml] +---- +apiVersion: telemetry.istio.io/v1 +kind: Telemetry +metadata: + name: otel-demo + namespace: istio-system +spec: + tracing: + - providers: + - name: otel + randomSamplingPercentage: 100 +---- + ++ +[NOTE] +==== +Once you can see the traces, lower the `randomSamplingPercentage` value or set it to `default` to reduce the number of requests. You can also use the `spec.targetRefs` field to enable tracing at a gateway or a waypoint level +==== + +. Optional: Use a single {istio} Telemetry resource for both a Prometheus metrics provider and a tracing provider by setting `spec.metrics.overrides.disabled` field to `false`. This enables the Prometheus metrics provider. You do not need this step if you have configured metrics through the OpenShift Cluster Monitoring approach described above. diff --git a/modules/ossm-config-otel.adoc b/modules/ossm-config-otel.adoc index 3a42ab177709..5a9489678359 100644 --- a/modules/ossm-config-otel.adoc +++ b/modules/ossm-config-otel.adoc @@ -6,21 +6,21 @@ [id="ossm-config-otel_{context}"] = Configuring {OTELName} with Service Mesh +[role="_abstract"] 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/latest/html/distributed_tracing/distr-tracing-tempo-installing#installing-the-tempo-operator_distr-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/latest/html/distributed_tracing/distr-tracing-tempo-installing#installing-a-tempostack-instance_distr-tracing-tempo-installing[Installing a TempoStack instance]. -* An Istio instance is created. -* An Istio CNI instance is created. +* You have installed the {TempoOperator}. See: link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/distributed_tracing/distr-tracing-tempo-installing#installing-the-tempo-operator_distr-tracing-tempo-installing[Installing the Tempo Operator]. +* You have installed the {OTELOperator}. See: link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/red_hat_build_of_opentelemetry/install-otel[Installing the Red Hat build of OpenTelemetry] +* You have installed a `TempoStack` which is configured in a `tempo` namespace. See: link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/distributed_tracing/distr-tracing-tempo-installing#installing-a-tempostack-instance_distr-tracing-tempo-installing[Installing a TempoStack instance]. +* You have created an {istio} instance. +* You have created an {istio} CNI instance. .Procedure -. Navigate to the {OTELOperator} and install the `OpenTelemetryCollector` resource in the `istio-system` namespace: +. Navigate to the {OTELOperator} and install the `OpenTelemetryCollector` resource in the `istio-system` namespace, similar to the following example: + -.Example OpenTelemetry Collector in `istio-system` namespace [source, yaml] ---- kind: OpenTelemetryCollector @@ -53,9 +53,8 @@ spec: - otlp ---- -. Configure {SMProductName} to enable tracing, and define the {OTELShortName} tracing providers in your `meshConfig`: +. Configure {SMProductName} to enable tracing, and define the {OTELShortName} tracing providers in your `meshConfig`, similar to the following example: + -.Example enabling tracing and defining tracing providers [source,yaml] ---- apiVersion: sailoperator.io/v1 @@ -77,9 +76,8 @@ spec: ---- <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`: +. Create an Istio Telemetry resource to enable tracers defined in `spec.values.meshConfig.ExtensionProviders`, similar to the following example: + -.Example Istio Telemetry resource [source,yaml] ---- apiVersion: telemetry.istio.io/v1 @@ -94,9 +92,11 @@ spec: randomSamplingPercentage: 100 ---- + +Once you verify that you can see traces, lower the `randomSamplingPercentage` value or set it to `default` to reduce the number of requests. ++ [NOTE] ==== -Once you verify that you can see traces, lower the `randomSamplingPercentage` value or set it to `default` to reduce the number of requests. +You can use a single {istio} Telemetry resource for both the Prometheus metrics provider and a tracing provider by setting `spec.metrics.overrides.disabled` to `false`. This enables the Prometheus metrics provider. This is an optional step and you can skip it if you configured metrics through the OpenShift Cluster Monitoring method described above. ==== . Create the `bookinfo` namespace by running the following command: diff --git a/modules/ossm-verifying-traces-ambient-mode.adoc b/modules/ossm-verifying-traces-ambient-mode.adoc new file mode 100644 index 000000000000..485d2879ee56 --- /dev/null +++ b/modules/ossm-verifying-traces-ambient-mode.adoc @@ -0,0 +1,41 @@ +// Module included in the following assemblies: +// +// * service-mesh-docs-main/traces/ossm-distr-tracing-assembly.adoc + +:_mod-docs-content-type: PROCEDURE +[id="ossm-verifying-traces-ambient-mode_{context}"] += Verifying traces in ambient mode + +[role="_abstract"] +You can verify that the traces for the Bookinfo application are in ambient mode. + +.Prerequisites + +* You have deployed the Bookinfo application in ambient mode to use the following example. For more information, see https://docs.redhat.com/en/documentation/red_hat_openshift_service_mesh/latest/html/installing/ossm-istio-ambient-mode#ossm-deploying-bookinfo-application-istio-ambient-mode_ossm-istio-ambient-mode[Deploying the Bookinfo application in Istio ambient mode]. + +* You have deployed a waypoint proxy and enrolled the `bookinfo` namespace to use the waypoint. For more information, see https://docs.redhat.com/en/documentation/red_hat_openshift_service_mesh/latest/html/installing/ossm-istio-ambient-mode#ossm-deploying-waypoint-proxy_ossm-istio-ambient-mode[Deploying a waypoint proxy]. + +.Procedure + +. Send some traffic to the Bookinfo `productpage` service for generating traces by running the following command: ++ +[source,terminal] +---- +$ curl "http://${GATEWAY_URL}/productpage" | grep "" +---- + +. Verify that the Bookinfo application traces in a Tempo dashboard UI by running the following command: ++ +[source,terminal] +---- +$ oc get routes -n tempo tempo-sample-query-frontend +---- + +. Select the `bookinfo-gateway-istio.booinfo` or the `waypoint.bookinfo` service from the dashboard UI. + +. Click *Find Traces*. ++ +[NOTE] +==== +The {ocp-short-name} route for Tempo dashboard UI can be created from the `TempoStack` custom resource (CR) with `.spec.template.queryFrontend.jaegerQuery.ingress.type: route` field. +==== \ No newline at end of file diff --git a/observability/traces/ossm-distr-tracing.adoc b/observability/traces/ossm-distr-tracing.adoc index 6a7648942ad9..ce284f4fc300 100644 --- a/observability/traces/ossm-distr-tracing.adoc +++ b/observability/traces/ossm-distr-tracing.adoc @@ -6,16 +6,21 @@ include::_attributes/common-attributes.adoc[] toc::[] +[role="_abstract"] 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/latest/html/distributed_tracing/distr-tracing-architecture[{TempoName}]. +For more about information about {temposhortname}, its features, installation, and configuration, see: link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/distributed_tracing/index[{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. +The link:https://opentelemetry.io/docs/collector/[OpenTelemetry Collector] can receive, process, and forward telemetry data in many 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}]. +For more information about {OTELShortName}, its features, installation, and configuration, see: link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/red_hat_build_of_opentelemetry/index[{OTELName}]. -include::modules/ossm-config-otel.adoc[leveloffset=+1] \ No newline at end of file +include::modules/ossm-config-otel.adoc[leveloffset=+1] + +include::modules/ossm-config-dt-ambient-mode.adoc[leveloffset=+1] + +include::modules/ossm-verifying-traces-ambient-mode.adoc[leveloffset=+2] \ No newline at end of file