STAC-22435 Update getting started

Author: rb3ckers

setup/install-stackstate/kubernetes_openshift/ingress.md

@@ -52,7 +52,7 @@ This step assummes that [Generate `baseConfig_values.yaml` and `sizing_values.ya
 {% endhint %}
 
 
-## Configure Ingress Rule for Open Telemetry Traces via the SUSE Observability Helm chart
+## Configure Ingress Rule for Open Telemetry
 
 The SUSE Observability Helm chart exposes an `opentelemetry-collector` service in its values where a dedicated `ingress` can be created. This is disabled by default. The ingress needed for `opentelemetry-collector` purposed needs to support GRPC protocol. The example below shows how to use the Helm chart to configure an nginx-ingress controller with GRPC and  TLS encryption enabled. Note that setting up the controller itself and the certificates is beyond the scope of this document.
 

setup/otel/collector.md

@@ -27,7 +27,7 @@ To install and configure the collector for usage with SUSE Observability we'll u
    2. generating metrics from traces
    3. sending the data to SUSE Observability
    4. combine it all together in pipelines
-2. [Create a Kubernetes secret for the SUSE Observability API key](#create-secret-for-the-api-key)
+2. [Create a Kubernetes secret for the SUSE Observability API key](#create-a-secret-for-the-api-key)
 3. [Deploy the collector](#deploy-the-collector)
 4. [Configure your instrumented applicatins to send telemetry to the collector](#configure-applications)
 
@@ -166,7 +166,7 @@ The `service` section determines what components of the collector are enabled. T
 The `pipelines` section defines pipelines for the traces and metrics. The metrics pipeline defines:
 * `receivers`, to receive metrics from instrumented applications (via the OTLP protocol, `otlp`), from spans (the `spanmetrics` connector) and by scraping Prometheus endpoints (the `prometheus` receiver). The latter is configured by default in the collector Helm chart to scrape the collectors own metrics
 * `processors`: The `memory_limiter` helps to prevent out-of-memory errors. The `batch` processor helps better compress the data and reduce the number of outgoing connections required to transmit the data. The `resource` processor adds additional resource attributes (discussed separately)
-* `exporters`: The `debug` exporter simply logs to stdout which helps when troubleshooting. The `otlp/stackstate` exporter sends telemetry data to SUSE Observability using the OTLP protocol via GRPC (Default). The `otlphttp/stackstate` exporter sends telemetry data to SUSE Observability using the OTLP protocol via HTTP and is meant to be used where there area some impediments to use the GRPC one (needs to be activated in the pipelines). Both OTLP exporters are configured to use the bearertokenauth extension for authentication to send data to the SUSE Observability OTLP endpoint.
+* `exporters`: The `debug` exporter simply logs to stdout which helps when troubleshooting. The `otlp/stackstate` exporter sends telemetry data to SUSE Observability using the OTLP protocol via GRPC (Default). The `otlphttp/stackstate` exporter sends telemetry data to SUSE Observability using the OTLP protocol via HTTP and is meant to be used where there area some impediments to use the GRPC one (needs to be activated in the pipelines). Both OTLP exporters are configured to use the bearertokenauth extension for authentication to send data to the SUSE Observability OTLP endpoint. You only need to use one of them, the examle uses the `otlp/stackstate` exporter which uses the GRCP protocol. Uf you find that this doesn't work (for example because a proxy server that is used doesn't properly support GRPC traffic) you can switch to the `otlphttp/stackstate` protocol instead. For more configuration options (for example to disable TLS validation) see the [exporter configuration docs](https://github.com/open-telemetry/opentelemetry-collector/blob/main/exporter/otlpexporter/README.md).
 
 For traces, there are 3 pipelines that are connected:
 * `traces`: The pipeline that receives traces from SDKs (via the `otlp` receiver) and does the initial processing using the same processors as for metrics. It exports into a router which routes all spans to both other traces pipelines. This setup makes it possible to calculate span metrics for all spans while applying sampling to the traces that are exported.

setup/otel/getting-started.md

@@ -4,19 +4,33 @@ description: SUSE Observability
 
 # Getting Started with Open Telemetry
 
-![Open Telemetry collector and 2 instrumented applications sending metrics and traces to SUSE Observability](/.gitbook/assets/otel/open-telemetry.svg)
+To get started we'll setup monitoring for:
 
-SUSE Observability supports [Open Telemetry](https://opentelemetry.io/docs/what-is-opentelemetry/). Open Telemetry is a set of standardized protocols and an open-source framework to collect, transform and ship telemetry data such as traces, metrics and logs. Open telemetry supports a wide variety of programming languages and platforms. 
+* An application / workload running in cluster A
+* The Open Telemetry collector running near the observed application(s), so in cluster A, and sending the data to SUSE Observability
+* Using SUSE Observability running in cluster B, or SUSE Cloud Observability
 
-SUSE Observability has support for both metrics and traces and adds the Open Telemetry metrics and traces to the (Kubernetes) topology data that is provided by the SUSE Observability agent. Therefore it is still needed to also install the SUSE Observability agent. Support for logs and using Open Telemetry without the SUSE Observability agent is coming soon.
+DIAGRAM...
 
-Open Telemetry consists of several different components. For usage with SUSE Observability, the [SDKs](./languages/README.md) to instrument your application and the [Open Telemetry collector](./collector.md) are the most important parts. We'll show how to configure both for usage with SUSE Observability.
+## Install the Open Telemetry collector
 
-If your application is already instrumented with Open Telemetry or with any other library that is supported by Open Telemetry, like Jaeger or Zipkin, the collector can be used to ship that data to SUSE Observability and no additional instrumentation is needed.
+First we'll install the collector in cluster A. It handles several tasks:
 
-SUSE Observability requires the collector to be configured with specific processors and authentication to make sure all data used by SUSE Observability is available.
+* Enrich collected data with Kubernetes attributes
+* Sampling of traces
+* Forward the data to SUSE Observability, including authentication using the API key
 
-## References
+To configure the collector you'll need the OTLP or OTLP over HTTP endpoint of SUSE Observability to be securely accessible. The SUSE Observability Helm chart allows you to set that up via an ingress configuration. If you didn't do that during installation now is the time to [add that ingress configuration](/setup/install-stackstate/kubernetes_openshift/ingress.md#configure-ingress-rule-for-open-telemetry). If you're using SUSE Cloud Observability these are the applicable URLs:
+* https://otel-<your-suse-observabillity>.app.stackstate.com - For the OTLP protocol
+* https://otel-http-<your-suse-observabillity>.app.stackstate.com - For OTLP over HTTP
 
-* [Open Telemetry collector](https://opentelemetry.io/docs/collector/) on the Open Telemetry documentation
-* [SDKs to instrument your application](https://opentelemetry.io/docs/languages/) on the Open Telemetry documentation
+Follow the steps [here](collector.md) to get it up and running. 
+
+## Collect telemetry data from your application
+
+The common way to collect telemetry data is to instrument your application using the Open Telemetry SDK's. We've documented some quick start guides for a few languages, but there are many more:
+* [Java](languages/java.md)
+* [.NET](languages/dot-net.md)
+* [Node.js](languages/node.js.md)
+
+For other languages follow the documentation on [opentelemetry.io](https://opentelemetry.io/docs/languages/) and make sure to configure the SDK exporter to ship data to the collector you just installed by following [these instructions](languages/sdk-exporter-config.md).

setup/otel/overview.md

@@ -14,8 +14,6 @@ The recommended setup for usage with SUSE Observability, is to instrument applic
 
 Follow the [getting started](./getting-started.md) guide to set up everything such that it works best with SUSE Observability.
 
-
-
 ## References
 
 * [Open Telemetry collector](https://opentelemetry.io/docs/collector/) on the Open Telemetry documentation