kerneltime commented on code in PR #7548: URL: https://github.com/apache/ozone/pull/7548#discussion_r1905012164
########## hadoop-hdds/docs/content/design/find-block-missing-key.md: ########## @@ -0,0 +1,106 @@ +--- +title: Find Block Missing Key +summary: A client-side tool used to locate Block missing Keys +date: 2024-12-09 +jira: HDDS-11891 +status: draft +--- +<!-- + 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. See accompanying LICENSE file. +--> + +## Summary + +This document provides a design overview of a client-side tool used to locate Block Missing Keys. + +In Ozone, the metadata of a Key is stored in the OM (Ozone Manager), while the data is stored on DNs (DataNodes). If the metadata of a Key is missing, the Key becomes invisible. However, if the metadata is intact but the data is missing, this issue cannot be identified until the Key is accessed. The goal of this tool is to detect such scenarios where the data is missing but the metadata remains intact, referred to as a Block Missing Key. + + +## Definitions + +- Key: In this document, a Key refers to both OBJECT_STORE objects and files in FSO buckets. At the Block level, they are treated the same way. +- Missing: Refers to a situation where a Key cannot be read successfully. If a Key is missing some replicas but can still be read, it is not considered a missing Key. This tool also provides functionality to detect Keys with partially missing replicas. +- Block Missing Key: Refers to a Key whose data is missing while its metadata remains intact. + + +## Limitations + +The following cases are not included in the scope of Block Missing Key detection in this document: + +1. Key data loss caused by Block data corruption. +2. Data block integrity errors, such as mismatched chunksum values. + +This tool only verifies the existence of Block data and metadata. It does not validate the correctness of data blocks, meaning it does not read Blocks to calculate their chunksum for comparison with metadata. + + +## Potential Scenarios for Block Missing Keys + +1. The Container containing the Key is in a `DELETED` or `DELETING` state. +2. The Container containing the Key is missing, and there is no record of the Container in the cluster. +3. The metadata of the Key’s Block is missing. +4. The data of the Key’s Block is missing. + + +## Scanning Process Overview + +1. Retrieve Key metadata: + - Gather metadata such as the Key name and BlockID (consisting of ContainerID and localID). + - After collecting sufficient Key metadata, organize it for further processing. + - There are three approaches to retrieve metadata (detailed in [Three Approaches to Retrieve Metadata](https://www.notion.so/meeting-room-Conference-Room-d17916fda32244f2b5edfec93c165cee?pvs=21)). Review Comment: Notion should be markdown, we should include it here in the PR itself. -- 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]
