The throttle mechanism is used to control access to the services at different levels. WSO2 ESB provides an effective and efficient way to apply the throttle mechanism to your Web services.
Levels of
...
throttling
You can enable throttling at the following levels in WSO2 ESB:
- Global level - If it is enabled globally, restrictions are applied globally (for every message coming into the server).
- Service level - If it is enabled for a particular service, restrictions are applied to all the messages coming into that service.
Adding Throttling to a Service
Use this function to add a throttle parameter that specifies a variable millisecond wait between calls or a variable maximum number of calls per unit of time. This would facilitate the smooth operation of Web services and REST using the Web service and HTTP client steps.
...
...
Click on the relevant tab for instructions to add a throttling policy at the required level.
Localtabgroup |
---|
Localtab |
---|
| Follow the instructions below to |
|
...
define a throttle policy at a global level. - Enter your user name and password to log on to the ESB Management Console.
|
|
...
...
- In the Modules section, click List to open the Deployed
|
|
...
...
- In the row that displays wso2throttle module, click Configure to open the Global Throttling Configuration page.
Image Added - In the Enable Throttling
|
|
...
- parameter, select Yes. The existing throttle configuration will appear in the wizard as shown in the example below.
|
|
...
- Image Added
Configure the following parameters as required to update the throttle policy. Parameter Name | Description |
---|
Maximum Concurrent Accesses | The maximum number of requests served concurrently by the service at any given time. | Range | The range of IP addresses or the domain (based on the value selected for the Type parameter) to be restricted from accessing the service. Requests from these IP addresses/domains will be restricted based on the specified values. | Type | This specifies the basis on which the clients should be restricted from accessing the proxy service. Possible values are as follows. - IP: This restricts access to the service based on the IP address of the client. If you select this, enter the relevant range ofIP addresses in the Range parameter (e.g.,
10.100.1.30-10.100.1.60 ). - Domain: This restricts access to the service based on the domain of the client. If you select this, enter the relevant domain in the Range parameter (e.g.,
*.wso2.com ).
|
|
|
...
This parameter specifies the maximum number of requests that should be handled within the time interval specified in the Unit Time parameter.
Tip |
---|
This parameter is applicable only when the value selected for the Access parameter is Control . |
...
The time interval for which the maximum number of requests specified for the Throttle ID in the Max Request Count parameter apply.
Tip |
---|
This parameter is applicable only when the value selected for the Access parameter is Control . |
...
Info |
---|
It is recommended to use IP based throttling instead of domain based throttling since the performance overhead is minimal when IP based throttling is used. Since the use of domain based throttling results in a high performance overhead, it is not provided by default with the ESB distribution. However, it can be provided as a patch if you need to use domain based throttling. |
| | This parameter specifies the maximum number of requests that should be handled within the time interval specified in the Unit Time parameter. Tip |
---|
This parameter is applicable only when the value selected for the Access parameter is Control . |
| |
|
|
...
...
| The time interval for which the maximum number of requests |
|
|
...
specified for the Throttle ID in the Max Request Count parameter |
|
|
...
apply. Tip |
---|
This parameter is applicable only when the value selected for the Access parameter is Control . |
| Prohibit Time Period (ms) | If the number of requests entered in the Max Request Count parameter is achieved before the time interval entered in the Unit Time (ms) parameter has elapsed, no more requests are taken by the inflow throttle handler for the time period entered in this parameter. Entering a value in this parameter alters the unit time. For example: Max Request Count = 50 Unit Time = 50000 ms Prohibit Time Period = 5000 ms If 50 requests are received within 35000 milliseconds, no requests will be taken for the next 5000 milliseconds. Thus, the time slot considered as the unit time is changed to 40000 milliseconds. If no value is entered in the Prohibit Time Period (ms) parameter, no requests will be taken until 15000 more milliseconds (i.e. the remainder of the unit time) have elapsed. Tip |
---|
This parameter is applicable only when the value selected for the Access parameter is Control . |
| Access | This parameter is used to specify he extent to which the IP addresses/domains specified in the Range parameter are allowed access to the service to which the throttle policy is applied. Possible values are as follows. - Allow: If this is selected, the specified IP addresses/domains are allowed to access the services to which the throttle ID is applied without any restrictions.
- Deny: If this is selected, specified IP addresses/domains are not allowed to access the services to which the throttle ID is applied.
- Control: If this is selected, the specified IP addresses/domains are allowed to access the services to which the throttle ID is applied. However, the number of times they can access the services is controlled by the Max Request Count , Unit Time (ms) ,and the Prohibit Time Period (ms) parameters.
| Actions | Click Delete in the relevant row to delete an entry. |
|
|
You can create as many entries as required by clicking Add New Entry.
- Click Finish to save the information.
|
|
Info |
---|
You can also specify the throttle policy within a proxy service configuration as a key by saving the policy in the registry or by saving it as a local entry. However, when you are not using the Management Console, you are required to manually create an entry in the < ESB_HOME/repository/deployment/server/servicemetafiles/<Service_Name>.xml file to enable throttling as shown in the example below.
Code Block |
---|
| <?xml version="1.0" encoding="UTF-8"?>
<proxy xmlns="http://ws.apache.org/ns/synapse"
name="ThrottleProxy"
transports="https http"
startOnLoad="true"
trace="disable">
<description/>
<target>
<endpoint>
<address uri="http://localhost:9000/services/SimpleStockQuoteService"/>
</endpoint>
<inSequence>
<log level="full"/>
</inSequence>
</target>
<policy key="throttlePolicy1"/>
</proxy> |
The following is an example of a throttle policy configuration that can be saved in the registry or as a local entry. Code Block |
---|
| <?xml version="1.0" encoding="UTF-8"?>
<localEntry xmlns="http://ws.apache.org/ns/synapse" key="throttlePolicy1">
<wsp:Policy xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
wsu:Id="WSO2ServiceThrottlingPolicy">
<throttle:ServiceThrottleAssertion xmlns:throttle="http://www.wso2.org/products/wso2commons/throttle">
<wsp:Policy>
<throttle:ID throttle:type="IP">10.100.0.37</throttle:ID>
<wsp:Policy>
<throttle:Control>
<wsp:Policy>
<throttle:MaximumCount>5</throttle:MaximumCount>
<throttle:UnitTime>100000</throttle:UnitTime>
<throttle:ProhibitTimePeriod wsp:Optional="true">10000</throttle:ProhibitTimePeriod>
</wsp:Policy>
</throttle:Control>
</wsp:Policy>
</wsp:Policy>
<wsp:Policy>
<throttle:ID throttle:type="DOMAIN">localhost</throttle:ID>
<wsp:Policy>
<throttle:Control>
<wsp:Policy>
<throttle:MaximumCount>5</throttle:MaximumCount>
<throttle:UnitTime>100000</throttle:UnitTime>
| Info |
---|
This section explains how to add a throttle policy to a service carry out throttling before mediation is carried out on the requests. If you want the throttling to be carried out after the requests have reached the mediation layer, you can add the Throttle mediator to the proxy configuration. |
Follow the instructions below to define a throttle policy for a service.
- Enter your user name and password to log on to the ESB Management Console.
- Click the Main tab. Under Web Services, click List to open the Deployed Services page.
Image Added - Click on the service for which you want to enable throttling to open its Service Dashboard.
Image Added In the Quality of Service Configuration panel, click Access Throttling. The Throttling Configuration page for the service will appear. Image Added In the Enable Throttling parameter, select Yes. The existing throttle configuration will appear in the wizard as shown in the example below. Image Added Configure the following parameters as required to update the throttle policy.
Parameter Name | Description |
---|
Maximum Concurrent Accesses | The maximum number of requests served concurrently by the service at any given time. | Range | The range of IP addresses or the domain (based on the value selected for the Type parameter) to be restricted from accessing the service. Requests from these IP addresses/domains will be restricted based on the specified values. | Type | This specifies the basis on which the clients should be restricted from accessing the proxy service. Possible values are as follows. - IP: This restricts access to the service based on the IP address of the client. If you select this, enter the relevant range ofIP addresses in the Range parameter (e.g.,
10.100.1.30-10.100.1.60 ). - Domain: This restricts access to the service based on the domain of the client. If you select this, enter the relevant domain in the Range parameter (e.g.,
*.wso2.com ).
Info |
---|
It is recommended to use IP based throttling instead of domain based throttling since the performance overhead is minimal when IP based throttling is used. Since the use of domain based throttling results in a high performance overhead, it is not provided by default with the ESB distribution. However, it can be provided as a patch if you need to use domain based throttling. |
| | This parameter specifies the maximum number of requests that should be handled within the time interval specified in the Unit Time parameter. Tip |
---|
This parameter is applicable only when the value selected for the Access parameter is Control . |
| | The time interval for which the maximum number of requests specified for the Throttle ID in the Max Request Count parameter apply. Tip |
---|
This parameter is applicable only when the value selected for the Access parameter is Control . |
| Prohibit Time Period (ms) | If the number of requests entered in the Max Request Count parameter is achieved before the time interval entered in the Unit Time (ms) parameter has elapsed, no more requests are taken by the inflow throttle handler for the time period entered in this parameter. Entering a value in this parameter alters the unit time. For example: Max Request Count = 50 Unit Time = 50000 ms Prohibit Time Period = 5000 ms If 50 requests are received within 35000 milliseconds, no requests will be taken for the next 5000 milliseconds. Thus, the time slot considered as the unit time is changed to 40000 milliseconds. If no value is entered in the Prohibit Time Period (ms) parameter, no requests will be taken until 15000 more milliseconds (i.e. the remainder of the unit time) have elapsed. Tip |
---|
This parameter is applicable only when the value selected for the Access parameter is Control . |
| Access | This parameter is used to specify he extent to which the IP addresses/domains specified in the Range parameter are allowed access to the service to which the throttle policy is applied. Possible values are as follows. - Allow: If this is selected, the specified IP addresses/domains are allowed to access the services to which the throttle ID is applied without any restrictions.
- Deny: If this is selected, specified IP addresses/domains are not allowed to access the services to which the throttle ID is applied.
- Control: If this is selected, the specified IP addresses/domains are allowed to access the services to which the throttle ID is applied. However, the number of times they can access the services is controlled by the Max Request Count , Unit Time (ms) ,and the Prohibit Time Period (ms) parameters.
| Actions | Click Delete in the relevant row to delete an entry. |
You can create as many entries as required by clicking Add New Entry. - Click Finish to save the information.
|
|
Info |
---|
You can also specify the throttle policy within a proxy service configuration as a key by saving the policy in the registry or by saving it as a local entry. However, when you are not using the Management Console, you are required to manually create an entry in the < ESB_HOME/repository/deployment/server/servicemetafiles/<Service_Name>.xml file to enable throttling as shown in the example below. Code Block |
---|
| <?xml version="1.0" encoding="UTF-8"?>
<serviceGroup name="ThrottleProxy" successfullyAdded="true">
<service name="ThrottleProxy"
<throttle:ProhibitTimePeriod wsp:Optional exposedAllTransports="truefalse">10000</throttle:ProhibitTimePeriod>
serviceDeployedTime="1431430083400"
</wsp:Policy> successfullyAdded="true">
</throttle:Control><operation name="mediate">
</wsp:Policy>
<module name="addressing" version="4.2.0" type="engagedModules"/>
</wsp:Policy> <module name="POXSecurityModule" version="4.2.2" type="engagedModules"/>
<wsp:Policy> <module <throttle:ID throttle:name="wso2statistics" version="4.2.2" type="IP">127.0.0.1</throttle:ID>engagedModules"/>
<module name="ServerAdminModule" <wsp:Policy>version="4.2.0" type="engagedModules"/>
<module name="pagination" version="4.2.0" type="engagedModules"/>
<throttle:Control> </operation>
<bindings>
<wsp:Policy> <binding name="ThrottleProxySoap12Binding">
<operation name="mediate"/>
<throttle:MaximumCount>5</throttle:MaximumCount> <operation name="GetMetadata"/>
</binding>
<throttle:UnitTime>100000</throttle:UnitTime> <binding name="ThrottleProxySoap11Binding">
<throttle:ProhibitTimePeriod wsp:Optional<operation name="truemediate">10000</throttle:ProhibitTimePeriod>/>
<operation name="GetMetadata"/>
</wsp:Policy>binding>
<binding name="ThrottleProxyHttpBinding">
</throttle:Control> <operation name="mediate"/>
</wsp:Policy> <operation </wsp:Policy>name="GetMetadata"/>
</throttle:ServiceThrottleAssertion>binding>
</wsp:Policy>bindings>
<policies>
<description/>
</localEntry> |
|
3. In the "Manage" menu, click on "List" under "Web Services."
Image Removed
4. The "Deployed Services" page appears.
5. Select the service for which you want to enable throttling. The "Service Dashboard" page (for that service) appears.
6. In the "Quality of Service Configuration" panel, click "Access Throttling."
Image Removed
7. The "Throttling Configuration" page appears.
Image Removed
8. In the "Enable Throttling" list, select "Yes" from the drop-down menu.
Image Removed
9. The existing throttle configuration appears in the wizard.
Image Removed
10. Click "Add New Entry."
Image Removed
Info |
---|
|
To enter new parameters or modify existing parameters, select "Allow" in the "Access" column. Image Removed |
11. Specify the parameters of a service.
Image Removed
Parameters for Throttling Configuration:
- Range - The IP address range or the domain is restricted from accessing the service. Requests from such clients will be restricted based on the specified values.
Type - This indicates the type of Range. It can be IP or DOMAIN. It should be IP if the range is given as a single IP address or a range of IP addresses (for example, 10.100.1.30-10.100.1.60). It should be DOMAIN if the range is given as as a domain (for example, *.wso2.com). If you specify both IP and DOMAIN, first priority will be given to DOMAIN level configurations.
Info |
---|
|
It is recommended to use IP based throttling instead of domain based throttling since the performance overhead is minimal when IP based throttling is used. Since the use of domain based throttling results in a high performance overhead, it is not provided by default with the ESB distribution. However, it can be provided as a patch if you need to use domain based throttling. |
- Maximum Request Count (MRC) - If Access is set to Control, it will be the maximum number of requests that are served within the time interval specified by the Unit Time parameter.
- Unit Time (UT) - The time period in milliseconds during which the maximum requests served. This is the number specified by the Maximum Request Count. The throttle starts counting the number of units from the moment it is enabled and the number of requests served within that period.
- Prohibit Time Period (PTP) - If the maximum request count is achieved before the unit time, this is the period during which no more requests are allowed to go in. By setting this value, the unit time slot is altered.
- Access
- Allow - Means that no restriction is applied for that range and all requests are allowed to go in as they come in.
- Deny - Means that access is completely denied for that range.
Control
Info |
---|
|
When the Access is set to Allow or Deny, MRC, UT and PTP parameters are not necessary and the said fields are deactivated. If it is Control, then the specified constraints are applied for that particular range. |
Example:
MRC = 50, UT = 50000, PTP = 5000
If 50 requests are arrived within 35000ms (35s) in a particular time period, no more requests are taken in for another 5000ms (5s = PTP). This time, the UT is altered to 35000ms + 5000ms = 40000ms (40s)
12. If you set the parameters for a particular service, your configuration will be applied only to that particular service. On the other hand, if you reached this page from global configurations, these configurations will be applied globally. For global engagement see Configuring Modules.
Click "Finish." Throttling will be engaged for that particular service or it will be engaged globally.
Image Removed
Functions of Buttons:
...
<policy policyType="3">
<policyUUID>WSO2ServiceThrottlingPolicy</policyUUID>
<wsp:Policy xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
wsu:Id="WSO2ServiceThrottlingPolicy">
<throttle:ServiceThrottleAssertion xmlns:throttle="http://www.wso2.org/products/wso2commons/throttle">
<wsp:Policy>
<throttle:ID throttle:type="IP">10.100.0.37</throttle:ID>
<wsp:Policy>
<throttle:Control>
<wsp:Policy>
<throttle:MaximumCount>5</throttle:MaximumCount>
<throttle:UnitTime>100000</throttle:UnitTime>
<throttle:ProhibitTimePeriod wsp:Optional="true">10000</throttle:ProhibitTimePeriod>
</wsp:Policy>
</throttle:Control>
</wsp:Policy>
</wsp:Policy>
<wsp:Policy>
<throttle:ID throttle:type="DOMAIN">localhost</throttle:ID>
<wsp:Policy>
<throttle:Control>
<wsp:Policy>
<throttle:MaximumCount>1</throttle:MaximumCount>
<throttle:UnitTime>10000</throttle:UnitTime>
<throttle:ProhibitTimePeriod wsp:Optional="true">10000</throttle:ProhibitTimePeriod>
</wsp:Policy>
</throttle:Control>
</wsp:Policy>
</wsp:Policy>
<wsp:Policy>
<throttle:ID throttle:type="IP">127.0.0.1</throttle:ID>
<wsp:Policy>
<throttle:Control>
<wsp:Policy>
<throttle:MaximumCount>1</throttle:MaximumCount>
<throttle:UnitTime>100000</throttle:UnitTime>
<throttle:ProhibitTimePeriod wsp:Optional="true">10000</throttle:ProhibitTimePeriod>
</wsp:Policy>
</throttle:Control>
</wsp:Policy>
</wsp:Policy>
</throttle:ServiceThrottleAssertion>
</wsp:Policy>
</policy>
</policies>
<module name="addressing" version="4.2.0" type="engagedModules"/>
<module name="POXSecurityModule" version="4.2.2" type="engagedModules"/>
<module name="wso2statistics" version="4.2.2" type="engagedModules"/>
<module name="ServerAdminModule" version="4.2.0" type="engagedModules"/>
<module name="pagination" version="4.2.0" type="engagedModules"/>
<parameter name="serviceType" type="1">proxy</parameter>
<policyUUID>WSO2ServiceThrottlingPolicy</policyUUID>
<parameter name="disableREST" type="1">true</parameter>
<module name="wso2throttle" version="4.2.0" type="engagedModules"/>
<association destinationPath="/repository/transports/https/listener"
type="exposedTransports"/>
<association destinationPath="/repository/transports/http/listener"
type="exposedTransports"/>
</service>
</serviceGroup> |
The proxy service configuration in this example can be as follows. Code Block |
---|
| <?xml version="1.0" encoding="UTF-8"?>
<proxy xmlns="http://ws.apache.org/ns/synapse"
name="ThrottleProxy"
transports="https http"
startOnLoad="true"
trace="disable">
<description/>
<target>
<endpoint>
<address uri="http://localhost:9000/services/SimpleStockQuoteService"/>
</endpoint>
<inSequence>
<log level="full"/>
</inSequence>
</target>
<policy key="throttlePolicy1"/>
</proxy> |
The following is an example of a throttle policy configuration that can be saved in the registry or as a local entry. Note |
---|
You need to use the same string (e.g., throttlePolicy1 ) for the throttle policy key of both the proxy service configuration, and the local entry definition, which is saved in the registry. |
Code Block |
---|
| <?xml version="1.0" encoding="UTF-8"?>
<localEntry xmlns="http://ws.apache.org/ns/synapse" key="throttlePolicy1">
<wsp:Policy xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
wsu:Id="WSO2ServiceThrottlingPolicy">
<throttle:ServiceThrottleAssertion xmlns:throttle="http://www.wso2.org/products/wso2commons/throttle">
<wsp:Policy>
<throttle:ID throttle:type="IP">10.100.0.37</throttle:ID>
<wsp:Policy>
<throttle:Control>
<wsp:Policy>
<throttle:MaximumCount>5</throttle:MaximumCount>
<throttle:UnitTime>100000</throttle:UnitTime>
<throttle:ProhibitTimePeriod wsp:Optional="true">10000</throttle:ProhibitTimePeriod>
</wsp:Policy>
</throttle:Control>
</wsp:Policy>
</wsp:Policy>
<wsp:Policy>
<throttle:ID throttle:type="DOMAIN">localhost</throttle:ID>
<wsp:Policy>
<throttle:Control>
<wsp:Policy>
<throttle:MaximumCount>5</throttle:MaximumCount>
<throttle:UnitTime>100000</throttle:UnitTime>
<throttle:ProhibitTimePeriod wsp:Optional="true">10000</throttle:ProhibitTimePeriod>
</wsp:Policy>
</throttle:Control>
</wsp:Policy>
</wsp:Policy>
<wsp:Policy>
<throttle:ID throttle:type="IP">127.0.0.1</throttle:ID>
<wsp:Policy>
<throttle:Control>
<wsp:Policy>
<throttle:MaximumCount>5</throttle:MaximumCount>
<throttle:UnitTime>100000</throttle:UnitTime>
<throttle:ProhibitTimePeriod wsp:Optional="true">10000</throttle:ProhibitTimePeriod>
</wsp:Policy>
</throttle:Control>
</wsp:Policy>
</wsp:Policy>
</throttle:ServiceThrottleAssertion>
</wsp:Policy>
<description/>
</localEntry> |
|