Copyright © Cloud Software Group, Inc. All Rights Reserved

Overview

TIBCO API Exchange Gateway supports throttles to control the flow of requests from the client to the target operations. TIBCO API Exchange Gateway uses a throttle policy to determine if a client request should be passed on to a target operation or rejected. TIBCO API Exchange Gateway uses the throttles to do the following:

•	Protect the target operations from overuse

•	Maintain the limit of requests load on a target operation

•	Protect the target operation to be accessed by unauthorized partners

•	Enforce the service level agreements at a partner level

Using throttles, you can define the maximum number of requests that are handled by a target operation in a defined time interval. You must define the maximum count and a time interval for the throttle.

The throttles define a condition for a throttle type and metric (entity). TIBCO API Exchange Gateway checks the condition for an incoming request before processing the request. For example, you can define a condition to allow only 5 client requests within 10 seconds to the target operation for a partner request.

A throttle policy is defined using the Monitors tab of the Config UI. After defining a throttle policy, the policy can be applied to a metric such as partner, partner group, partner operation, or target operation.

Facade Throttles

Facade throttles are designed for the partners, partner groups, and partner+operation. The Core Engine applies the facade throttle after it identifies the facade operation.

The supported throttle types can be applied at the following level:

•

Partner

After defining a throttle policy, apply the policy at a partner level. The Core Engine checks the throttle condition on every request sent by the partner.

•	Partner Group

After defining a throttle policy, apply the policy at a partner group level. The Core Engine checks the throttle condition on every request sent by the partners in a group.

•	Partner + Operation

After defining a throttle policy, apply the policy by the combination of the partner and the operation. The Core Engine checks the throttle condition on every request sent by the partner for a specific operation.

Service Throttles

Service throttles are designed for a target operation. The Core Engine applies the service throttle after it identifies the target operation.

The supported throttles types can be applied at the following level:

•	Target Operation

After defining a throttle policy, apply the policy for a target operation. The Core Engine checks the throttle condition on every request sent to the target operation.

For both facade and service throttles, if an error occurs before the throttle has been identified, the throttle is not applied.

Throttle Types

TIBCO API Exchange Gateway supports the following types of throttles:

Rate

The rate throttle is a throttle that allows the requests to pass through until a limit is reached for a time interval.

The rate throttle count is increased based on the following:

•	Request Count

•	Payload Size. See Payload Size Throttles.

•	Monitor metric retrieved from the context of the input request message. See Content Based Throttles.

The rate throttle is a technical throttle which can be applied to any metric. For example:

•	Define a rate throttle to apply at a partner level. Using the throttle at a partner level, limit the number of requests from a partner.

•	Define a rate throttle to apply at a target operation level. Using the throttle at a target operation level, protect the target operations from overuse.

You may define the rate throttles for any metric if you want to measure the number of requests within a small time interval. After each request is processed, the current throttle count is usually incremented by 1, if the throttle counter is set to Request Count. See Throttle Counter for the details.

Rate throttle is applied for the shorter intervals and is reset once the interval is reached.

For a rate throttle, define throttle interval (in seconds) and throttle max limit. The throttle max limit is reset as specified by Throttle UpdateInterval. See Throttle UpdateInterval.

Example

Set the following throttle configuration on the Config UI to allow only 5 maximum requests to be processed by a target operation within 10 seconds. The following throttle configuration allows 5 requests every 10 seconds and rejects the other requests within 10 seconds.

---

 

Interval : 10

Max Limit: 5

Monitor Type: Rate Throttle

Monitor Counter: Request Count

---

 

Quota

Quota throttle is similar to the Rate throttle, but it uses a much larger count over much longer intervals (such as hours). Quota throttles are increased on the request. For a quota throttle, define throttle interval (in hour) and throttle max limit, if the throttle counter is set to Request Count.

Quota throttles are commercial throttles designed to prevent commercial overuse of the target operations, such as wholesale usage.

Example

Set the following throttle configuration for a target operation on the Config UI to allow only maximum 10 requests to be processed by a target operation within 1 hour. The following throttle configuration allows 10 requests to be processed within 1 hour and rejects the other requests within 1 hour.

---

 

Interval : 1

Max Limit: 10

Type: Quota Throttle

Monitor Counter: Request Count

---

 

Display Quota Usage Statistics

The quota usage statistics are displayed on the Organizations page of the Management Portal. See the “Configuring the API Exchange Engine and the Portal Engine" section in Chapter 2 of the TIBCO API Exchange Getting Started guide, "Deploying the Product Components” for configuration details.

Support Quota Notification

To support quota throttle notification, start each engine instance using the -n EngineName parameter for the asg-engine command:

For example, on the Windows platform, run the asg-engine as follows:

asg-engine.exe -n EngineName -u asg-gtm

where EngineName specifies a unique engine name.

If you are running multiple instances of the Core Engines, you must run the Global Throttle Manager as described in Chapter 16, "High Availability Deployment Of Runtime Components".

High Water Mark

High Water Mark throttle is similar to the Rate throttle, but this throttle also decrements the count after the passed on requests are completed and the response is ready to return to the requestor.

The High Water Mark throttle increments the throttle count on the request and decreases the throttle count once the response for that request is sent. Define a throttle max count for a high water mark throttle. Using the High Water Mark throttle, you can process a specific number of requests in parallel by a target service.

Example

High water mark throttle can be defined when the requests are sent in parallel by different users to a target operation. The target operation is slow in responding to such requests sent to it in parallel.

