This is an automated email from the ASF dual-hosted git repository.
ArafatKhan2198 pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/ozone-site.git
The following commit(s) were added to refs/heads/master by this push:
new 94c6674d87 HDDS-15964. Restructure Recon docs: convert Web UI monolith
to folder, move Capacity inside. (#508).
94c6674d87 is described below
commit 94c6674d8736621582955703454efa27fdb416e9
Author: Arafat2198 <[email protected]>
AuthorDate: Fri Jul 24 20:44:28 2026 +0530
HDDS-15964. Restructure Recon docs: convert Web UI monolith to folder, move
Capacity inside. (#508).
Co-authored-by: Claude <[email protected]>
---
.../04-performance/11-storage-capacity-planning.md | 2 +-
.../09-observability/02-recon/01-recon-web-ui.md | 276 ---------------------
.../02-recon/01-recon-web-ui/01-overview.mdx | 158 ++++++++++++
.../02-capacity.mdx} | 2 +-
.../02-recon/01-recon-web-ui/README.mdx | 46 ++++
.../{ => 01-recon-web-ui}/data_node_insights.png | Bin
.../{ => 01-recon-web-ui}/ozone_capacity.png | Bin
.../{ => 01-recon-web-ui}/ozone_recon_overview.png | Bin
.../{ => 01-recon-web-ui}/pending_deletion.png | Bin
.../{ => 01-recon-web-ui}/service_capacity.png | Bin
.../02-recon/02-recon-rest-api.mdx | 4 +
11 files changed, 210 insertions(+), 278 deletions(-)
diff --git
a/docs/05-administrator-guide/02-configuration/04-performance/11-storage-capacity-planning.md
b/docs/05-administrator-guide/02-configuration/04-performance/11-storage-capacity-planning.md
index e5a64907a8..87d06ccac4 100644
---
a/docs/05-administrator-guide/02-configuration/04-performance/11-storage-capacity-planning.md
+++
b/docs/05-administrator-guide/02-configuration/04-performance/11-storage-capacity-planning.md
@@ -67,7 +67,7 @@ Administrators can inspect the actual and "SCM-usable" space
using the Ozone CLI
### 1. Recon Web UI
-The [Recon cluster capacity
guide](../../operations/observability/recon/recon-capacity-distribution)
describes how to monitor cluster-wide storage:
+The [Recon cluster capacity
guide](../../operations/observability/recon/recon-web-ui/capacity) describes
how to monitor cluster-wide storage:
- **Dashboards**: View aggregated capacity, used space, and remaining space
for the entire cluster.
- **Datanodes Page**: Sort Datanodes by utilization to quickly identify nodes
that are approaching their "Full" threshold.
diff --git
a/docs/05-administrator-guide/03-operations/09-observability/02-recon/01-recon-web-ui.md
b/docs/05-administrator-guide/03-operations/09-observability/02-recon/01-recon-web-ui.md
deleted file mode 100644
index af1bfb78e2..0000000000
---
a/docs/05-administrator-guide/03-operations/09-observability/02-recon/01-recon-web-ui.md
+++ /dev/null
@@ -1,276 +0,0 @@
----
-sidebar_label: Recon Web UI
----
-
-# Recon Web UI
-
-## Introduction
-
-Apache Ozone Recon is a read-only monitoring and observability service for
Apache Ozone clusters, designed for cluster administrators. Recon aggregates
metadata from Ozone Manager (OM), Storage Container Manager (SCM), and
Datanodes, and exposes this information through a web-based user interface.
-
-Recon does not modify cluster state. It is designed to provide visibility,
diagnostics, and insight into the health and usage of an Ozone cluster.
-
-## Accessing the Recon UI
-
-The Recon UI is available via the Recon HTTP endpoint, typically:
-
-`http://<recon-host>:9888/`
-
-The left navigation panel provides access to all available views:
-
-- Overview
-- Volumes
-- Buckets
-- Datanodes
-- Pipelines
-- Containers
-- Insights
-- OM DB Insights
-- Namespace Usage
-
-Most pages support:
-
-- Automatic refresh
-- Manual refresh
-- Column selection
-- Sorting and filtering
-
-## Overview Page
-
-
-
-The Overview page provides a high-level summary of cluster health and usage.
-
-### Health
-
-Displays overall health indicators for:
-
-- Datanodes
-- Containers
-
-The health status reflects Recon’s aggregated view of SCM and Datanode reports.
-
-### Cluster Capacity
-
-Shows a capacity breakdown using a ring chart:
-
-- Ozone Used: Storage consumed by Ozone keys
-- Non-Ozone Used: Disk usage outside of Ozone
-- Remaining: Free capacity
-- Container Pre-allocated: Space reserved by containers
-
-In newly initialized or empty clusters, values may be zero.
-
-### Summary Counters
-
-Quick counts for:
-
-- Volumes
-- Buckets
-- Keys
-- Pipelines
-- Deleted Containers
-
-These counters help operators confirm overall namespace activity.
-
-### Open Keys and Delete Pending Keys
-
-Displays summary information related to:
-
-- Open keys
-- Keys pending deletion
-- Replicated and unreplicated data sizes
-
-These metrics are useful when diagnosing delayed deletions or space
reclamation issues.
-
-## Volumes Page
-
-
-
-The Volumes page lists all volumes known to the cluster.
-
-### Displayed Information
-
-- Volume name
-- Owner
-- Admin
-- Creation time
-- Modification time
-- Storage quota
-- Namespace capacity usage
-
-### Actions
-
-- Show Buckets: Navigates to buckets within the selected volume
-- Show ACL: Displays access control configuration
-
-This page is commonly used to verify ownership, quotas, and namespace usage at
the volume level.
-
-## Buckets Page
-
-
-
-The Buckets page lists all buckets across all volumes.
-
-### Displayed Information
-
-- Bucket name
-- Volume
-- Owner
-- Versioning status
-- Storage type
-- Bucket layout
-- Creation and modification times
-- Storage capacity usage
-- Namespace capacity usage
-
-An empty table indicates that no buckets exist in the cluster.
-
-This view is useful for auditing bucket configuration and identifying buckets
with high namespace or storage usage.
-
-## Datanodes Page
-
-
-
-The Datanodes page provides detailed status information for each Datanode.
-
-### Displayed Information
-
-- Hostname
-- Health state
-- Operational state (for example, IN_SERVICE)
-- UUID
-- Storage capacity utilization
-- Last heartbeat timestamp
-- Pipeline membership
-- Leader count
-
-This page is commonly used to:
-
-- Detect unhealthy or missing Datanodes
-- Verify heartbeat freshness
-- Inspect Ratis leader distribution
-
-## Pipelines Page
-
-
-
-The Pipelines page displays all SCM-managed pipelines.
-
-### Displayed Information
-
-- Pipeline ID
-- Replication type and factor
-- Pipeline status
-- Number of containers
-- Datanode membership
-- Current leader
-- Last leader election time
-
-Pipeline information is useful for diagnosing container allocation issues and
validating Ratis pipeline health.
-
-## Containers Page
-
-
-
-The Containers page focuses on container health and replication status.
-
-### Highlights
-
-Displays summary counts for:
-
-- Missing containers
-- Under-replicated containers
-- Over-replicated containers
-- Mis-replicated containers
-- Mismatched replicas
-
-### Detailed Views
-
-Each category provides a detailed table showing:
-
-- Container ID
-- Number of keys
-- Actual versus expected replica count
-- Hosting Datanodes
-- Pipeline ID
-- Time since unhealthy state
-
-This page is primarily used for replication and durability diagnostics.
-
-## Insights Page
-
-
-
-The Insights page provides analytical summaries derived from Recon metadata.
-
-### Available Charts
-
-- File size distribution
-- Container size distribution
-
-If no data is present, Recon displays an explicit “No Data” indicator.
-
-These charts become useful once the cluster has active workloads.
-
-## OM DB Insights
-
-
-
-The OM DB Insights section exposes internal Ozone Manager metadata conditions
derived from Recon analysis.
-
-### Available Views
-
-- Container mismatch information
-- Open keys
-- Keys pending deletion
-- Deleted container keys
-- Directories pending deletion
-
-These views are intended for advanced operators and developers investigating
OM metadata behavior or inconsistencies.
-
-## Namespace Usage
-
-
-
-The Namespace Usage page visualizes namespace consumption hierarchically.
-
-### Visualization
-
-A pie chart displays namespace usage by:
-
-- Volume
-- Bucket
-- Directory
-
-Small entities may be visually amplified for readability; exact values are
available in the details panel.
-
-### Entity Details
-
-For the selected entity, Recon displays:
-
-- Entity type
-- Namespace usage
-- Namespace quota
-- Creation and modification time
-- Counts of volumes, buckets, directories, and keys
-
-This view is useful for identifying namespace-heavy tenants and planning quota
usage.
-
-## Limitations
-
-Recon is read-only and cannot be used to modify cluster state.
-
-Recon data freshness depends on metadata synchronization from OM and SCM.
-
-Operational actions must be performed using standard Ozone administrative
tools.
-
-## Summary
-
-Apache Ozone Recon provides:
-
-- Centralized visibility into cluster health
-- Namespace and capacity observability
-- Diagnostics for containers, pipelines, and metadata
-
-Recon is intended to complement, not replace, existing Ozone administrative
workflows.
diff --git
a/docs/05-administrator-guide/03-operations/09-observability/02-recon/01-recon-web-ui/01-overview.mdx
b/docs/05-administrator-guide/03-operations/09-observability/02-recon/01-recon-web-ui/01-overview.mdx
new file mode 100644
index 0000000000..ea0f4e43e2
--- /dev/null
+++
b/docs/05-administrator-guide/03-operations/09-observability/02-recon/01-recon-web-ui/01-overview.mdx
@@ -0,0 +1,158 @@
+---
+sidebar_label: Overview
+---
+
+# Recon UI — Overview Page
+
+
+
+## 1. Page Overview
+
+The **Overview** page is the Recon landing page. It gives you an at-a-glance
+summary of the health and size of your Ozone cluster: datanode and container
+health, total storage capacity and how it is being used, counts of the main
+objects (volumes, buckets, keys, pipelines, containers), and summaries of open
+and delete-pending keys.
+
+It is a read-only dashboard, and every card links to a more detailed page, so
+the Overview is the usual starting point for any investigation.
+
+## 2. When to Use This Page
+
+- As your first stop after logging in, to confirm the cluster is healthy.
+- To quickly spot missing containers or unhealthy datanodes.
+- To check how full the cluster is (used vs. remaining capacity).
+- To see whether there is a large backlog of open keys or keys pending
deletion.
+- To confirm the data Recon is showing is recent, and to trigger an on-demand
+ sync from the Ozone Manager (OM).
+
+## 3. How to Access the Page
+
+The Overview page is shown by default when you open the Recon web UI. You can
+also reach it any time from the **Overview** entry in the left navigation menu.
+
+## 4. Information Displayed
+
+At the top of the page is the page title and an **Auto Reload** panel
(described
+under Available Actions). At the bottom, the **Ozone Service ID** and **SCM
ID**
+are shown for reference.
+
+### Health cards
+
+Two cards, each showing a **Health** status (Healthy or Unhealthy) and an
+**Availability** ratio in the form `available/total`:
+
+- **Datanodes** — healthy datanodes out of the total. Links to the Datanodes
+ page.
+- **Containers** — available containers out of the total (total minus missing).
+ Links to the Containers page.
+
+A card is **Healthy** only when every unit is accounted for (available equals
+total). Otherwise it shows **Unhealthy**.
+
+### Ozone Capacity card
+
+A storage breakdown with a stacked bar and a **View More** link to the Capacity
+page. It shows:
+
+- **TOTAL** — the space configured for Ozone to use in the cluster. The actual
+ disk space may be larger than what is allocated to Ozone.
+- **OZONE USED SPACE** — space used by data stored in Ozone.
+- **OTHER USED SPACE** — space occupied by other Ozone-related files (logs,
+ configuration, database files, and so on) rather than stored data.
+- **CONTAINER PRE-ALLOCATED** — space committed/pre-allocated but not yet
+ written.
+
+### Count cards
+
+Six single-number cards:
+
+- **Volumes** — total volumes (links to the Volumes page).
+- **Buckets** — total buckets (links to the Buckets page).
+- **Keys** — total keys in the cluster.
+- **Pipelines** — total pipelines (links to the Pipelines page).
+- **Deleted Containers** — containers in the deleted state.
+- **Open Containers** — containers in the open state.
+
+### Summary tables
+
+Two tables, each with **Name** and **Size** columns and a **View More** link to
+the OM DB Insights page:
+
+- **Open Keys Summary** — Total Replicated Data, Total Unreplicated Data, and
+ the number of Open Keys.
+- **Delete Pending Keys Summary** — Total Replicated Data, Total Unreplicated
+ Data, and the number of Delete Pending Keys.
+
+Values that are unavailable appear as **N/A**.
+
+## 5. Available Actions
+
+The **Auto Reload** panel in the header provides:
+
+- **Auto Refresh** toggle — turns automatic refresh on or off. It refreshes
+ every 60 seconds and remembers your choice for the session.
+- **Refreshed at `<time>`** with a **reload** button — refreshes all data on
the
+ page immediately.
+- **DB Synced at `<time>`** with a **sync** button — triggers an on-demand OM
DB
+ sync. Hovering over the time shows when the last delta and full updates
+ happened, and whether a sync was just triggered or was already running.
+
+Each health, capacity, and summary card also has a **View More** link that
takes
+you to the detailed page for that topic. There is no search, filter, sort,
+pagination, or download on this page.
+
+## 6. How to Interpret the Information
+
+- **Health = Healthy (green check):** all units are accounted for. **Unhealthy
+ (yellow warning):** at least one datanode is not healthy or at least one
+ container is missing — use **View More** to drill down.
+- **Missing containers** indicate a data-availability risk; investigate on the
+ Containers page. The count is capped at 1001, so a value of **1001** means
+ "1001 or more".
+- **Ozone Capacity:** compare OZONE USED SPACE against TOTAL to judge how full
+ the cluster is. A large OTHER USED SPACE means non-data files are consuming
+ disk. CONTAINER PRE-ALLOCATED is space reserved but not yet written.
+- **Open Keys Summary:** a large open-keys count or size can indicate many
+ in-progress writes, or leaked/abandoned open keys.
+- **Delete Pending Keys Summary:** a growing backlog can indicate that deletion
+ is falling behind.
+- **N/A** means the value was unavailable, which is not necessarily the same as
+ zero.
+
+## 7. Common Use Cases
+
+1. **Daily health check.** Confirm both health cards show Healthy and capacity
+ is within expectations. If a card is Unhealthy, click **View More** to
+ investigate.
+2. **Capacity planning.** Watch OZONE USED SPACE against TOTAL over time to
+ decide when to add datanodes, then use **View More → Capacity** for the
+ per-datanode breakdown.
+3. **Deletion backlog triage.** If Delete Pending Keys is high, click **View
+ More** to the OM DB Insights page to see the keys involved.
+
+## 8. Important Notes and Limitations
+
+- **Data freshness.** Volume, bucket, and key counts and the key summaries come
+ from Recon's own copy of the OM database, which is updated by a periodic
sync.
+ The "DB Synced at" time shows how current that data is; use the sync button
to
+ force an update. Datanode, container, and capacity numbers depend on datanode
+ reports and heartbeats.
+- **Auto Refresh** only re-queries Recon; it does not force Recon to re-sync
from
+ OM. It runs every 60 seconds by default.
+- **Capacity** is based on datanode reports and includes replicated data size.
+ If some datanodes have not reported yet, capacity may be incomplete.
+- On an error, a card shows an error state instead of values. Until the first
+ successful load, counts appear as zero or N/A.
+- The **Ozone Service ID** and **SCM ID** come from cluster configuration and
may
+ show N/A if they are not configured.
+
+## 9. Related Pages
+
+- **Datanodes** — detail behind the Datanodes health card.
+- **Containers** — detail behind the Containers health card and
missing-container
+ investigations.
+- **Capacity** — full storage and capacity breakdown.
+- **Volumes**, **Buckets**, **Pipelines** — detail behind the count cards.
+- **OM DB Insights** — detail behind the Open Keys and Delete Pending Keys
+ summaries.
diff --git
a/docs/05-administrator-guide/03-operations/09-observability/02-recon/03-recon-capacity-distribution.md
b/docs/05-administrator-guide/03-operations/09-observability/02-recon/01-recon-web-ui/02-capacity.mdx
similarity index 99%
rename from
docs/05-administrator-guide/03-operations/09-observability/02-recon/03-recon-capacity-distribution.md
rename to
docs/05-administrator-guide/03-operations/09-observability/02-recon/01-recon-web-ui/02-capacity.mdx
index c3c5223128..fd173177bf 100644
---
a/docs/05-administrator-guide/03-operations/09-observability/02-recon/03-recon-capacity-distribution.md
+++
b/docs/05-administrator-guide/03-operations/09-observability/02-recon/01-recon-web-ui/02-capacity.mdx
@@ -1,5 +1,5 @@
---
-sidebar_label: Cluster Capacity User Guide
+sidebar_label: Cluster Capacity
---
# Cluster Capacity User Guide
diff --git
a/docs/05-administrator-guide/03-operations/09-observability/02-recon/01-recon-web-ui/README.mdx
b/docs/05-administrator-guide/03-operations/09-observability/02-recon/01-recon-web-ui/README.mdx
new file mode 100644
index 0000000000..cb0a8d896d
--- /dev/null
+++
b/docs/05-administrator-guide/03-operations/09-observability/02-recon/01-recon-web-ui/README.mdx
@@ -0,0 +1,46 @@
+---
+sidebar_label: Recon Web UI
+---
+
+# Recon Web UI
+
+import DocCardList from '@theme/DocCardList';
+
+## Introduction
+
+Apache Ozone Recon is a read-only monitoring and observability service for
Apache Ozone clusters, designed for cluster administrators. Recon aggregates
metadata from Ozone Manager (OM), Storage Container Manager (SCM), and
Datanodes, and exposes this information through a web-based user interface.
+
+Recon does not modify cluster state. It is designed to provide visibility,
diagnostics, and insight into the health and usage of an Ozone cluster.
+
+## Accessing the Recon UI
+
+The Recon UI is available via the Recon HTTP endpoint, typically:
+
+`http://<recon-host>:9888/`
+
+The left navigation panel provides access to all available views:
+
+- Overview
+- Volumes
+- Buckets
+- Datanodes
+- Pipelines
+- Containers
+- Insights
+- OM DB Insights
+- Namespace Usage
+- Heatmap
+
+The **Cluster Capacity** page is reached from the **View More** link on the
Overview page rather than from the left navigation.
+
+## Common conventions
+
+Most Recon UI pages share the same controls and behaviors. They are described
once here; each page notes only where it differs.
+
+- **Auto Reload panel** — an **Auto Refresh** toggle that re-queries Recon
every 60 seconds (and remembers your choice for the session) plus a manual
**reload** button showing the last refreshed time. Auto Refresh only re-queries
Recon; it does **not** force Recon to re-sync from OM. Some pages (for example
Insights, Heatmap, and OM DB Insights) have no Auto Reload panel.
+- **Data freshness** — namespace data (volumes, buckets, keys, and their
summaries) comes from Recon's own copy of the Ozone Manager (OM) database,
updated by a periodic sync; datanode, container, pipeline, and capacity figures
come from datanode reports and heartbeats. Values are only as current as the
last sync or report. The Overview page shows the last **DB Synced at** time and
can trigger an on-demand OM sync.
+- **Columns selector** — table pages let you choose which columns are visible;
a key identifier column is always pinned.
+- **Limit selector** — on large listings, controls how many rows are fetched
from the server (options such as 1000/5000/10000/20000; default 1000).
**Search, sorting, and filters apply to the loaded rows only**, not to rows
beyond the limit — raise the limit if you expect more.
+- **Error states** — on a fetch error, a page reports a data-fetch error and
its table stays empty; until the first successful load, counts may appear as
zero or `N/A`.
+
+<DocCardList/>
diff --git
a/docs/05-administrator-guide/03-operations/09-observability/02-recon/data_node_insights.png
b/docs/05-administrator-guide/03-operations/09-observability/02-recon/01-recon-web-ui/data_node_insights.png
similarity index 100%
rename from
docs/05-administrator-guide/03-operations/09-observability/02-recon/data_node_insights.png
rename to
docs/05-administrator-guide/03-operations/09-observability/02-recon/01-recon-web-ui/data_node_insights.png
diff --git
a/docs/05-administrator-guide/03-operations/09-observability/02-recon/ozone_capacity.png
b/docs/05-administrator-guide/03-operations/09-observability/02-recon/01-recon-web-ui/ozone_capacity.png
similarity index 100%
rename from
docs/05-administrator-guide/03-operations/09-observability/02-recon/ozone_capacity.png
rename to
docs/05-administrator-guide/03-operations/09-observability/02-recon/01-recon-web-ui/ozone_capacity.png
diff --git
a/docs/05-administrator-guide/03-operations/09-observability/02-recon/ozone_recon_overview.png
b/docs/05-administrator-guide/03-operations/09-observability/02-recon/01-recon-web-ui/ozone_recon_overview.png
similarity index 100%
rename from
docs/05-administrator-guide/03-operations/09-observability/02-recon/ozone_recon_overview.png
rename to
docs/05-administrator-guide/03-operations/09-observability/02-recon/01-recon-web-ui/ozone_recon_overview.png
diff --git
a/docs/05-administrator-guide/03-operations/09-observability/02-recon/pending_deletion.png
b/docs/05-administrator-guide/03-operations/09-observability/02-recon/01-recon-web-ui/pending_deletion.png
similarity index 100%
rename from
docs/05-administrator-guide/03-operations/09-observability/02-recon/pending_deletion.png
rename to
docs/05-administrator-guide/03-operations/09-observability/02-recon/01-recon-web-ui/pending_deletion.png
diff --git
a/docs/05-administrator-guide/03-operations/09-observability/02-recon/service_capacity.png
b/docs/05-administrator-guide/03-operations/09-observability/02-recon/01-recon-web-ui/service_capacity.png
similarity index 100%
rename from
docs/05-administrator-guide/03-operations/09-observability/02-recon/service_capacity.png
rename to
docs/05-administrator-guide/03-operations/09-observability/02-recon/01-recon-web-ui/service_capacity.png
diff --git
a/docs/05-administrator-guide/03-operations/09-observability/02-recon/02-recon-rest-api.mdx
b/docs/05-administrator-guide/03-operations/09-observability/02-recon/02-recon-rest-api.mdx
index 293d60865b..a55ffefb7c 100644
---
a/docs/05-administrator-guide/03-operations/09-observability/02-recon/02-recon-rest-api.mdx
+++
b/docs/05-administrator-guide/03-operations/09-observability/02-recon/02-recon-rest-api.mdx
@@ -1,3 +1,7 @@
+---
+sidebar_label: Recon REST API
+---
+
# Recon REST API
import SwaggerUI from '@site/src/components/SwaggerUI';
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
