HDDS-16384. Document Recon fileSize bin semantics

[chihsuan]

What changes were proposed in this pull request?

Clarify in the Recon API documentation and chatbot guidance that fileSize matches the exact upper bound of one
file-size histogram bin. It is not an arbitrary file size or a cumulative threshold, and a positive value that is not
a bin upper bound returns an empty result.

This follows #11203, which fixes the endpoint to apply fileSize independently of the volume and bucket filters.

What is the link to the Apache JIRA

https://issues.apache.org/jira/browse/HDDS-16384

How was this patch tested?

• mvn -pl :ozone-recon -am install -DskipTests -DskipShade -DskipRecon -DskipDocs
• mvn -pl :ozone-recon test -Dtest=TestReconToolCatalogConsistency -DskipShade -DskipRecon -DskipDocs
• ./hadoop-ozone/dev-support/checks/checkstyle.sh
• Parsed recon-api.yaml with Ruby's YAML parser

Generated-by: Codex (GPT-5)

[Copilot]

🟡 Changes recommended

The OpenAPI schema type for fileSize should be corrected to an int64 integer, and the docs currently describe fileSize as independent while the implementation in this branch does not apply it independently unless #11203 is included.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR updates Apache Ozone Recon documentation and tool metadata to clarify the precise semantics of the optional fileSize query parameter on GET /api/v1/utilization/fileCount, aligning user-facing docs and LLM/chatbot guidance with the endpoint’s histogram-bin model.

Changes:

• Clarifies that fileSize matches an exact histogram bin upper bound (bytes), not an arbitrary size or cumulative threshold.
• Updates chatbot/tooling guidance to avoid “under X” phrasing and to describe the single-bin behavior.
• Improves Swagger and Recon API docs (English + Chinese) to reflect the bin semantics and empty-result behavior for non-bin values.

File summaries

File	Description
hadoop-ozone/recon/src/main/resources/chatbot/recon-tool-semantics.md	Updates chatbot selection/answering guidance for fileCount and refines examples.
hadoop-ozone/recon/src/main/java/org/apache/hadoop/ozone/recon/chatbot/agent/LlmToolSpecFactory.java	Refines the LLM tool description for api_v1_utilization_fileCount to describe exact-bin fileSize semantics.
hadoop-hdds/docs/themes/ozonedoc/static/swagger-resources/recon-api.yaml	Updates OpenAPI summary/parameter description to explicitly define fileSize as a bin upper bound.
hadoop-hdds/docs/content/interface/ReconApi.zh.md	Updates Chinese API docs to describe exact-bin filtering and non-cumulative semantics.
hadoop-hdds/docs/content/interface/ReconApi.md	Updates English API docs to describe exact-bin filtering and non-cumulative semantics.

Review details

Suppressed comments (1)

hadoop-hdds/docs/themes/ozonedoc/static/swagger-resources/recon-api.yaml:1092

• fileSize is documented as an exact upper bound in bytes and is parsed as a long in the endpoint, but the OpenAPI schema declares it as type: number. This should be an integer (int64) to match the API contract and avoid clients sending fractional values.

        - name: fileSize
          in: query
          description: |
            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>
            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
          schema:
            type: number

• Files reviewed: 5/5 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.