From 7b324f1c7f6cca0432be7bc8f46433b4471e313f Mon Sep 17 00:00:00 2001
From: Benedikt Bongartz <bongartz@klimlive.de>
Date: Thu, 13 Feb 2025 14:38:39 +0100
Subject: [PATCH] observability: add README.md

Signed-off-by: Benedikt Bongartz <bongartz@klimlive.de>
---
 observability/README.md | 51 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)
 create mode 100644 observability/README.md

diff --git a/observability/README.md b/observability/README.md
new file mode 100644
index 000000000..27cbef8c6
--- /dev/null
+++ b/observability/README.md
@@ -0,0 +1,51 @@
+# ARO dev observability
+
+## Tracing
+
+ARO frontend, cluster service and other components are instrumented with the OpenTelemetry SDK.
+In the current development environment, there is no possibility to inspect traces.
+
+### Deploy Jaeger all-in-one testing backend
+
+#### Install
+```
+make deploy
+```
+
+After installation, the `jaeger` service becomes available in the `observability` namespace. We can access the UI using `kubectl port-forward`:
+
+```
+kubectl port-forward -n observability svc/jaeger 16686:16686
+```
+
+The `observability` namespace contains a second service named `ingest` which accepts otlp via gRPC and HTTP.
+
+#### Configure instances
+
+The export of the trace information is configured via environment variables. Existing deployments can be patched as follows:
+
+```diff
++        env:
++        - name: OTEL_EXPORTER_OTLP_ENDPOINT
++          value: https://<service>.<namespace>:4318
++        - name: OTEL_TRACES_EXPORTER
++          value: otlp
+```
+
+You can use:
+
+```
+make patch-frontend
+make patch-clusteservice
+```
+
+
+### Correlate with ARM requests
+
+The following span attributes are set in the root span and propagated to the next service via baggage: 
+
+```
+aro.correlation.id
+aro.request.id
+aro.client.request.id
+```