<p>This document describes how to configure and manage the Fair Call Queue for Hadoop.</p></section><section>
<h2><aname="Prerequisites"></a>Prerequisites</h2>
<p>Make sure Hadoop is installed, configured and setup correctly. For more information see:</p>
<ul>
<li><ahref="./SingleCluster.html">Single Node Setup</a> for first-time users.</li>
<li><ahref="./ClusterSetup.html">Cluster Setup</a> for large, distributed clusters.</li>
</ul></section><section>
<h2><aname="Overview"></a>Overview</h2>
<p>Hadoop server components, in particular the HDFS NameNode, experience very heavy RPC load from clients. By default, all client requests are routed through a first-in, first-out queue and serviced in the order they arrive. This means that a single user submitting a very large number of requests can easily overwhelm the service, causing degraded service for all other users. The Fair Call Queue, and related components, aim to mitigate this impact.</p></section><section>
<p>There are a few components in the IPC stack which have a complex interplay, each with their own tuning parameters. The image below presents a schematic overview of their interactions, which will be explained below.</p>
<p>In the following explanation, <b>bolded</b> words refer to named entities or configurables.</p>
<p>When a client makes a request to an IPC server, this request first lands in a <b>listen queue</b>. <b>Reader</b> threads remove requests from this queue and pass them to a configurable <b>RpcScheduler</b> to be assigned a priority and placed into a <b>call queue</b>; this is where FairCallQueue sits as a pluggable implementation (the other existing implementation being a FIFO queue). <b>Handler</b> threads accept requests out of the call queue, process them, and respond to the client.</p>
<p>The implementation of RpcScheduler used with FairCallQueue by default is <b>DecayRpcScheduler</b>, which maintains a count of requests received for each user. This count <i>decays</i> over time; every <b>sweep period</b> (5s by default), the number of requests per user is multiplied by a <b>decay factor</b> (0.5 by default). This maintains a weighted/rolling average of request count per user. Every time that a sweep is performed, the call counts for all known users are ranked from highest to lowest. Each user is assigned a <b>priority</b> (0-3 by default, with 0 being highest priority) based on the proportion of calls originating from that user. The default <b>priority thresholds</b> are (0.125, 0.25, 0.5), meaning that users whose calls make up more than 50% of the total (there can be at most one such user) are placed into the lowest priority, users whose calls make up between 25% and 50% of the total are in the 2nd lowest, users whose calls make up between 12.5% and 25% are in the 2nd highest priority, and all other users are placed in the highest priority. At the end of the sweep, each known user has a cached priority which will be used until the next sweep; new users which appear between sweeps will have their priority calculated on-the-fly.</p>
<p>Within FairCallQueue, there are multiple <b>priority queues</b>, each of which is designated a <b>weight</b>. When a request arrives at the call queue, the request is placed into one of these priority queues based on the current priority assigned to the call (by the RpcScheduler). When a handler thread attempts to fetch an item from the call queue, which queue it pulls from is decided via an <b>RpcMultiplexer</b>; currently this is hard-coded to be a <b>WeightedRoundRobinMultiplexer</b>. The WRRM serves requests from queues based on their weights; the default weights for the default 4 priority levels are (8, 4, 2, 1). Thus, the WRRM would serve 8 requests from the highest priority queue, 4 from the second highest, 2 from the third highest, 1 from the lowest, then serve 8 more from the highest priority queue, and so on.</p>
<p>In addition to the priority-weighting mechanisms discussed above, there is also a configurable <b>backoff</b> mechanism, in which the server will throw an exception to the client rather than handling it; the client is expected to wait some time (i.e., via exponential backoff) before trying again. Typically, backoff is triggered when a request is attempted to be placed in a priority queue (of FCQ) when that queue is full. This helps to push back further on impactful clients, reducing load, and can have substantial benefit. There is also a feature, <b>backoff by response time</b>, which will cause requests in lower priority levels to back off if requests in higher priority levels are being serviced too slowly. For example, if the response time threshold for priority 1 is set to be 10 seconds, but the average response time in that queue is 12 seconds, an incoming request at priority levels 2 or lower would receive a backoff exception, while requests at priority levels 0 and 1 would proceed as normal. The intent is to force heavier clients to back off when overall system load is heavy enough to cause high priority clients to be impacted.</p>
<p>The discussion above refers to the <b>user</b> of a request when discussing how to group together requests for throttling. This is configurable via the <b>identity provider</b>, which defaults to the <b>UserIdentityProvider</b>. The user identity provider simply uses the username of the client submitting the request. However, a custom identity provider can be used to performing throttling based on other groupings, or using an external identity provider.</p>
<p>If particular users submit important requests and you don’t want to limit them, you can set them up as the <b>service-users</b>. They are always scheduled into the high-priority queue and won’t be included in the priority computation of normal user calls.</p><section>
<p>Though the fair call queue itself does a good job of mitigating the impact from users who submit a very high <i>number</i> of requests, it does not take account into how expensive each request is to process. Thus, when considering the HDFS NameNode, a user who submits 1000 “getFileInfo” requests would be prioritized the same as a user who submits 1000 “listStatus” requests on some very large directory, or a user who submits 1000 “mkdir” requests, which are more expensive as they require an exclusive lock on the namesystem. To account for the <i>cost</i> of an operation when considering the prioritization of user requests, there is a “cost-based” extension to the Fair Call Queue which uses the aggregate processing time of a user’s operations to determine how that user should be prioritized. By default, queue time (time spent waiting to be processed) and lock wait time (time spent waiting to acquire a lock) is not considered in the cost, time spent processing without a lock is neutrally (1x) weighted, time spent processing with a shared lock is weighted 10x higher, and time spent processing with an exclusive lock is weighted 100x higher. This attempts to prioritize users based on the actual load they place on the server. To enable this feature, set the <code>costprovder.impl</code> configuration to <code>org.apache.hadoop.ipc.WeightedTimeCostProvider</code> as described below.</p></section></section><section>
<h2><aname="Configuration"></a>Configuration</h2>
<p>This section describes how to configure the fair call queue.</p><section>
<p>All call queue-related configurations are relevant to only a single IPC server. This allows for a single configuration file to be used to configure different components, or even different IPC servers within a component, to have uniquely configured call queues. Each configuration is prefixed with <code>ipc.<port_number></code>, where <code><port_number></code> is the port used by the IPC server to be configured. For example, <code>ipc.8020.callqueue.impl</code> will adjust the call queue implementation for the IPC server running at port 8020. For the remainder of this section, this prefix will be omitted.</p></section><section>
<h3><aname="Full_List_of_Configurations"></a>Full List of Configurations</h3>
<tableborder="0"class="bodyTable">
<thead>
<trclass="a">
<thalign="left"> Configuration Key </th>
<thalign="left"> Applicable Component </th>
<thalign="left"> Description </th>
<thalign="left"> Default </th></tr>
</thead><tbody>
<trclass="b">
<tdalign="left"> backoff.enable </td>
<tdalign="left"> General </td>
<tdalign="left"> Whether or not to enable client backoff when a queue is full. </td>
<tdalign="left"> false </td></tr>
<trclass="a">
<tdalign="left"> callqueue.impl </td>
<tdalign="left"> General </td>
<tdalign="left"> The fully qualified name of a class to use as the implementation of a call queue. Use <code>org.apache.hadoop.ipc.FairCallQueue</code> for the Fair Call Queue. </td>
<tdalign="left"> The capacity allocation weights among all subqueues. A postive int array whose length is equal to the <code>scheduler.priority.levels</code> is expected where each int is the relative weight out of total capacity. i.e. if a queue with capacity weight <code>w</code>, its queue capacity is <code>capacity * w/sum(weights)</code></td></tr>
<trclass="a">
<tdalign="left"> scheduler.impl </td>
<tdalign="left"> General </td>
<tdalign="left"> The fully qualified name of a class to use as the implementation of the scheduler. Use <code>org.apache.hadoop.ipc.DecayRpcScheduler</code> in conjunction with the Fair Call Queue. </td>
<tdalign="left"><code>org.apache.hadoop.ipc.DefaultRpcScheduler</code> (no-op scheduler) <br/> If using FairCallQueue, defaults to <code>org.apache.hadoop.ipc.DecayRpcScheduler</code></td></tr>
<trclass="b">
<tdalign="left"> scheduler.priority.levels </td>
<tdalign="left"> RpcScheduler, CallQueue </td>
<tdalign="left"> How many priority levels to use within the scheduler and call queue. </td>
<tdalign="left"> How much weight to give to each priority queue. This should be a comma-separated list of length equal to the number of priority levels. </td>
<tdalign="left"> Weights descend by a factor of 2 (e.g., for 4 levels: <code>8,4,2,1</code>) </td></tr>
<trclass="b">
<tdalign="left"> identity-provider.impl </td>
<tdalign="left"> DecayRpcScheduler </td>
<tdalign="left"> The identity provider mapping user requests to their identity. </td>
<tdalign="left"> The cost provider mapping user requests to their cost. To enable determination of cost based on processing time, use <code>org.apache.hadoop.ipc.WeightedTimeCostProvider</code>. </td>
<tdalign="left"> How frequently the decay factor should be applied to the operation counts of users. Higher values have less overhead, but respond less quickly to changes in client behavior. </td>
<tdalign="left"> When decaying the operation counts of users, the multiplicative decay factor to apply. Higher values will weight older operations more strongly, essentially giving the scheduler a longer memory, and penalizing heavy clients for a longer period of time. </td>
<tdalign="left"> 0.5 </td></tr>
<trclass="b">
<tdalign="left"> decay-scheduler.thresholds </td>
<tdalign="left"> DecayRpcScheduler </td>
<tdalign="left"> The client load threshold, as an integer percentage, for each priority queue. Clients producing less load, as a percent of total operations, than specified at position <i>i</i> will be given priority <i>i</i>. This should be a comma-separated list of length equal to the number of priority levels minus 1 (the last is implicitly 100). </td>
<tdalign="left"> Thresholds ascend by a factor of 2 (e.g., for 4 levels: <code>13,25,50</code>) </td></tr>
<tdalign="left"> The response time thresholds, as time durations, for each priority queue. If the average response time for a queue is above this threshold, backoff will occur in lower priority queues. This should be a comma-separated list of length equal to the number of priority levels. </td>
<tdalign="left"> Threshold increases by 10s per level (e.g., for 4 levels: <code>10s,20s,30s,40s</code>) </td></tr>
<tdalign="left"> Service users will always be scheduled into the highest-priority queue and won’t be included in the priority computation of normal user calls. They are specified as a comma-separated list. </td>
<tdalign="left"></td></tr>
<trclass="a">
<tdalign="left"> weighted-cost.lockshared </td>
<tdalign="left"> WeightedTimeCostProvider </td>
<tdalign="left"> The weight multiplier to apply to the time spent in the processing phase which holds a shared (read) lock. </td>
<tdalign="left"> The weight multiplier to apply to the time spent in the processing phases which do not involve holding a lock. See <code>org.apache.hadoop.ipc.ProcessingDetails.Timing</code> for more details on each phase. </td>
<p>This is an example of configuration an IPC server at port 8020 to use <code>FairCallQueue</code> with the <code>DecayRpcScheduler</code> and only 2 priority levels. The heaviest 10% of users are penalized heavily, given only 1% of the total requests processed.</p>
