Using the Throughput Quota Policy

Learn how to monitor web service throughput performance by specifying a throughput limit (quota), and by configuring fault and alert notifications.

For information about using policies in the context of the Community Manager developer portal, see Business Policies.

Table of Contents

Introduction

A Throughput Quota Policy is a Quality of Service (QoS) policy that allows you to monitor web service throughput performance by specifying a throughput limit (quota), and by configuring fault and alert notifications.

If the quota is exceeded, a Consumer Fault Message is returned to the service consumer and an alert is logged.

Creating a Throughput Quota Policy

The first step in creating a policy is to define the basic policy information.

To add a Quality of Service policy

  1. Go to Workbench > Browse > Organization, and select Policies > QoS Policies. The Policies Summary is displayed.
  2. Click Add Policy.
  3. Choose the policy type and click Next.
  4. Specify a name (required) and description (optional) and click Finish. At the Completion Summary, click Close. The Add Policy Wizard creates a draft policy instance that you can then configure on the Policy Details page.

For more information, see Add Policy.

Configuring the Throughput Quota Policy

Once you've defined the basic policy information, you can configure the technical details that determine how the policy works when it's attached to a service.

To configure the Throughput Quota policy

  1. Create the policy as covered above.
  2. At the Policies Summary page, in the Throughput Quota Policy section, click Modify. The Modify Throughput Quota Policy page appears, as shown below.

    Modify Throughput Quota Policy page

  3. Specify values for the policy. For information about the available settings, see Throughput Quota Policy Options.
  4. Click Finish.

Once the policy is configured, you can attach it to a service.

Throughput Quota Policy Options

The Throughput Quota policy includes the configuration options listed below.

Throughput Limit
Specify two values: first, the number of messages allowed; second, the time period (seconds or minutes). Example: 10000 messages per minute.
Queue Size
Optional (not recommended, see below): defines the concurrent threads that are queued before access is denied. This delays the consumer requests in an effort to manage a brief spike in traffic without denying access.
Note: Akana recommends that you do not use this setting. The container holds the entire content of each message in memory. There could potentially be a large number of messages held in memory, and if the messages themselves are also large, the memory and resources consumed could overwhelm the container, causing out-of-memory issues. If container restart becomes necessary, messages might be lost. In addition, a possible side-effect of slow processing is that the consumer might re-send the message. For example, if the message content includes a very large PDF file, and the message ends up in the queue, the consumer might re-send the message, which creates another instance in the queue.
If you need this functionality, you could consider implementing a Rule in combination with a queue to help ensure the queue does not get too large. For information about rules, see Policy Manager Service Rules.
Fault Message
The message that is returned if a message is rejected because the throughput limit is exceeded.
Fault Element Name
The name of the fault element.
Fault Namespace URI
Fault namespace URI.
Fault Namespace Prefix
Fault namespace prefix.
Time to Clear Alert (s)
Defines the time that the throughput needs to be within the limit before a second alert is sent to signify that the consumer is once again within quota.
HTTP Result Code
The HTTP code returned if a message is rejected because the throughput limit is exceeded. Must be in the 400 or 500 range.
Send Reminder Alert
Check the box if you want to send regular reminder alerts until the throughput is within limits.
Reminder Alert Interval (s)
The interval, in seconds, at which the reminder alert is sent, if checked. For example: 300s to send a reminder alert every five minutes.

For examples of how you can configure these properties, see Throughput Quota Policy: use cases for Policy Manager and Throughput Quota Policy: use cases for the Akana API Platform (Community Manager).

Activating a policy

When you create and configure a policy, the policy is in Draft state. When the policy configuration is complete, activate the policy: click Activate Policy and then confirm. See Activate a Policy.

A policy in Draft state is not available for general use. Once you activate the policy, it is in Active state and is available for use.

Attaching a policy

To use the Throughput Quota policy, go to the Policies folder in the respective organization and attach the policy.

This policy can be attached to an organization, service, or contract. Attaching the Throughput Quota policy to an operation is not supported.

Throughput Quota Policy: use cases for Policy Manager

This section provides a list of Policy Manager-specific usage scenarios for the Throughput Quota Policy.

Note: In a clustered scenario, you can also enable the grid counter service so that this policy works across all nodes in the cluster rather than enforcing the policy limit for each node. See Enabling the grid counter service for the Throughput Quota policy.

It includes:

  1. Generate Alert When Throughput Exceeds Limit
  2. Generate Reminder Alert When Throughput Exceeded
  3. Generate Clear Alert When Throughput Stops Crossing Limit
  4. Timeline view

Generate Alert When Throughput Exceeds Limit

Generate an alert and trigger an email to the administrator when throughput has crossed the 10 per minute limit

  1. Create a physical service in the Policy Manager Management Console using Create Physical Service.
  2. Provide service details and finish the wizard.
  3. Using Virtualize Service, virtualize and host the physical service on Network Director (ND1), and assign a name (for example, Vs1).
  4. Navigate to Organization > Policies > QoS Policies and use Add Policy to create a Throughput Quota Policy.
  5. Configure the Throughput Quota Policy as per the use case with 10 Throughput Limit per minute and a custom Fault message.

  6. Activate the policy in the Policy Workflow portlet and attach it to the Vs1 service in the Service Details > Policy Attachments > QoS section.
  7. Send 20 requests from the application/client to the Vs1 service in a minute. Results:
    1. When the Throughput limit has been exceeded, the Fault Message will be returned to the service consumer and an alert will be logged at the service level.
    2. The subsequent requests will fail after the throughput has exceeded.
    3. The details in the usage logs show the error being displayed as configured in the policy.

  8. In the alert code, an email must be configured that will be sent to the administrator, as shown below.

