This is an automated email from the ASF dual-hosted git repository.
weichiu pushed a commit to branch HDDS-9225-website-v2
in repository https://gitbox.apache.org/repos/asf/ozone-site.git
The following commit(s) were added to refs/heads/HDDS-9225-website-v2 by this
push:
new 1794bd5bb HDDS-14500. [Website v2] [Docs] [Administrator Guide]
Improve 'FairCallQueue' page (#292)
1794bd5bb is described below
commit 1794bd5bb25a323328be52e3fbdb8b74ef10a6c2
Author: Gargi Jaiswal <[email protected]>
AuthorDate: Tue Jan 27 11:15:31 2026 +0530
HDDS-14500. [Website v2] [Docs] [Administrator Guide] Improve
'FairCallQueue' page (#292)
---
cspell.yaml | 2 +
.../04-performance/08-fair-call-queue.md | 60 ++++++++++++++++++----
2 files changed, 53 insertions(+), 9 deletions(-)
diff --git a/cspell.yaml b/cspell.yaml
index 77ad7f9dd..efb4a35e9 100644
--- a/cspell.yaml
+++ b/cspell.yaml
@@ -95,6 +95,8 @@ words:
- HCFS
- libo3fs
- AOS
+- FCQ
+- QoS
# Other systems' words
- KDC
- classpath
diff --git
a/docs/05-administrator-guide/02-configuration/04-performance/08-fair-call-queue.md
b/docs/05-administrator-guide/02-configuration/04-performance/08-fair-call-queue.md
index e0de624f3..2a2cc5873 100644
---
a/docs/05-administrator-guide/02-configuration/04-performance/08-fair-call-queue.md
+++
b/docs/05-administrator-guide/02-configuration/04-performance/08-fair-call-queue.md
@@ -1,17 +1,37 @@
---
-sidebar_label: FairCallQueue
+sidebar_label: Fairness
---
-# FairCallQueue
+# Fairness
-This document contains information for setting up the `FairCallQueue` feature
with Ozone.
-In order for `FairCallQueue` to be enabled and used,
-Hadoop RPC must be used as transport protocol for OM - S3G communication.
-There is no implementation for gRPC yet.
+## What is FairCallQueue?
-There is a custom `IdentityProvider` implementation for Ozone that must be
specified in the configuration, otherwise
-there is no S3G impersonation which makes the `FairCallQueue` ineffective
since it's only reading one user,
-the S3G special user instead of the S3G client user.
+Fair Call Queue (FCQ) is a multi-level priority queue that schedules RPC
requests based on user identity. It works with a scheduler (typically
`DecayRpcScheduler`) to track each user's call volume over time, assign
priority levels based on usage patterns, and distribute processing capacity
fairly across all users using a weighted round-robin multiplexer.
+
+This document contains information for setting up the `FairCallQueue` feature
with Ozone. In order for FairCallQueue to be enabled and used, Hadoop RPC must
be used as transport protocol for `OM - S3G communication`. There is no
implementation for gRPC yet.
+
+There is a custom `IdentityProvider` implementation for Ozone that must be
specified in the configuration, otherwise there is no S3G impersonation which
makes the FairCallQueue ineffective since it’s only reading one user, the S3G
special user instead of the S3G client user.
+
+## Why is Fairness Important?
+
+Fairness is crucial in multi-tenant environments where multiple users or
applications access Ozone through the S3 Gateway. Without fair scheduling:
+
+- A single high-volume user or application can flood the request queue,
causing other users' requests to wait indefinitely or timeout
+- Users with legitimate but lower-volume workloads may experience unacceptable
latency as their requests are delayed behind a backlog of requests from a
single dominant user.
+- System resources could be monopolized by aggressive clients
+- Quality of service (QoS) guarantees cannot be maintained
+
+By implementing fair call queuing, Ozone ensures that all users receive
equitable access to OM resources, leading to more predictable performance and
better multi-tenancy support.
+
+## Where FCQ should be applied?
+
+FCQ should be applied at the **Ozone Manager (OM)** level for the **S3 Gateway
(S3G) → Ozone Manager** communication path.
+When S3 Gateway forwards requests from multiple S3 clients to the Ozone
Manager, FCQ uses each request's S3 access ID to
+identify users and prioritize requests based on their recent call volume,
ensuring fair resource distribution across all users.
+
+## Hadoop FCQ Framework
+
+Ozone leverages Hadoop's `FairCallQueue` framework for implementing fairness.
For detailed information about how `FairCallQueue` works, its architecture, and
advanced configuration options, refer to the [Hadoop FairCallQueue
documentation](https://hadoop.apache.org/docs/stable/hadoop-project-dist/hadoop-common/FairCallQueue.html).
## Configuration
@@ -72,3 +92,25 @@ Port used for below examples : 9862
<value>50</value>
</property>
```
+
+### Validation Steps
+
+1. **Check Logs**: After starting OM, verify in the logs that FCQ is
initialized:
+
+ ```text
+ FairCallQueue is in use with <N> queues with total capacity of <capacity>
+ ```
+
+2. **Verify Metrics**: Check that FCQ metrics are being collected (via JMX or
metrics endpoint):
+ - `FairCallQueueSize_p<N>` for each priority level
+ - `FairCallQueueOverflowedCalls_p<N>` for overflow statistics
+
+## Troubleshooting
+
+1. **FCQ not working**: Verify `OzoneIdentityProvider` is configured, gRPC is
disabled (`ozone.om.s3.grpc.server_enabled=false`), and port numbers match
across all `ipc.<port>.*` properties.
+
+2. **High latency**: Increase queue capacity
(`ipc.server.max.callqueue.length`) or adjust scheduler thresholds
(`ipc.<port>.decay-scheduler.thresholds`).
+
+3. **Configuration errors**: Ensure port consistency between
`ozone.om.address` and `ipc.<port>.*` properties, and verify all class names
are correct.
+
+4. **Monitor metrics**: Check `FairCallQueueSize_p<N>` and
`FairCallQueueOverflowedCalls_p<N>` via JMX to diagnose queue behavior.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
