STAC-23444: add page on ui extension troubleshooting (#109)

* STAC-23444: add page on ui extension troubleshooting

Co-authored-by: akashraj4261 <[email protected]>

Author: fvlankvelt

docs/latest/modules/en/nav.adoc

@@ -111,6 +111,7 @@
 *** xref:setup/install-stackstate/troubleshooting.adoc[Troubleshooting]
 **** xref:setup/install-stackstate/advanced-troubleshooting.adoc[Advanced Troubleshooting]
 **** xref:setup/install-stackstate/support-package-logs.adoc[Support Package (Logs)]
+**** xref:setup/install-stackstate/extension-troubleshooting.adoc[UI Extension Troubleshooting]
 ** Configure SUSE Observability
 *** xref:setup/configure-stackstate/slack-notifications.adoc[Slack notifications]
 *** xref:setup/configure-stackstate/email-notifications.adoc[E-mail notifications]

docs/latest/modules/en/pages/k8s-suse-rancher-prime.adoc

@@ -371,7 +371,8 @@ sts service-token create --name suse-observability-extension --roles stackstate-
 
 | 2.x.x
 | 2.10 +
-2.11
+2.11 +
+2.12
 |===
 
 == Installing the SUSE Observability Agent
@@ -436,3 +437,7 @@ To enable Single sign-on with your own authentication provider please xref:/setu
 . After the extensions are installed, the SUSE Observability UI opens in the same tab as the Rancher UI.
  ** You can use shift-click to open in a new tab, this will become the default behaviour
 . Be aware upgrading or downgrading from HA to NON-HA and vice-versa is not yet supported.
+
+== Troubleshooting
+
+For any queries regarding the installation of the UI extension for Observability, see xref:/setup/install-stackstate/extension-troubleshooting.adoc[Extension troubleshooting guide].

docs/latest/modules/en/pages/setup/install-stackstate/extension-troubleshooting.adoc

@@ -0,0 +1,33 @@
+= Extension Troubleshooting
+:revdate: 2025-11-03
+:page-revdate: {revdate}
+:description: SUSE Observability Self-hosted
+
+This section provides troubleshooting steps for any interoperability issues between {stackstate-product-name} and the Rancher UI extension.
+
+== Collect a HAR (Http ARchive)
+
+Http ARchive collects details on requests that are sent by the browser to Rancher and {stackstate-product-name}.  It also logs the responses received.
+This archive is specific to the page/browser tab with the error.  It does not need access to the backing Rancher or {stackstate-product-name} instances (though their logs may be useful at a later stage).
+
+* Open the *Network* tab in the "Developer Tools" panel.  You can access this by using `F12`.  The network tab shows a log of all requests that are made.
+* Clear the log and do a (hard) refresh of the page that is displaying the problematic behavior.
+* There should now be a large number of requests to both Rancher and SUSE Observability visible.
+* Export/Download/Save the HAR - different browsers use different names here.
+
+== Cluster is unobserved
+
+For the cluster health status to be visible in Rancher, there needs to be alignment between these configurations:
+
+* The (display) name of the cluster in the Rancher UI.
+* The `stackstate.cluster.name` set on the agent deployed on the cluster
+* The cluster name in the configuration of the Kubernetes stackpack in SUSE Observability
+
+A mismatch will tend to show up as "no data received" in the cluster overview in Rancher.
+
+== Connection failed
+
+The configuration for SUSE Observability may sometimes not yield a valid connection in the Rancher UI due to the following reasons:
+
+* The Rancher host is not configured as an allowed origin for SUSE Observability.  You can fix this by adding it to the `stackstate.allowedOrigins` list in the helm values, or by passing `--set stackstate.allowedOrigins={"https://<rancher-url>"}` to the deployment command.
+* SUSE Observability is not accessible from the browser. For example, the root certificate has not been installed.