eclipse-che · gtrivedi88 · Jul 7, 2026
@@ -13,6 +13,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:
 * Set up OAuth for Git providers. See xref:administration-guide:configuring-oauth-for-git-providers.adoc[].
 * Control workspace start times with image caching. See xref:optimize:caching-images-for-faster-workspace-start.adoc[].
 * Upgrade to the latest version. See xref:upgrade: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 tasks and guides
 

@@ -6,3 +6,4 @@
 *** xref:authenticating-with-openshift-connector-from-che.adoc[]
 *** xref:creating-components-with-openshift-connector-in-che.adoc[]
 *** xref:connecting-source-code-from-github-to-a-openshift-component-using-openshift-connector.adoc[]
+* xref:creating-a-telemetry-plugin.adoc[]
@@ -2,7 +2,7 @@
 :description: Creating a telemetry plugin
 :keywords: extensions, telemetry
 :navtitle: Creating a telemetry plugin
-:page-aliases: extensions:creating-a-telemetry-plug-in.adoc
+:page-aliases: administration-guide:creating-a-telemetry-plugin.adoc, observe:creating-a-telemetry-plugin.adoc, extensions:creating-a-telemetry-plug-in.adoc
 
 [id="creating-a-telemetry-plugin"]
 = Creating a telemetry plugin
@@ -386,13 +386,13 @@ 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:
   devEnvironments:
     defaultPlugins:
-    - editor: eclipse/che-theia/next     <1>
+    - editor: che-incubator/che-code/latest     <1>
       plugins:                           <2>
       - 'http://apache-che.apps-crc.testing/plugin.yaml'
 ----
@@ -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
 

@@ -0,0 +1,9 @@
+.Platform monitoring and telemetry
+* xref:configuring-observability.adoc[]
+* xref:monitoring-che.adoc[]
+* xref:monitoring-the-dev-workspace-operator.adoc[]
+* xref:the-woopra-telemetry-plugin.adoc[]
+
+.Server logging and diagnostics
+* xref:configuring-server-logging.adoc[]
+* xref:collecting-logs-using-chectl.adoc[]
@@ -1,15 +1,15 @@
 :_content-type: REFERENCE
-:description: Collecting logs using {prod-cli}
+:description: Collect logs with {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:
+The following commands collect {prod} logs from the {orch-name} cluster:
 
 `{prod-cli} server:logs`:: 
 Collects existing {prod} server logs and stores them in a directory on the local machine.
@@ -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"]
 ----

@@ -0,0 +1,47 @@
+:_content-type: CONCEPT
+:description: What you can observe about {prod-short}
+:keywords: observability, metrics, logs, monitoring, telemetry
+: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"]
+= What you can observe about {prod-short}
+
+{prod-short} exposes metrics, logs, and telemetry data that help you monitor platform health, diagnose issues, and track workspace usage.
+
+{prod-short} provides three categories of observability data:
+
+*Metrics*
+
+The {prod-short} server exposes JVM metrics (memory usage, classloading, garbage collection) on port `8087` via the `che-host` Service `/metrics` endpoint. The {devworkspace} Operator exposes workspace startup, failure, and performance metrics on port `8443` via the `devworkspace-controller-metrics` Service `/metrics` endpoint. The {orch-name} in-cluster monitoring stack (Prometheus) scrapes both endpoints. The {prod-short} Operator automatically creates the required ServiceMonitor, Role, and RoleBinding resources. You can view these metrics on custom dashboards in the {orch-name} web console.
+
+*Logs*
+
+The {prod-short} server uses configurable log levels for individual loggers. You can increase verbosity for specific components to isolate issues, log HTTP traffic between {prod-short} and the {orch-name} API server, and collect diagnostic logs with the `{prod-cli}` command-line tool. For log configuration procedures, see xref:configuring-server-logging.adoc[].
+
+*Telemetry*
+
+Workspace activity events (start, stop, editor actions) can be sent to Segment and Woopra by using the built-in Woopra telemetry plugin, or to a custom analytics backend by using a telemetry plugin you build yourself. For details on building a custom plugin, see xref:extensions:creating-a-telemetry-plugin.adoc[].
+
+[NOTE]
+====
+{prod-short} does not include built-in alerting rules. To receive alerts when metrics exceed thresholds, configure Prometheus alerting rules for the metrics described in this guide.
+====
+
+.What do you need to observe?
+[cols="1,2", options="header"]
+|===
+| Goal | Description
+
+| xref:monitoring-che.adoc[Monitor server metrics]
+| Enable Prometheus metrics for the {prod-short} server and view JVM dashboards.
+
+| xref:monitoring-the-dev-workspace-operator.adoc[Monitor workspace metrics]
+| Enable Prometheus metrics for the {devworkspace} Operator and view workspace dashboards.
+
+| xref:configuring-server-logging.adoc[Configure logging]
+| Control server log verbosity, log HTTP traffic, and collect diagnostic logs with {prod-cli}.
+
+| xref:the-woopra-telemetry-plugin.adoc[Configure telemetry]
+| Send workspace activity data to Segment and Woopra with a CheCluster CR configuration change.
+|===
@@ -0,0 +1,22 @@
+:_content-type: ASSEMBLY
+:description: How server logging works
+:keywords: administration-guide, configuring-server-logging
+:navtitle: How server logging works
+:page-aliases: .:configuring-server-logging.adoc
+
+[id="configuring-server-logging"]
+= How server logging works
+
+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: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.
+
+You can configure the log levels of individual loggers in the {prod-short} server with the `CHE_LOGGER_CONFIG` environment variable.
+
+include::partial$proc_configuring-server-logging.adoc[leveloffset=+1]
+
+include::partial$con_logger-naming.adoc[leveloffset=+1]
+
+include::partial$proc_logging-http-traffic.adoc[leveloffset=+1]
@@ -1,13 +1,13 @@
 :_content-type: ASSEMBLY
-:description: Monitoring {prod-short} Server
+:description: What {prod-short} server metrics reveal
 :keywords: administration-guide, monitoring-che
-:navtitle: Monitoring {prod-short} Server
+:navtitle: What {prod-short} server metrics reveal
 :page-aliases: .:monitoring-che.adoc, .:tracing-che.adoc, tracing-che.adoc
 
 [id="monitoring-{prod-id-short}"]
-= Monitoring {prod-short} Server
+= What {prod-short} server metrics reveal
 
-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
+:description: What {devworkspace} Operator metrics reveal
 :keywords: administration-guide, monitoring-the-dev-workspace-operator
-:navtitle: Monitoring the {devworkspace} Operator
+:navtitle: What {devworkspace} Operator metrics reveal
 :page-aliases: .:monitoring-the-dev-workspace-operator.adoc
 
 
 [id="monitoring-the-dev-workspace-operator"]
-= Monitoring the {devworkspace} Operator
+= What {devworkspace} Operator metrics reveal
 
-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,14 +1,14 @@
 :_content-type: PROCEDURE
-:description: The Woopra telemetry plugin
+:description: Configure 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.
+The Woopra Telemetry Plugin sends 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.
 There are no dependencies other than a valid Woopra domain and Segment Write key.
 The devfile v2 for the plugin, link:https://raw.githubusercontent.com/che-incubator/devworkspace-telemetry-woopra-plugin/main/plugin.yaml[plugin.yaml], has four environment variables that can be passed to the plugin:
@@ -20,18 +20,24 @@ The devfile v2 for the plugin, link:https://raw.githubusercontent.com/che-incuba
 
 To enable the Woopra plugin on the {prod} installation:
 
+.Prerequisites
+
+* An active `{orch-cli}` session with administrative permissions to the destination {orch-name} cluster. See {orch-cli-link}.
+
+* You have a valid Woopra domain and Segment Write key.
+
 .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]
 ----
 spec:
   devEnvironments:
     defaultPlugins:
-    - editor: eclipse/che-theia/next     <1>
+    - editor: che-incubator/che-code/latest     <1>
       plugins:                           <2>
       - 'https://your-web-server/plugin.yaml'
 ----
@@ -42,4 +48,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.