diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index 514e2c6725..1b21fd5525 100644 --- a/_topic_maps/_topic_map.yml +++ b/_topic_maps/_topic_map.yml @@ -3486,12 +3486,12 @@ Topics: # logging - Name: Cluster logging with OpenShift Serverless File: cluster-logging-serverless - # Tracing - - Name: Tracing requests using Jaeger - File: serverless-tracing # Metrics - Name: Serverless developer metrics File: serverless-developer-metrics +# Tracing +- Name: Tracing + File: serverless-tracing # Support - Name: Support File: serverless-support diff --git a/_topic_maps/_topic_map_osd.yml b/_topic_maps/_topic_map_osd.yml index 323b946b84..3fa3bc60f5 100644 --- a/_topic_maps/_topic_map_osd.yml +++ b/_topic_maps/_topic_map_osd.yml @@ -297,10 +297,11 @@ Topics: Topics: - Name: Cluster logging with OpenShift Serverless File: cluster-logging-serverless - - Name: Tracing requests using Jaeger - File: serverless-tracing - Name: Serverless developer metrics File: serverless-developer-metrics +# Tracing +- Name: Tracing + File: serverless-tracing - Name: Support File: serverless-support - Name: Security diff --git a/_topic_maps/_topic_map_rosa.yml b/_topic_maps/_topic_map_rosa.yml index 0a2a70bdbb..607d513f48 100644 --- a/_topic_maps/_topic_map_rosa.yml +++ b/_topic_maps/_topic_map_rosa.yml @@ -408,10 +408,11 @@ Topics: Topics: - Name: Cluster logging with OpenShift Serverless File: cluster-logging-serverless - - Name: Tracing requests using Jaeger - File: serverless-tracing - Name: Serverless developer metrics File: serverless-developer-metrics +# Tracing +- Name: Tracing + File: serverless-tracing - Name: Support File: serverless-support - Name: Security diff --git a/modules/distr-tracing-product-overview.adoc b/modules/distr-tracing-product-overview.adoc index c46143b55b..dce17005f9 100644 --- a/modules/distr-tracing-product-overview.adoc +++ b/modules/distr-tracing-product-overview.adoc @@ -2,6 +2,7 @@ This module included in the following assemblies: -service_mesh/v2x/ossm-architecture.adoc -distr_tracing_arch/distr-tracing-architecture.adoc +-serverless/serverless-tracing.adoc //// :_content-type: CONCEPT diff --git a/modules/serverless-jaeger-config.adoc b/modules/serverless-jaeger-config.adoc index 37b335accc..bfc26026c0 100644 --- a/modules/serverless-jaeger-config.adoc +++ b/modules/serverless-jaeger-config.adoc @@ -1,12 +1,12 @@ // Module is included in the following assemblies: // -// * serverless/monitor/serverless-tracing.adoc +// * serverless/serverless-tracing.adoc :_content-type: PROCEDURE [id="serverless-jaeger-config_{context}"] -= Configuring Jaeger for use with {ServerlessProductName} += Using Jaeger to enable distributed tracing -You can use the following procedure to set up Jaeger for use with {ServerlessProductName}. +If you do not want to install all of the components of {DTProductName}, you can still use distributed tracing on {product-title} with {ServerlessProductName}. To do this, you must install and configure Jaeger as a standalone integration. .Prerequisites @@ -19,8 +19,8 @@ ifdef::openshift-dedicated,openshift-rosa[] endif::[] * You have installed the {ServerlessOperatorName} and Knative Serving. -* You have installed the Jaeger Operator. -* Install the OpenShift CLI (`oc`). +* You have installed the {JaegerName} Operator. +* You have installed the OpenShift (`oc`) CLI. * You have created a project or have access to a project with the appropriate roles and permissions to create applications and other workloads in {product-title}. .Procedure @@ -52,11 +52,11 @@ spec: tracing: sample-rate: "0.1" <1> backend: zipkin <2> - zipkin-endpoint: http://jaeger-collector.default.svc.cluster.local:9411/api/v2/spans <3> + zipkin-endpoint: "http://jaeger-collector.default.svc.cluster.local:9411/api/v2/spans" <3> debug: "false" <4> ---- + -<1> The `sample-rate` defines sampling probability. Using `sample-rate: "0.1"` means that 1 in 10 traces will be sampled. +<1> The `sample-rate` defines sampling probability. Using `sample-rate: "0.1"` means that 1 in 10 traces are sampled. <2> `backend` must be set to `zipkin`. <3> The `zipkin-endpoint` must point to your `jaeger-collector` service endpoint. To get this endpoint, substitute the namespace where the Jaeger CR is applied. <4> Debugging should be set to `false`. Enabling debug mode by setting `debug: "true"` allows all spans to be sent to the server, bypassing sampling. @@ -69,7 +69,7 @@ You can access the Jaeger web console to see tracing data, by using the `jaeger` + [source,terminal] ---- -$ oc get route jaeger +$ oc get route jaeger -n default ---- + .Example output diff --git a/modules/serverless-open-telemetry.adoc b/modules/serverless-open-telemetry.adoc new file mode 100644 index 0000000000..9746f2f220 --- /dev/null +++ b/modules/serverless-open-telemetry.adoc @@ -0,0 +1,149 @@ +// Module is included in the following assemblies: +// +// * serverless/serverless-tracing.adoc + +:_content-type: PROCEDURE +[id="serverless-open-telemetry_{context}"] += Using {DTProductName} to enable distributed tracing + +{DTProductName} is made up of several components that work together to collect, store, and display tracing data. You can use {DTProductName} with {ServerlessProductName} to monitor and troubleshoot serverless applications. + +.Prerequisites + +* You have access to an {product-title} account with cluster administrator access. +* You have not yet installed the {ServerlessOperatorName} and Knative Serving. These must be installed after the {DTProductName} installation. +* You have installed {DTProductName} by following the {product-title} "Installing distributed tracing" documentation. +* You have installed the OpenShift (`oc`) CLI. +* You have created a project or have access to a project with the appropriate roles and permissions to create applications and other workloads in {product-title}. + +.Procedure + +. Create an `OpenTelemetryCollector` custom resource (CR): ++ +.Example OpenTelemetryCollector CR +[source,yaml] +---- +apiVersion: opentelemetry.io/v1alpha1 +kind: OpenTelemetryCollector +metadata: + name: cluster-collector + namespace: +spec: + mode: deployment + config: | + receivers: + zipkin: + processors: + exporters: + jaeger: + endpoint: jaeger-all-in-one-inmemory-collector-headless.tracing-system.svc:14250 + tls: + ca_file: "/var/run/secrets/kubernetes.io/serviceaccount/service-ca.crt" + logging: + service: + pipelines: + traces: + receivers: [zipkin] + processors: [] + exporters: [jaeger, logging] +---- + +. Verify that you have two pods running in the namespace where {DTProductName} is installed: ++ +[source,terminal] +---- +$ oc get pods -n +---- ++ +.Example output +[source,terminal] +---- +NAME READY STATUS RESTARTS AGE +cluster-collector-collector-85c766b5c-b5g99 1/1 Running 0 5m56s +jaeger-all-in-one-inmemory-ccbc9df4b-ndkl5 2/2 Running 0 15m +---- + +. Verify that the following headless services have been created: ++ +[source,terminal] +---- +$ oc get svc -n | grep headless +---- ++ +.Example output +[source,terminal] +---- +cluster-collector-collector-headless ClusterIP None 9411/TCP 7m28s +jaeger-all-in-one-inmemory-collector-headless ClusterIP None 9411/TCP,14250/TCP,14267/TCP,14268/TCP 16m +---- ++ +These services are used to configure Jaeger and Knative Serving. The name of the Jaeger service may vary. + +. Install the {ServerlessOperatorName} by following the "Installing the {ServerlessOperatorName}" documentation. + +. Install Knative Serving by creating the following `KnativeServing` CR: ++ +.Example KnativeServing CR +[source,yaml] +---- +apiVersion: operator.knative.dev/v1alpha1 +kind: KnativeServing +metadata: + name: knative-serving + namespace: knative-serving +spec: + config: + tracing: + backend: "zipkin" + zipkin-endpoint: "http://cluster-collector-collector-headless.tracing-system.svc:9411/api/v2/spans" + debug: "true" + sample-rate: "0.1" <1> +---- +<1> The `sample-rate` defines sampling probability. Using `sample-rate: "0.1"` means that 1 in 10 traces are sampled. + +. Create a Knative service: ++ +.Example service +[source,yaml] +---- +apiVersion: serving.knative.dev/v1 +kind: Service +metadata: + name: helloworld-go +spec: + template: + metadata: + labels: + app: helloworld-go + annotations: + autoscaling.knative.dev/minScale: "1" + autoscaling.knative.dev/target: "1" + spec: + containers: + - image: quay.io/openshift-knative/helloworld:v1.2 + imagePullPolicy: Always + resources: + requests: + cpu: "200m" + env: + - name: TARGET + value: "Go Sample v1" +---- + +. Make some requests to the service: ++ +.Example HTTPS request +[source,terminal] +---- +$ curl https://helloworld-go.example.com +---- + +. Get the URL for the Jaeger web console: ++ +.Example command +[source,terminal] +---- +$ oc get route jaeger-all-in-one-inmemory -o jsonpath='{.spec.host}' -n +---- ++ +You can now examine traces by using the Jaeger console. diff --git a/serverless/install/install-serverless-operator.adoc b/serverless/install/install-serverless-operator.adoc index 7fa7b94b08..da6dae112c 100644 --- a/serverless/install/install-serverless-operator.adoc +++ b/serverless/install/install-serverless-operator.adoc @@ -38,8 +38,13 @@ endif::[] // universal install doc include::modules/serverless-install-web-console.adoc[leveloffset=+1] -[role="_additional-resources"] +[IMPORTANT] +==== +If you want to xref:../../serverless/serverless-tracing.adoc#serverless-tracing[use {DTProductName} with {ServerlessProductName}], you must install and configure {DTProductName} before you install Knative Serving or Knative Eventing. +==== + [id="additional-resources_install-serverless-operator"] +[role="_additional-resources"] == Additional resources ifdef::openshift-enterprise[] * xref:../../operators/admin/olm-restricted-networks.adoc#olm-restricted-networks[Using Operator Lifecycle Manager on restricted networks] diff --git a/serverless/install/installing-knative-eventing.adoc b/serverless/install/installing-knative-eventing.adoc index 9693324445..e03648dc39 100644 --- a/serverless/install/installing-knative-eventing.adoc +++ b/serverless/install/installing-knative-eventing.adoc @@ -10,6 +10,11 @@ To use event-driven architecture on your cluster, install Knative Eventing. You After you install the {ServerlessOperatorName}, you can install Knative Eventing by using the default settings, or configure more advanced settings in the `KnativeEventing` custom resource (CR). For more information about configuration options for the `KnativeEventing` CR, see xref:../../serverless/admin_guide/serverless-configuration.adoc#serverless-configuration[Global configuration]. +[IMPORTANT] +==== +If you want to xref:../../serverless/serverless-tracing.adoc#serverless-tracing[use {DTProductName} with {ServerlessProductName}], you must install and configure {DTProductName} before you install Knative Eventing. +==== + include::modules/serverless-install-eventing-web-console.adoc[leveloffset=+1] include::modules/serverless-install-eventing-yaml.adoc[leveloffset=+1] diff --git a/serverless/install/installing-knative-serving.adoc b/serverless/install/installing-knative-serving.adoc index 4d83d1a7a7..0e75e1c67c 100644 --- a/serverless/install/installing-knative-serving.adoc +++ b/serverless/install/installing-knative-serving.adoc @@ -10,6 +10,11 @@ Installing Knative Serving allows you to create Knative services and functions o After you install the {ServerlessOperatorName}, you can install Knative Serving by using the default settings, or configure more advanced settings in the `KnativeServing` custom resource (CR). For more information about configuration options for the `KnativeServing` CR, see xref:../../serverless/admin_guide/serverless-configuration.adoc#serverless-configuration[Global configuration]. +[IMPORTANT] +==== +If you want to xref:../../serverless/serverless-tracing.adoc#serverless-tracing[use {DTProductName} with {ServerlessProductName}], you must install and configure {DTProductName} before you install Knative Serving. +==== + include::modules/serverless-install-serving-web-console.adoc[leveloffset=+1] include::modules/serverless-install-serving-yaml.adoc[leveloffset=+1] diff --git a/serverless/monitor/serverless-tracing.adoc b/serverless/monitor/serverless-tracing.adoc deleted file mode 100644 index cd8ca3b7e0..0000000000 --- a/serverless/monitor/serverless-tracing.adoc +++ /dev/null @@ -1,23 +0,0 @@ -:_content-type: ASSEMBLY -[id="serverless-tracing"] -= Tracing requests using Jaeger -:context: serverless-tracing -include::_attributes/common-attributes.adoc[] - -toc::[] - -Using Jaeger with {ServerlessProductName} allows you to enable _distributed tracing_ for your serverless applications on {product-title}. - -Distributed tracing records the path of a request through the various services that make up an application. - -It is used to tie information about different units of work together, to understand a whole chain of events in a distributed transaction. -The units of work might be executed in different processes or hosts. - -Developers can visualize call flows in large architectures with distributed tracing. which is useful for understanding serialization, parallelism, and sources of latency. - -ifdef::openshift-enterprise[] -For more information about distributed tracing, see xref:../../distr_tracing/distr_tracing_arch/distr-tracing-architecture.adoc#distributed-tracing-architecture[distributed tracing architecture] and xref:../../distr_tracing/distr_tracing_install/distr-tracing-installing.adoc#install-distributed-tracing[Installing distributed tracing]. -endif::[] - -// Serverless specific modules -include::modules/serverless-jaeger-config.adoc[leveloffset=+1] diff --git a/serverless/serverless-tracing.adoc b/serverless/serverless-tracing.adoc new file mode 100644 index 0000000000..7ef7dcd077 --- /dev/null +++ b/serverless/serverless-tracing.adoc @@ -0,0 +1,26 @@ +:_content-type: ASSEMBLY +[id="serverless-tracing"] += Tracing requests +:context: serverless-tracing +include::_attributes/common-attributes.adoc[] + +toc::[] + +Distributed tracing records the path of a request through the various services that make up an application. It is used to tie information about different units of work together, to understand a whole chain of events in a distributed transaction. The units of work might be executed in different processes or hosts. + +ifdef::openshift-enterprise[] +include::modules/distr-tracing-product-overview.adoc[leveloffset=+1] +// we can only use this module for OCP until OSD docs have distributed tracing install docs available, since this is part of the prereqs +include::modules/serverless-open-telemetry.adoc[leveloffset=+1] +endif::[] + +// standalone Jaeger only integration +include::modules/serverless-jaeger-config.adoc[leveloffset=+1] + +ifdef::openshift-enterprise[] +[id="additional-resources_serverless-tracing"] +[role="_additional-resources"] +== Additional resources +* xref:../distr_tracing/distr_tracing_arch/distr-tracing-architecture.adoc#distr-tracing-architecture[{DTProductName} architecture] +* xref:../distr_tracing/distr_tracing_install/distr-tracing-installing.adoc#installing-distributed-tracing[Installing distributed tracing] +endif::[]