This is an automated email from the ASF dual-hosted git repository.
chihsuan pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/ozone.git
The following commit(s) were added to refs/heads/master by this push:
new c5d4f28266d HDDS-16384. Document Recon fileSize bin semantics (#11204)
c5d4f28266d is described below
commit c5d4f28266dc7b2feb1954c235553afa88f91b5b
Author: Chi-Hsuan Huang <[email protected]>
AuthorDate: Tue Oct 13 17:18:33 2026 +0800
HDDS-16384. Document Recon fileSize bin semantics (#11204)
---
hadoop-hdds/docs/content/interface/ReconApi.md | 11 ++++++++---
hadoop-hdds/docs/content/interface/ReconApi.zh.md | 9 +++++----
.../themes/ozonedoc/static/swagger-resources/recon-api.yaml | 8 ++++++--
.../ozone/recon/chatbot/agent/LlmToolSpecFactory.java | 7 +++++--
.../src/main/resources/chatbot/recon-tool-semantics.md | 13 +++++++++----
5 files changed, 33 insertions(+), 15 deletions(-)
diff --git a/hadoop-hdds/docs/content/interface/ReconApi.md
b/hadoop-hdds/docs/content/interface/ReconApi.md
index c338908b33f..561af052b8a 100644
--- a/hadoop-hdds/docs/content/interface/ReconApi.md
+++ b/hadoop-hdds/docs/content/interface/ReconApi.md
@@ -1397,12 +1397,17 @@ Returns the status of all the Recon tasks.
* fileSize (optional)
- Filters the results based on the given fileSize.
+ Filters the results by the exact upper bound of a file-size histogram bin,
in bytes. It is not an arbitrary file
+ size or a cumulative less-than-or-equal threshold. A positive value that is
not a bin upper bound returns an empty
+ result. The first bin has an upper bound of 1024 bytes; for example, the
bin with upper bound 2048 contains files
+ larger than 1024 bytes and up to 2048 bytes. This filter can be used
independently or together with volume and/or
+ bucket.
**Returns**
-Returns the file counts within different file ranges with `fileSize` in the
-response object being the upper cap for file size range.
+Returns the file counts within different file ranges with `fileSize` in the
response object being the upper bound of
+the corresponding histogram bin. Each count is for that bin only, not the
cumulative count of files whose size is less
+than or equal to `fileSize`.
```json
[{
diff --git a/hadoop-hdds/docs/content/interface/ReconApi.zh.md
b/hadoop-hdds/docs/content/interface/ReconApi.zh.md
index 85358d58759..6b35e61bc2c 100644
--- a/hadoop-hdds/docs/content/interface/ReconApi.zh.md
+++ b/hadoop-hdds/docs/content/interface/ReconApi.zh.md
@@ -964,11 +964,14 @@ Recon跟踪所有大小从`1 KB`到`1 PB`的键。对于小于`1 KB`的键，映
根据给定的桶名过滤结果。
* fileSize (可选)
- 根据给定的文件大小筛选结果。
+ 根据文件大小直方图分桶的上界精确筛选结果，单位为字节。该值不是任意文件大小，也不是小于或等于该值的
+ 累计阈值。正数值如果不等于分桶上界，将回传空结果。第一个分桶的上界为 1024 字节；例如，上界为 2048
+ 的分桶包含大于 1024 字节且不超过 2048 字节的文件。该筛选条件可以单独使用，也可以与卷和/或桶一起使用。
**回传**
-回传不同文件范围内的文件计数，其中响应对象中的`fileSize`是文件大小范围的上限。
+回传不同文件范围内的文件计数，其中响应对象中的`fileSize`是对应直方图分桶的上界。每个计数仅属于该分桶，
+并不是文件大小小于或等于`fileSize`的累计计数。
```json
[{
@@ -1030,5 +1033,3 @@ Recon跟踪所有大小从`1 KB`到`1 PB`的键。对于小于`1 KB`的键，映
}
}
```
-
-
diff --git
a/hadoop-hdds/docs/themes/ozonedoc/static/swagger-resources/recon-api.yaml
b/hadoop-hdds/docs/themes/ozonedoc/static/swagger-resources/recon-api.yaml
index f67d2d70a93..4ef163b4f0c 100644
--- a/hadoop-hdds/docs/themes/ozonedoc/static/swagger-resources/recon-api.yaml
+++ b/hadoop-hdds/docs/themes/ozonedoc/static/swagger-resources/recon-api.yaml
@@ -1061,7 +1061,7 @@ paths:
get:
tags:
- Utilization
- summary: Returns the file counts within different file ranges with
fileSize in the response object being the upper cap for file size range.
+ summary: Returns file counts by size bin, with fileSize representing the
bin upper bound.
operationId: getFileCounts
parameters:
- name: volume
@@ -1081,7 +1081,11 @@ paths:
- name: fileSize
in: query
description: |
- Filters the results based on the given file size.<br>
+ Filters the results by the exact upper bound of a file-size
histogram bin, in bytes.<br>
+ It is not an arbitrary file size or a cumulative
less-than-or-equal threshold.<br>
+ A positive value that is not a bin upper bound returns an empty
result.<br>
+ The first bin has an upper bound of 1024 bytes; for example, the
bin with upper bound 2048 contains files larger than 1024 bytes and up to 2048
bytes.<br>
+ This filter can be used independently or together with volume
and/or bucket.<br>
The smallest file size being tracked for count is 1 KB i.e. 1024
bytes.
example: 1024
required: false
diff --git
a/hadoop-ozone/recon/src/main/java/org/apache/hadoop/ozone/recon/chatbot/agent/LlmToolSpecFactory.java
b/hadoop-ozone/recon/src/main/java/org/apache/hadoop/ozone/recon/chatbot/agent/LlmToolSpecFactory.java
index b9f32a1a091..778034f5b13 100644
---
a/hadoop-ozone/recon/src/main/java/org/apache/hadoop/ozone/recon/chatbot/agent/LlmToolSpecFactory.java
+++
b/hadoop-ozone/recon/src/main/java/org/apache/hadoop/ozone/recon/chatbot/agent/LlmToolSpecFactory.java
@@ -236,8 +236,11 @@ private void
addVolumeUtilizationAndNamespaceToolSpecs(List<ToolSpec> specs, Map
specs.add(createSpec("api_v1_utilization_fileCount",
"Distribution of file counts by size tier (optionally per
volume/bucket). Use for "
- + "histogram-style 'how many small vs large files' questions — not
for listing "
- + "individual files (api_v1_keys_listKeys).",
+ + "histogram-style 'how many small vs large files' questions.
fileSize selects a single "
+ + "bin by its exact upper bound in bytes, not an arbitrary size or
cumulative threshold; "
+ + "for example, upper bound 2048 represents files over 1024 and up
to 2048 bytes. A "
+ + "positive non-bin value returns no results. Not for listing
individual files "
+ + "(api_v1_keys_listKeys).",
paramMap(RECON_QUERY_VOLUME, "string", RECON_QUERY_BUCKET, "string",
RECON_QUERY_FILE_SIZE, "integer")));
diff --git
a/hadoop-ozone/recon/src/main/resources/chatbot/recon-tool-semantics.md
b/hadoop-ozone/recon/src/main/resources/chatbot/recon-tool-semantics.md
index 10f7477ae18..8b896a63d45 100644
--- a/hadoop-ozone/recon/src/main/resources/chatbot/recon-tool-semantics.md
+++ b/hadoop-ozone/recon/src/main/resources/chatbot/recon-tool-semantics.md
@@ -629,11 +629,16 @@ status and timestamps.
count", "object-count analytics".
**Do not use when.** They want to *list* files (`api_v1_keys_listKeys`) or
total disk usage
(`api_v1_namespace_usage`).
-**Parameters.** `volume`, `bucket`, `fileSize` (all optional; set
volume/bucket to scope).
-**Select examples.** "file size distribution"; "how many files are under 1MB";
"small vs large file
-counts in bucket b1"; "histogram of file sizes"; "object count by size tier".
+**Parameters.** `volume`, `bucket`, `fileSize` (all optional and independent;
set volume/bucket to
+scope). `fileSize` is an exact histogram-bin upper bound in bytes, not an
arbitrary file size or a
+cumulative less-than-or-equal threshold. A positive value that is not a bin
upper bound returns an
+empty result. The first bin has upper bound 1024; for example, upper bound
2048 represents files
+larger than 1024 bytes and up to 2048 bytes.
+**Select examples.** "file size distribution"; "how many files are in the bin
ending at 1MiB";
+"small vs large file counts in bucket b1"; "histogram of file sizes"; "object
count by size tier".
**Do-not-select examples.** "list large files" → `api_v1_keys_listKeys` with
`keySize`.
-**Answering guidance.** Present as a distribution; don't imply it lists files.
+**Answering guidance.** Present as a distribution; don't imply it lists files
or returns a
+cumulative count.
### `api_v1_utilization_containerCount`
**Purpose.** Container-count distribution across size tiers.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