Generate Reminder Alert When Throughput Exceeded

Generate a reminder alert and run a management script when throughput has crossed the 5 per second limit.

  1. Create a physical service in the Policy Manager Management Console using Create Physical Service.
  2. Provide service details and finish the wizard.
  3. Using Virtualize Service, virtualize and host the physical service on Network Director (ND1), and assign a name (for example, Vs1).
  4. Navigate to Organization > Policies > QoS Policies and use Add Policy to create a Throughput Quota Policy.
  5. Configure the Throughput Quota Policy as per the use case with 5 Throughput Limit per second and a custom Fault message and reminder time interval.

  6. Activate the policy in the Policy Workflow portlet and attach it to the Vs1 service in the Service Details > Policy Attachments > QoS section.
  7. Send 10 requests from the application/client to the Vs1 service in a second.
    1. When the Throughput limit has been exceeded, the Fault Message will be returned to the service consumer and an alert will be logged at the service level.
    2. The subsequent requests will fail after the throughput has exceeded.
    3. The details in the usage logs show the error being displayed as configured in the policy.
    4. If the limit still exceeds during Reminder Alert Interval (s), a remainder alert is generated.

  8. In the reminder alert code, management script has to be configured to run (for example, to store information related to the alert as shown below).

Generate Clear Alert When Throughput Stops Crossing Limit

Generate a clear alert and trigger an email to the administrator when throughput has stopped crossing the 15 requests per second limit.

  1. Create a physical service in the Policy Manager Management Console using Create Physical Service.
  2. Provide service details and finish the wizard.
  3. Using Virtualize Service, virtualize and host the physical service on Network Director (ND1), and assign a name (for example, Vs1).
  4. Navigate to Organization > Policies > QoS Policies and use Add Policy to create a Throughput Quota Policy.
  5. Configure the Throughput Quota Policy as per the use case with 15 Throughput Limit per second and a custom Fault message.
  6. Activate the policy in the Policy Workflow portlet and attach it to the Vs1 service in the Service Details > Policy Attachments > QoS section.
  7. Send 20 requests from the application/client to the Vs1 service in a second.
    1. When the Throughput limit has been exceeded, the Fault Message will be returned to the service consumer and an alert will be logged at the service level.
    2. The subsequent requests will fail after the throughput has exceeded.
    3. The details in the usage logs show the error being displayed as configured in the policy.
    4. After the time to clear, a clear alert is generated and the subsequent requests will be successful until the Throughput quota is violated.

  8. In the clear alert code, an email must be configured that will be sent to the administrator.

Timeline view

After 60 seconds, in the new UNIX time minute, requests count from 1 (not 11).

Throughput Quota Policy: use cases for the Akana API Platform (Community Manager)

This section provides a list of Community Manager-specific usage scenarios for the Throughput Quota Policy.

It includes:

  1. Add / Configure Throughput Quota Policy
  2. Scenario 1: How Do I Verify Throughput Quota Policy at the Service Level?
  3. Scenario 2: How Do I Verify Throughput Quota Policy at the Contract Level?
  4. Scenario 3: How Do I Verify Throughput Quota Policy at License > Term Level?

Add / Configure Throughput Quota Policy

If you are using a Throughput Quota Policy with Community Manager, you must first add the policy to the Community Manager Tenant Organization in Policy Manager. Once that's done, it will be available for selection in the Community Manager developer portal.

  1. In the Policy Manager Management Console, go to the Tenant Organization, choose Policies > QoS Policies, and then click Add Policy.

  2. Specify Policy Name, Policy Type (Throughput Quota Policy), click Finish, and then click Close.

  3. On the Throughput Quota Policy Details screen, click Modify.

  4. Provide the policy details and click Finish.

  5. Activate the policy.

Scenario 1: How Do I Verify Throughput Quota Policy at the Service Level?

  1. Launch Community Manager.
  2. Attach the Throughput Quota Policy at the Service Level.

  3. Send requests from App > Test Client. If the throughput limit exceeded, a fault message will display in the response window. Alerts will display (as shown below).

  4. Go to API Monitoring > Logs and you'll see that error logs are displayed with the correct error message.

  5. In the Policy Manager Management Console, observe the following logs for the service in Monitoring > Logs.

Scenario 2: How Do I Verify Throughput Quota Policy at the Contract Level?

  1. Launch Community Manager.
  2. Attach the Throughput Quota Policy at the Contract Level and activate the contract.

  3. Send requests from App > Test Client. If the throughput limit exceeded, you will see a fault message in the response window. Alerts will be displayed as shown below.

Scenario 3: How Do I Verify Throughput Quota Policy at License > Term Level?

  1. Launch Community Manager.
  2. Attach Throughput Quota Policy at License > Term level.

  3. Test the Throughput Quota Policy at the License > Term level. This assumes that the same scope (as above) is used for Scope mapping, and the same license is selected while requesting API access.
  4. Go to Test Client and send requests. If the throughput limit exceeded, a fault message will display in the response window:

  5. Logs will display in API > Monitoring Logs:

  6. Alerts will display on the API Board: