App Throttling - Configuration and Mechanics

Version 2

    Feature Summary

    App throttling to prevent a malicious or errant app code from severely impacting server performance is built into the Jive platform and set in the Admin Console. The mechanism is designed such that app request counts are tracked with high resolution but for a short period of time, and compared against lower and upper thresholds. If the upper threshold is exceeded, the server returns a 503 instead of processing the request. A Jive Admin can adjust these settings, but the new setting will apply to all apps. The description of the default behavior below should help you understand the likely consequences of frequent server calls using this default configuration, so you can design your app to conform to expected usage.

     

    Configuration and Thresholds

    The default throttling for an app tracks usage over a 10-second interval, imposing a lower threshold of 70 requests and an upper threshold of 150 requests during the interval.

     

    App throttling will detect when the upper limit is exceeded and refuse requests until the throttle falls below the lower limit, providing a cooling period. A non-blocking alert will be triggered upon exceeding the lower threshold, and a blocking alert will be triggered if the upper threshold is exceeded. These alerts may not be displayed in the browser immediately, so the ill-behaved app may run out of control for a short period before the user sees these alerts.

     

    Period vs. Bucket Thresholds

    The throttle implementation uses a ring buffer of buckets. Each bucket stores a count of uses for a relatively short interval within the total use history. A running total is maintained, incremented when new uses are recorded and decremented as buckets expire. Lower and upper thresholds are computed for each bucket as a percentage of the period thresholds, but at 1000% of their respective fractional limits. Bucket thresholds allow the server to respond faster to extreme request counts, while the 1000% increase allows for bursting that typically happens when an app is first rendered.

     

    User Experience

    A user can be presented with two types of alerts, blocking and non-blocking, as shown in the screen shots. The sparkline in the corner is available for developer apps when you choose Monitor On from the context menu. The sparkline is only visible when a user points to it, and indicates the usage trend over the last 10 seconds.

     

    Throttling1.pngThrottling-2.png

    For Jive Administrators

    An administrator can adjust throttling limits. App developers are encouraged to optimize their apps to work within the default configuration described above, but some apps may require you to change this default.

     

    A Jive administrator can configure the throttling mechanism using a single jive property: jive.api.throttle.definition.app

     

    This property is a formatted human-readbale string that defines warning and absolute thresholds as well as the sampling interval. The following table gives examples of configuration values.

     

    Example ValueExplanation

    Warning

    Limit

    Fail

    Limit

    Interval

    Max

    Burst

    Limit to: 70 (150!) per 10s

    Warn at 70 and fail at 150 uses within any 10 second interval (this is the default configuration)

    7015010 sec30 / 200ms
    Limit to: 200 (250!) per 5s

    Warn at 200 and fail at 250 uses within any 5 second interval

    2002505 sec50 / 100ms
    Limit to: 50 (50!) per 1s

    Fail at 50 uses within any 1 second interval, warnings will not be issued when equal to the fail limit

    ignored501 sec10 / 20ms

     

    † Warning and failure limits cannot be less than 10, and warning limits cannot be greater than failure limits. If the wanring limit is equal to the failure limit, the warning limit is ignored.

    ‡ Max burst is computed as: (fail limit / 5) per (interval / 50)