priyeshkaratha commented on code in PR #8907: URL: https://github.com/apache/ozone/pull/8907#discussion_r2634361309
########## hadoop-hdds/docs/content/design/storage-distribution.md: ########## @@ -0,0 +1,346 @@ +--- +title: Storage Capacity Distribution Design +summary: Proposal for introducing a comprehensive storage distribution dashboard in Recon. +date: 2025-08-05 +jira: HDDS-13177 +status: Under Review +author: Priyesh Karatha +--- + +<!-- + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, + either express or implied. See the License for the specific + language governing permissions and limitations under the License. +--> + +# Abstract +Ozone currently lacks a unified interface to monitor and analyze storage distribution across its cluster components. This makes it difficult to: + +- Understand data distribution across the cluster +- Debug storage reclamation issues +- Monitor pending deletion progress +- Analyze utilization patterns +- Identify potential bottlenecks and imbalances + +This proposal introduces a comprehensive **Storage Capacity Distribution Dashboard** in Recon to address these challenges. +This initiative significantly enhances operational insight, capacity planning accuracy, and system observability in large-scale Ozone deployments. + +## Approach 1: Recon-based + +### Architectural Overview + +The dashboard operates as an extension to **Recon**, leveraging existing telemetry from: + +- **Ozone Manager (OM)** - namespace-level and key-level metadata. +- **Storage Container Manager (SCM)** - container, block, and replication metrics. +- **DataNodes (DNs)** - raw storage usage and pending deletion data. + +All metrics are aggregated, and exposed through a **RESTful API (/storagedistribution)** for recon dashboard. + + +### Data Flow Summary + +- OM → Recon + - Periodic synchronization happens between OM db to Recon. +- OM -> SCM + - Block deletion request sent by OM to SCM carries block size and replicated size. +- SCM → Recon + - SCM aggregates the blocks in the block deletion request into DeletedBlocksTransaction with aggregated block size and replicated size, persisted into DB. + - SCM maintains and updates a deletion transaction summary for newly created/deleted transactions. Summary is exposed through metrics, API, and also persisted. + - Recon gets the deletion transaction summary using SCM client whenever required. +- SCM → Datanode + - Block deletion transaction sent by SCM to DN carries block size. +- DataNode → Recon + - Exposes TotalPendingDeletionBytes via JMX through BlockDeletingService. + - Recon fetches this data for node-level pending deletion tracking. +- Recon + - Consolidates all component-level data. + - Computes global storage, namespace usage, and pending deletion metrics. + - Exposes results via RestFull API /storagedistribution. + +### Recon API Design + +The Recon API will expose a single endpoint that returns a JSON object with the following structure: + +| Field | Type | Description | +|--------------------|------------------|----------------------------------------| +| globalStorage | Object | Overall storage capacity metrics. | +| globalNamespace | Object | Overall namespace (key) usage metrics. | +| usedSpaceBreakdown | Object | Detailed breakdown of used space. | +| dataNodeUsage | Array of Objects | Per-DataNode storage usage. | + +#### globalStorage Object + +| Field | Type | Description | +|----------------|------|---------------------------------------------------| +| totalUsedSpace | Long | Total used space across all DataNodes in bytes. | +| totalFreeSpace | Long | Total free space across all DataNodes in bytes. | +| totalCapacity | Long | Total raw capacity across all DataNodes in bytes. | + +#### globalNamespace Object + +| Field | Type | Description | +|----------------|------|---------------------------------------------------------| +| totalUsedSpace | Long | Total used space for namespace objects (keys) in bytes. | +| totalKeys | Long | Total number of keys in the namespace. | + +#### usedSpaceBreakdown Object + +| Field | Type | Description | +|-----------------------|--------|--------------------------------------------------------| +| openKeysBytes | Long | Bytes currently held by open keys (not yet committed). | +| committedBytes | Long | Bytes committed to existing keys. | +| containerPreAllocated | Long | Pre-allocated space for open containers. | +| deletionPendingBytes | Object | Bytes pending deletion. | + +#### deletionPendingBytes Object + +| Field | Type | Description | +|---------|--------|-------------------------------------------------| +| total | Long | Total bytes pending deletion across all stages. | +| byStage | Object | Breakdown of pending deletion bytes by stage. | + +#### byStage Object + +| Field | Type | Description | +|-------|--------|-----------------------------------------------------| +| DN | Object | DataNode pending deletion metrics. | +| SCM | Object | Storage Container Manager pending deletion metrics. | +| OM | Object | Ozone Manager pending deletion metrics. | + +#### DN Object (within byStage) + +| Field | Type | Description | +|--------------|------|-----------------------------------------------| +| pendingBytes | Long | Bytes pending deletion at the DataNode level. | + +#### SCM Object (within byStage) + +| Field | Type | Description | +|--------------|------|------------------------------------------| +| pendingBytes | Long | Bytes pending deletion at the SCM level. | + +#### OM Object (within byStage) + +| Field | Type | Description | +|-----------------------|------|------------------------------------------------------------------------------------------| +| pendingKeyBytes | Long | Key bytes pending deletion at the Ozone Manager level. | +| pendingDirectoryBytes | Long | Directory bytes pending deletion at the Ozone Manager level. | +| totalBytes | Long | Total bytes pending deletion at the Ozone Manager level (includes keys and directories). | +#### dataNodeUsage Array of Objects + +Each object in this array represents the usage for a single DataNode. + +| Field | Type | Description | +|------------------|--------|------------------------------------------------| +| dataNodeUuId | String | Unique identifier for the DataNode | +| hostName | String | Hostname of the DataNode | +| capacity | Long | Total capacity of the DataNode in bytes. | +| used | Long | Used space on the DataNode in bytes. | +| remaining | Long | Remaining free space on the DataNode in bytes. | +| committed | Long | Bytes committed to keys on this DataNode. | +| pendingDeletion | Long | Bytes pending deletion on this DataNode. | +| minimumFreeSpace | Long | Configured minimum free space in Bytes. | + +#### Example API Output + +```json +{ + "globalStorage": { + "totalUsedSpace": 15744356352, + "totalFreeSpace": 3002519420928, + "totalCapacity": 3242976054744 + }, + "globalNamespace": { + "totalUsedSpace": 5242880000, + "totalKeys": 10 + }, + "usedSpaceBreakdown": { + "openKeysBytes": 0, + "committedBytes": 5242880000, + "containerPreAllocated": 0, + "deletionPendingBytes": { + "total": 0, + "byStage": { + "DN": { + "pendingBytes": 0 + }, + "SCM": { + "pendingBytes": 0 + }, + "OM": { + "pendingKeyBytes": 0, + "totalBytes": 0, + "pendingDirectoryBytes": 0 + } + } + } + }, + "dataNodeUsage": [ + { + "datanodeUuid": "31300d56-f6f8-46f4-9d1e-862ac82066f8", + "hostName": "ozone-datanode-2.ozone_default", + "capacity": 1080992018248, + "used": 5248118784, + "remaining": 1000839806976, + "committed": 0, + "pendingDeletion": 0, + "minimumFreeSpace": 1080992000 Review Comment: DU reserved will be also added in response. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
