docs: refine info about configuring Grafana/Jaeger (#2315)

Signed-off-by: Meg McRoberts <meg.mcroberts@dynatrace.com>
Co-authored-by: Moritz Wiesinger <moritz.wiesinger@dynatrace.com>

docs/content/en/docs/implementing/otel.md

@@ -93,39 +93,47 @@ you must have the following on your cluster:
   See
   [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/)
   for more information.
-- Prometheus Operator.
+- A Prometheus Operator.
   See [Prometheus Operator Setup](https://github.com/prometheus-operator/kube-prometheus/blob/main/docs/customizing.md).
-- The Prometheus Operator must have the required permissions
-  to watch resources of the `keptn-lifecycle-toolkit-system` namespace (see
-  [Setup for Monitoring other Namespaces](https://prometheus-operator.dev/docs/kube/monitoring-other-namespaces/)).
 
-If you want a dashboard for reviewing metrics and traces,
-you need:
-
-- [Grafana](https://grafana.com/)
-  or the dashboard of your choice.
-   See
-  [Grafana Setup](https://grafana.com/docs/grafana/latest/setup-grafana/).
-
-- [Jaeger](https://jaegertracing.io)
-  or a similar tool if you want traces.
-   See
-  [Jaeger Setup](https://github.com/jaegertracing/jaeger-operator#getting-started).
-
-To install Prometheus into the `monitoring` namespace,
-using the default configuration included with Keptn,
-use the following commands.
-Use similar commands if you define a different configuration::
-
-> **Note**
-You must clone  the `lifecycle-toolkit` repository and `cd` into the correct directory
-(`examples/support/observability`) before running the following commands.
-
-```shell
-kubectl create namespace monitoring
-kubectl apply --server-side -f config/prometheus/setup
-kubectl apply -f config/prometheus/
-```
+  - The Prometheus Operator must have the required permissions
+    to watch resources of your Keptn namespace (default is `keptn-lifecycle-toolkit-system`) (see
+    [Setup for Monitoring other Namespaces](https://prometheus-operator.dev/docs/kube/monitoring-other-namespaces/)).
+
+  - To install Prometheus into the `monitoring` namespace
+    using the example configuration included with Keptn,
+    use the following command sequence.
+    Use similar commands if you define a different configuration:
+
+    > **Note**
+    You must clone the `lifecycle-toolkit` repository
+    and `cd` into the correct directory
+    (`examples/support/observability`) before running the following commands.
+
+    ```shell
+    kubectl create namespace monitoring
+    kubectl apply --server-side -f config/prometheus/setup/
+    kubectl apply -f config/prometheus/
+    ```
+
+- If you want a dashboard for reviewing metrics and traces:
+
+  - Install
+    [Grafana](https://grafana.com/grafana/)
+    or the visualization tool of your choice, following the instructions in
+    [Grafana Setup](https://grafana.com/docs/grafana/latest/setup-grafana/).
+  - Install
+    [Jaeger](https://www.jaegertracing.io/)
+    or a similar tool for traces following the instructions in
+    [Jaeger Setup](https://www.jaegertracing.io/docs/1.50/getting-started/).
+
+  - Follow the instructions in the Grafana
+    [README](https://github.com/keptn/lifecycle-toolkit/blob/main/dashboards/grafana/README.md)
+    file to configure the Grafana dashboard(s) for Keptn..
+
+    Metrics can also be retrieved without a dashboard.
+    See
+    [Accessing Metrics via the Kubernetes Custom Metrics API](evaluatemetrics.md/#accessing-metrics-via-the-kubernetes-custom-metrics-api)
 
 ### Integrate OpenTelemetry into Keptn
 

docs/content/en/docs/install/k8s.md

@@ -55,8 +55,7 @@ The basic steps are:
 ## Prepare your cluster for Keptn
 
 Keptn installs into an existing Kubernetes cluster.
-When setting up a local Kubernetes cluster
-to study or demonstrate Keptn,
+When setting up a local Kubernetes cluster to study or demonstrate Keptn,
 you need to provide these components.
 
 Your cluster should include the following:
@@ -65,42 +64,55 @@ Your cluster should include the following:
   See [Supported Kubernetes versions](reqs.md/#supported-kubernetes-versions)
   for details.
 
-* [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl)
+* The
+  [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl)
+  CLI that is used to interact with Kubernetes clusters.
 
-* [Helm](https://helm.sh/docs/intro/install/)
-
-* Metric provider such as
-  [Prometheus](https://prometheus.io/),
-  [Dynatrace](https://www.dynatrace.com/),
-  or [Datadog](https://www.datadoghq.com/).
-  This is used for the metrics used for the observability features
-  as well as the pre- and post-deployment evaluations.
+* The
+  [Helm](https://helm.sh/docs/intro/install/)
+  CLI that is used to install and configure Keptn.
 
 * Deployment tools of your choice,
   such as
   [Argo CD](https://argo-cd.readthedocs.io/en/stable/) or
   [Flux](https://fluxcd.io/).
-  Alternatively, Keptn also works with just `kubctl apply` for deployment.
+  Alternatively, Keptn also works with just `kubectl apply` for deployment.
+
+* At least one observability data provider such as
+  [Prometheus](https://prometheus.io/),
+  [Dynatrace](https://www.dynatrace.com/),
+  or [Datadog](https://www.datadoghq.com/);
+  you can use multiple instances of different data providers.
+  These provide:
+
+  * Metrics used for
+    [Keptn Metrics](../implementing/evaluatemetrics.md/)
+  * Metrics used for
+    [OpenTelemetry](../implementing/otel.md/)
+    observability
+  * SLIs for pre- and post-deployment
+    [evaluations](../implementing/evaluations.md/)
+  * SLIs used for
+    [analyses](../implementing/slo/)
 
 * If you want to use the standardized observability feature,
   you must have an OpenTelemetry collector
-  and a Prometheus operator installed on your cluster.
-
-  If you want a dashboard for reviewing metrics and traces,
-  install Grafana or the dashboard of your choice.
-
-  For traces, install Jaeger or a similar tool.
+  as well as a Prometheus operator installed on your cluster.
+  For more information, see
+  [Requirements for OpenTelemetry](../implementing/otel.md/#requirements-for-opentelemetry).
 
+* If you want a dashboard for reviewing metrics and traces,
+  install the dashboard tools of your choice;
+  we primarily use Grafana.
   For more information, see
   [Requirements for Open Telemetry](../implementing/otel.md/#requirements-for-opentelemetry).
 
-Also note that Keptn includes
-a light-weight cert-manager that, by default, is installed
-as part of the Keptn software.
-If you are using another cert-manager in the cluster,
-you can configure Keptn to instead use your cert-manager.
-See [Use Keptn with cert-manager.io](../operate/cert-manager.md)
-for detailed instructions.
+* Keptn includes a lightweight `cert-manager` that, by default,
+  is installed as part of the Keptn software.
+  If you are using another certificate manager in the cluster,
+  you can configure Keptn to instead use your cert-manager.
+  See [Use Keptn with cert-manager.io](../operate/cert-manager.md)
+  for detailed instructions.
 
 ## How many namespaces?
 
@@ -109,7 +121,7 @@ and how to set them up.
 See the Kubernetes
 [Namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/)
 documentation for some basic information.
-You can also search and find lots of "Best Practices for Namespaces"
+You can also search and find many "Best Practices for Namespaces"
 documents published on the web.
 
 Some considerations for Keptn: