eclipse-che · gtrivedi88 · Jul 7, 2026
@@ -11,6 +11,7 @@ nav:
   - modules/upgrade/nav.adoc
   - modules/secure/nav.adoc
   - modules/optimize/nav.adoc
+  - modules/observe/nav.adoc
   - modules/administration-guide/nav.adoc
   - modules/extensions/nav.adoc
   - modules/glossary/nav.adoc

@@ -21,13 +21,6 @@
 *** xref:configuring-workspaces-nodeselector.adoc[]
 *** xref:configuring-allowed-urls-for-cloud-development-environments.adoc[]
 *** xref:enabling-container-run-capabilities.adoc[]
-** xref:configuring-observability.adoc[]
-**** xref:the-woopra-telemetry-plugin.adoc[]
-**** xref:creating-a-telemetry-plugin.adoc[]
-*** xref:configuring-server-logging.adoc[]
-*** xref:collecting-logs-using-chectl.adoc[]
-**** xref:monitoring-the-dev-workspace-operator.adoc[]
-**** xref:monitoring-che.adoc[]
 ** xref:configuring-networking.adoc[]
 *** xref:configuring-network-policies.adoc[]
 *** xref:configuring-che-hostname.adoc[]

@@ -20,7 +20,7 @@ Common tasks include:
 * Configure the `CheCluster` custom resource. See xref:administration-guide:understanding-the-checluster-custom-resource.adoc[].
 * Set up OAuth for Git providers. See xref:administration-guide:configuring-oauth-for-git-providers.adoc[].
 * Upgrade to the latest version. See xref:administration-guide:upgrading-che.adoc[].
-* Monitor metrics and logs. See xref:administration-guide:configuring-observability.adoc[].
+* Monitor metrics and logs. See xref:observe:configuring-observability.adoc[].
 
 == Developer
 

@@ -0,0 +1,8 @@
+.Observe
+* xref:configuring-observability.adoc[]
+* xref:monitoring-che.adoc[]
+* xref:monitoring-the-dev-workspace-operator.adoc[]
+* xref:configuring-server-logging.adoc[]
+* xref:collecting-logs-using-chectl.adoc[]
+* xref:the-woopra-telemetry-plugin.adoc[]
+* xref:creating-a-telemetry-plugin.adoc[]
@@ -1,13 +1,13 @@
 :_content-type: REFERENCE
 :description: Collecting logs using {prod-cli}
 :keywords: administration-guide, collecting-logs-using-chectl
-:navtitle: Collecting logs using {prod-cli}
+:navtitle: Collect logs with {prod-cli}
 :page-aliases: .:collecting-logs-using-chectl.adoc
 
 [id="collecting-logs-using-{prod-cli}"]
-= Collecting logs using {prod-cli}
+= Collect logs with {prod-cli}
 
-An installation of {prod} consists of several containers running in the {orch-name} cluster. While it is possible to manually collect logs from each running container, `{prod-cli}` provides commands which automate the process.
+The `{prod-cli}` management tool provides commands to collect {prod-short} logs for troubleshooting and diagnostics. These commands automate log collection from the multiple containers that comprise a {prod} installation in the {orch-name} cluster.
 
 Following commands are available to collect {prod} logs from the {orch-name} cluster using the `{prod-cli}` tool:
 
@@ -29,7 +29,7 @@ When run, `{prod-cli} server:logs` prints a message in the console specifying th
 {prod} logs will be available in '/tmp/chectl-logs/1648575098344'
 ----
 +
-If {prod} is installed in a non-default {orch-namespace}, `{prod-cli} server:logs` requires the `-n <NAMESPACE>` paremeter, where `<NAMESPACE>` is the {platforms-namespace} in which {prod} was installed. For example, to get logs from {prod-short} in the `my-namespace` {orch-namespace}, use the command
+If {prod} is installed in a non-default {orch-namespace}, `{prod-cli} server:logs` requires the `-n <NAMESPACE>` parameter, where `<NAMESPACE>` is the {platforms-namespace} in which {prod} was installed. For example, to get logs from {prod-short} in the `my-namespace` {orch-namespace}, use the command
 +
 [source,shell,subs="+attributes"]
 ----

@@ -1,11 +1,11 @@
 :_content-type: ASSEMBLY
 :description: Configuring observability
 :keywords: administration-guide, configuring, observability, logs, monitoring
-:navtitle: Configuring observability
+:navtitle: What you can observe about {prod-short}
 :page-aliases: .:retrieving-che-logs.adoc, .:viewing-kubernetes-events.adoc, viewing-kubernetes-events.adoc, .:viewing-plug-in-broker-logs.adoc, viewing-plug-in-broker-logs.adoc, retrieving-che-logs.adoc, viewing-che-server-logs.adoc, viewing-external-service-logs.adoc, che-theia-workspaces.adoc
 
 [id="configuring-observability"]
-= Configuring observability
+= What you can observe about {prod-short}
 
 To configure {prod-short} observability features, see:
 

@@ -1,15 +1,15 @@
 :_content-type: ASSEMBLY
 :description: Configuring server logging
 :keywords: administration-guide, configuring-server-logging
-:navtitle: Configuring server logging
+:navtitle: How server logging works
 :page-aliases: .:configuring-server-logging.adoc
 
-[id="configuring-sever-logging"]
-= Configuring server logging
+[id="configuring-server-logging"]
+= How server logging works
 
-It is possible to fine-tune the log levels of individual loggers available in the {prod-short} server.
+Fine-tune the log levels of individual loggers available in the {prod-short} server to control output verbosity and isolate issues during troubleshooting.
 
-The log level of the whole {prod-short} server is configured globally using the `cheLogLevel` configuration property of the Operator. See xref:checluster-custom-resource-fields-reference.adoc[]. 
+The log level of the whole {prod-short} server is configured globally using the `cheLogLevel` configuration property of the Operator. See xref:administration-guide:checluster-custom-resource-fields-reference.adoc[]. 
 To set the global log level in installations not managed by the Operator, specify the `CHE_LOG_LEVEL` environment variable in the `che`
 ConfigMap.
 

@@ -1,11 +1,11 @@
 :_content-type: REFERENCE
 :description: Creating a telemetry plugin
 :keywords: extensions, telemetry
-:navtitle: Creating a telemetry plugin
+:navtitle: Build a custom telemetry plugin
 :page-aliases: extensions:creating-a-telemetry-plug-in.adoc
 
 [id="creating-a-telemetry-plugin"]
-= Creating a telemetry plugin
+= Build a custom telemetry plugin
 
 This section shows how to create an `AnalyticsManager` class that extends link:https://github.com/che-incubator/che-workspace-telemetry-client/blob/master/backend-base/src/main/java/org/eclipse/che/incubator/workspace/telemetry/base/AbstractAnalyticsManager.java[`AbstractAnalyticsManager`] and implements the following methods:
 
@@ -386,7 +386,7 @@ image::creating-a-telemetry-plugin/devworkspace_telemetry_plugin.png[{devworkspa
 
 Set the telemetry plugin as a default plugin. Default plugins are applied on {devworkspace} startup for new and existing {devworkspace}s.
 
-* Configure the `CheCluster` Custom Resource. See xref:using-the-cli-to-configure-the-checluster-custom-resource.adoc[].
+* Configure the `CheCluster` Custom Resource. See xref:administration-guide:using-the-cli-to-configure-the-checluster-custom-resource.adoc[].
 +
 ----
 spec:
@@ -402,7 +402,7 @@ spec:
 
 .Additional resources
 
-* xref:using-the-cli-to-configure-the-checluster-custom-resource.adoc[].
+* xref:administration-guide:using-the-cli-to-configure-the-checluster-custom-resource.adoc[].
 
 .Verification steps
 

@@ -1,13 +1,13 @@
 :_content-type: ASSEMBLY
 :description: Monitoring {prod-short} Server
 :keywords: administration-guide, monitoring-che
-:navtitle: Monitoring {prod-short} Server
+:navtitle: Monitor {prod-short} server
 :page-aliases: .:monitoring-che.adoc, .:tracing-che.adoc, tracing-che.adoc
 
 [id="monitoring-{prod-id-short}"]
-= Monitoring {prod-short} Server
+= Monitor {prod-short} server
 
-You can configure {prod-short} to expose JVM metrics such as JVM memory and class loading for {prod-short} Server.
+The {prod-short} server exposes JVM metrics such as memory usage and class loading on port `8087` on the `/metrics` endpoint. Monitoring these metrics helps administrators identify performance bottlenecks and plan server capacity.
 
 include::partial$proc_enabling-and-exposing-che-metrics.adoc[leveloffset=+1]
 

@@ -1,14 +1,14 @@
 :_content-type: ASSEMBLY
 :description: Monitoring the {devworkspace} Operator
 :keywords: administration-guide, monitoring-the-dev-workspace-operator
-:navtitle: Monitoring the {devworkspace} Operator
+:navtitle: Monitor the {devworkspace} Operator
 :page-aliases: .:monitoring-the-dev-workspace-operator.adoc
 
 
 [id="monitoring-the-dev-workspace-operator"]
-= Monitoring the {devworkspace} Operator
+= Monitor the {devworkspace} Operator
 
-You can configure the OpenShift in-cluster monitoring stack to scrape metrics exposed by the {devworkspace} Operator.
+The {devworkspace} Operator exposes workspace startup, failure, and performance metrics on port `8443` on the `/metrics` endpoint of the `devworkspace-controller-metrics` Service. The {orch-name} in-cluster monitoring stack can scrape these metrics to help administrators track workspace health and diagnose startup failures.
 
 include::partial$con_collecting-dev-workspace-operator-metrics-with-prometheus.adoc[leveloffset=+1]
 

@@ -1,12 +1,12 @@
 :_content-type: PROCEDURE
 :description: The Woopra telemetry plugin
 :keywords: extensions, telemetry
-:navtitle: The Woopra telemetry plugin
+:navtitle: Configure the Woopra telemetry plugin
 :page-aliases: extensions:the-woopra-telemetry-plug-in.adoc
 
 [id="the-woopra-telemetry-plugin"]
 
-= The Woopra telemetry plugin
+= Configure the Woopra telemetry plugin
 
 The link:https://github.com/che-incubator/devworkspace-telemetry-woopra-plugin[Woopra Telemetry Plugin] is a plugin built to send telemetry from a {prod} installation to Segment and Woopra.
 This plugin is used by link:https://workspaces.openshift.com[Eclipse Che hosted by Red Hat], but any {prod} deployment can take advantage of this plugin.
@@ -22,9 +22,9 @@ To enable the Woopra plugin on the {prod} installation:
 
 .Procedure
 
-* Deploy the `plugin.yaml` devfile v2 file to an HTTP server with the environment variables set correctly.
+. Deploy the `plugin.yaml` devfile v2 file to an HTTP server with the environment variables set correctly.
 
-. Configure the `CheCluster` Custom Resource. See xref:using-the-cli-to-configure-the-checluster-custom-resource.adoc[].
+. Configure the `CheCluster` Custom Resource. See xref:administration-guide:using-the-cli-to-configure-the-checluster-custom-resource.adoc[].
 +
 [source,yaml]
 ----
@@ -42,4 +42,4 @@ spec:
 
 * xref:install:using-chectl-to-configure-the-checluster-custom-resource-during-installation.adoc[]
 
-* xref:using-the-cli-to-configure-the-checluster-custom-resource.adoc[]
+* xref:administration-guide:using-the-cli-to-configure-the-checluster-custom-resource.adoc[]
@@ -2,11 +2,10 @@
 :page-aliases: .:proc_collecting-che-metrics-with-prometheus.adoc
 
 [id="collecting-{prod-id-short}-metrics-with-prometheus"]
-= Verifying {prod-short} Server metrics collection with Prometheus
+= Verify {prod-short} server metrics with Prometheus
 
 [role="_abstract"]
-The {prod-operator} automatically creates and reconciles the required Prometheus resources (ServiceMonitor, Role, and RoleBinding) and configures {orch-namespace} labeling for monitoring {prod-short} Server JVM metrics.
-No manual configuration is required.
+Verify that {prod-short} Server JVM metrics are available in Prometheus. The {prod-operator} automatically creates and reconciles the required Prometheus resources (ServiceMonitor, Role, and RoleBinding) and configures {orch-namespace} labeling.
 
 .Verification
 

@@ -1,11 +1,10 @@
 :page-aliases: .:proc_collecting-dev-workspace-operator-metrics-with-prometheus.adoc
 
 [id="collecting-dev-workspace-operator-metrics-with-prometheus"]
-= Verifying {devworkspace} Operator metrics collection with Prometheus
+= Verify {devworkspace} Operator metrics with Prometheus
 
 [role="_abstract"]
-The {prod-operator} automatically creates and reconciles the required Prometheus resources (ServiceMonitor, Role, and RoleBinding) and configures {orch-namespace} labeling for monitoring the {devworkspace} Operator.
-No manual configuration is required.
+Verify that {devworkspace} Operator metrics are available in Prometheus. The {prod-operator} automatically creates and reconciles the required Prometheus resources (ServiceMonitor, Role, and RoleBinding) and configures {orch-namespace} labeling.
 
 .Verification
 

@@ -1,6 +1,6 @@
 // configuring-server-logging
 
 [id="logger-naming"]
-= Logger naming
+= How logger names work
 
 The names of the loggers follow the class names of the internal server classes that use those loggers.
@@ -0,0 +1,31 @@
+// configuring-server-logging
+
+[id="logging-http-traffic"]
+= Log HTTP traffic
+
+[role="_abstract"]
+Log the HTTP traffic between the {prod-short} server and the API server of the {kubernetes} or {orch-name} cluster to troubleshoot communication issues and debug API errors.
+
+.Prerequisites
+
+* An active `{orch-cli}` session with administrative permissions to the destination {orch-name} cluster. See {orch-cli-link}.
+
+.Procedure
+
+. Configure the `CheCluster` Custom Resource. See xref:administration-guide:using-the-cli-to-configure-the-checluster-custom-resource.adoc[].
++
+[source,yaml]
+----
+spec:
+  components:
+    cheServer:
+      extraProperties:
+        CHE_LOGGER_CONFIG: "che.infra.request-logging=TRACE"
+----
+
+.Additional resources
+
+* xref:install:using-chectl-to-configure-the-checluster-custom-resource-during-installation.adoc[]
+
+* xref:administration-guide:using-the-cli-to-configure-the-checluster-custom-resource.adoc[]
+
@@ -1,11 +1,18 @@
 // configuring-server-logging
 
 [id="configuring-log-levels"]
-= Configuring log levels
+= Configure log levels
+
+[role="_abstract"]
+Configure the log levels of individual loggers in the {prod-short} server using the `CHE_LOGGER_CONFIG` environment variable to control log verbosity and simplify troubleshooting.
+
+.Prerequisites
+
+* An active `{orch-cli}` session with administrative permissions to the destination {orch-name} cluster. See {orch-cli-link}.
 
 .Procedure
 
-* Configure the `CheCluster` Custom Resource. See xref:using-the-cli-to-configure-the-checluster-custom-resource.adoc[].
+. Configure the `CheCluster` Custom Resource. See xref:administration-guide:using-the-cli-to-configure-the-checluster-custom-resource.adoc[].
 +
 [source,yaml,subs="+attributes,+quotes"]
 ----
@@ -34,5 +41,5 @@ spec:
 
 * xref:install:using-chectl-to-configure-the-checluster-custom-resource-during-installation.adoc[]
 
-* xref:using-the-cli-to-configure-the-checluster-custom-resource.adoc[]
+* xref:administration-guide:using-the-cli-to-configure-the-checluster-custom-resource.adoc[]
 
@@ -0,0 +1,32 @@
+// monitoring-{prod-id-short}
+
+[id="enabling-and-exposing-{prod-id-short}-metrics"]
+= Enable {prod-short} server metrics
+
+{prod-short} exposes the JVM metrics on port `8087` of the `che-host` Service. Configure this behavior to support performance monitoring and capacity planning.
+
+.Prerequisites
+
+* An active `{orch-cli}` session with administrative permissions to the destination {orch-name} cluster. See {orch-cli-link}.
+
+.Procedure
+
+. Configure the `CheCluster` Custom Resource. See xref:administration-guide:using-the-cli-to-configure-the-checluster-custom-resource.adoc[].
++
+[source,yaml,subs="+attributes,+quotes"]
+----
+spec:
+  components:
+    metrics:
+      enable: __<boolean>__ <1>
+----
+<1> `true` to enable, `false` to disable.
+
+.Verification
+
+* Verify the metrics endpoint is accessible:
++
+[source,terminal,subs="+attributes"]
+----
+$ {orch-cli} get service che-host -n {prod-namespace} -o jsonpath='{.spec.ports[?(@.port==8087)]}'
+----
@@ -1,13 +1,13 @@
 // monitoring-{prod-id-short}
 
 [id="viewing-{prod-id-short}-metrics-on-grafana-dashboards"]
-= Viewing {prod-short} Server from an OpenShift web console dashboard
+= View {prod-short} Server from an {orch-name} web console dashboard
 
-After configuring the in-cluster Prometheus instance to collect {prod-short} Server JVM metrics, you can view the metrics on a custom dashboard in the *Administrator* perspective of the OpenShift web console.
+View {prod-short} Server JVM metrics on a custom dashboard in the *Administrator* perspective of the {orch-name} web console. This dashboard helps you identify performance bottlenecks and monitor server health.
 
 .Prerequisites
 
-* Your organization's instance of {prod-short} is installed and running in Red Hat OpenShift.
+* {prod-short} is installed and running on a Red Hat OpenShift cluster.
 
 * An active `oc` session with administrative permissions to the destination OpenShift cluster. See link:https://docs.openshift.com/container-platform/{ocp4-ver}/cli_reference/openshift_cli/getting-started-cli.html[Getting started with the CLI].