For example, if you want to send 5 requests to a target operation A by 5 users concurrently, define the throttle configuration for a target operation on the Config UI as follows. The following throttle configuration allows only 5 parallel requests to be served by a target operation A at a time, with this throttle configuration.

---

 

Max Limit: 5

Type: High Water Mark Throttle

---

 

Error

An Error throttle acts as a Rate Throttle in logic, but the Error throttle counts the number of error responses as opposed to the number of requests. The throttle count of an error throttle is increased on the error responses.

For an error throttle, define throttle interval (in seconds) and throttle max count. The throttle max count is reset as specified by throttle updateInterval. See Throttle UpdateInterval.

Example

You can define an error throttle for a target operation when you want to block the requests after a certain number of error responses are returned from this target operation.

Set the following throttle configuration on the Config UI if you allow only 10 error responses from a target operation within 10 seconds. This means that 10 requests are sent by the client within 10 seconds to a target operation and all the requests are processed with errors. An error response for each request is sent back to the client and the throttle count is incremented after each request is processed. The Core Engine rejects the 11th request onwards. After 10 seconds, the throttle maximum limit is reset to 0 so that the client can send the requests to the target operation again.

---

 

Interval : 10

Max Limit: 10

Throttle Type: Error Throttle

---

 

The following diagram shows how the throttles are implemented for a throttle type:

Figure 18 Throttle Types

Monitor Time Modifiers

Using TIBCO API Exchange Gateway, you can design the throttles that work on the time modifiers. You can modify the throttle limits depending on the time of the day by applying time modifiers. Throttles time modifier specifies the time ranges when the time modifier can be active. You can specify multiple days and time ranges. For example, a throttle can relax or tighten its limit based on the time of day, such as between 9am and 11am.

The time modifiers of a throttle specify when any throttle can be overridden with the new values such as date and time range, days of the week, and the throttle max count. You can specify multiple time modifiers for a single throttle of each type. The time modifier limit applies if the current time meets all the rules specified in the time modifier configuration.

Configuring Time Modifier Throttles

To configure a time modifier throttle, edit a throttle configuration and add the day, date, and time modifiers. The parameters for the throttle time modifiers are explained in the following table:

Table 87 Throttle Time Modifers

Parameter	Description
Max Count	• Specifies a maximum count that is active during this time. • Refers to a throttle limit to apply if the throttle is in range. • Required.
Start Date	• Specifies the start date when the time modifier can be active. • Optional.
End Date	• Specifies the end date when the time modifier can be active. • Optional.
Day of Week	• Specifies the days of the week when the time modifier can be active. • Optional.
Time Range	• Specifies the time ranges when the time modifier can be active. Multiple ranges can be given. • Optional.

 

• When you configure time modifiers for monitors, and if no day is selected, the time modifiers settings are applicable for all days of the week. For example, if you configure throttle time modifiers for a rate throttle as follows, the settings work for all the days of the week. − Max Count: 10 − Start Date: Current Date − End Date: Current Date − Time Range: 9 AM to 11 AM • The date and time modifiers for monitors use the local time as set on the host machine where the Core Engine instance runs. • The time zone for time modifiers should match the Server Time Zone of the Joomla! -based portal of TIBCO API Exchange. Refer to TIBCO API Exchange Manager Adapter for Joomla User's Guide to set the Server Time Zone under Location Settings of the system.

Throttle Counter

The throttle counter provides the type of counter used to increment the throttle count. The possible values for the throttle counter are as follows:

•	Request Count

The throttle count is incremented by 1 after each request is processed. To use this throttle counter, define Request Count as the throttle type for Rate, Quota, High Water Mark, Error and Content based throttles.

•	Input Payload Size

The throttle count is incremented by the size of request payload message (in bytes) after each request is processed. The Input Payload Size throttle counter is used for Payload size throttle type. See Payload Size Throttles.

•	Output Payload Size

The throttle count is incremented by the size of response payload message (in bytes) after each request is processed. The Output Payload Size throttle counter is used for Payload size throttle type. See Payload Size Throttles

•	Transaction Payload Size

The throttle count is incremented by the size of both request and response payload messages (in bytes) after each request is processed. The Transaction Payload Size throttle counter is used for Payload size throttle type. See Payload Size Throttles

Throttle UpdateInterval

Throttle UpdateInterval is the time interval (in seconds) which is used by the Core Engine to calculate the throttle count allowed until the next UpdateInterval period is lapsed.

The default value for Throttle UpdateInterval is 10 seconds. This means that the Core Engine refreshes the throttle count allowed for the next 10 seconds using the Interval and Max Limit parameters configured for the throttle Instance in the Config UI. For example, if the Interval is 60 seconds and Max Limit is 6, at most 1 request is allowed every 10 seconds.

Throttle UpdateInterval is defined by the following property in the ASG_CONFIG_HOME/asg.properties file.

      tibco.clientVar.ASG/Throttle/UpdateIntervalSec=10

 

Throttle Chaining

Using TIBCO API Exchange Gateway, you can assemble the throttles into a throttle chain. You can define multiple throttles for a partner request and service endpoint for each enforcement point.

By defining multiple throttles, you can pass a partner request through a chain of throttles to meet complex throttling needs. For example, the following throttle chains can be configured:

•	Rate and High Water Mark: this throttle chain addresses the interface load.

•	Quota: this throttle chain addresses the interface agreements.

The configuration of the throttles determines whether the request is passed on to be processed by the Core Engine or whether it is applied to any other throttle. Passing on the request to other throttles is called throttle chaining.

Copyright © Cloud Software Group, Inc. All Rights Reserved