# System Administrator’s Guide

# Managing and Configuring Budgets

The following section explains how to configure budgets and describes their relationship to SLA settings.

- Introduction

- Synchronization of budgets

- Configuration and Management
- Reference: Attributes and Operations for BudgetService
- Adding a Datasource

## Introduction

In Oracle Communications Services Gatekeeper, SLA enforcement is based on budgets maintained by the Budget service. The budget reflects the current traffic request rate based on traffic history. Each Oracle Communications Services Gatekeeper server updates both its own local traffic count and the cluster-wide count maintained in one Oracle Communications Services Gatekeeper server, the cluster master, based on load and time intervals. The cluster master is, from a cluster-perspective, a singleton service that is highly available and is guaranteed to be available by the WebLogic Server infrastructure. The cluster master is also guaranteed to be active on only one server in the cluster. This ensures accurate SLA enforcement with regards to request counters.

By default, budget quotas are enforced within the cluster. The Budget service is also capable of maintaining budget quotas across domains spread across geographic locations.

Budget values for SLAs that span longer periods of time are persisted in the persistent store to minimize the state loss if a cluster master fails.

There are two types of budget caches:

- In-memory only
- In-memory cache backed by persistent storage

When a cluster master is restarted it revives its state from the persistent store. If a cluster master fails, each Oracle Communications Services Gatekeeper server continues to independently enforce the SLA accurately to the extent possible, until the role of cluster master has been transferred to an operational server. In such a situation, a subset of the budget cache is lost: the in-memory only budget cache and the parts of the in-memory cache backed by persistent storage that have not been flushed to persistent storage. The flush intervals are configurable, see Attribute: PersistentBudgetFlushInterval and Attribute: PersistentBudgetTimeThreshold.

A desired accuracy factor for synchronizations can also be configured, see Attribute: AccuracyFactor.

The configuration settings for these affect accuracy and performance:

- The higher the Attribute: AccuracyFactor, the more granularity you have in enforcing the budgets over the time span. This requires more processing power to synchronize the budgets over the cluster.
- The higher the Attribute: PersistentBudgetFlushInterval is, the less impact persisting data has on overall performance, and the more budget data may be lost in case of server failure.
- The higher the Attribute: PersistentBudgetTimeThreshold is, the fewer budgets are likely to be persisted since this value is related to the time intervals for which time limits are defined in the SLAs. A high threshold causes less impact on database performance, but more data may be lost in case of server failure.

### Synchronization of budgets

Budgets are synchronized between all servers in a cluster according to the following algorithm:

`r` t`= r / (a * n)`

`T` t`= T / (a * n)`, where:

r t is the slave request count synchronization threshold value. r is a request limit specified in an SLA. a is the accuracy factor, see Attribute: AccuracyFactor n is the number of running WebLogic Network Servers in a cluster. Tt is the duration between counter synchronization between the slave and the master. T is a time period specified in the SLA.

#### Slave intervals

The request count is the amount of the budget that has been allocated since the last synchronization with the master. The following scenarios are possible:

1. When the request count reaches rt on a particular node it synchronizes with the master.
2. If the request count does not reach the rt value and if the count is greater than zero, the slave synchronizes with the master if the time since last synchronization reaches Tt.

Synchronization happens as a result of (1) or (2), whichever comes first.

If the request count reaches the threshold value, there will be no explicit synchronization when the timer reaches Tt.

Example:

If r = 100, n = 2 and T = 1000 milliseconds and a = 2

rt = 100 / (2 * 2) = 25 requests Tt = 1000 / (2 *2) = 250 milliseconds

The slave synchronizes with the master if the request count reaches 25 or if the time since the last synchronization is 250 ms, whichever comes first, at which point the timer is reset.

#### Master Internal

The master is responsible for enforcing the budget limits across the cluster by keeping track of the request count across all the servers in the cluster.

If there is budget available, the master updates the slaves with the remaining budget whenever the slaves synchronize with the master.

#### Failure Conditions

In the absence of the master, each slave individually enforces the budget limit but caps the requests at r/n, thereby guaranteeing that the budget count never reaches the limit.

If the slave fails before it can update the master, the master is not able to account for that server’s budget allocation, and can be rt requests out-of-sync.

Under certain circumstances, if the master allocates more than the configured budget limit, the budget will be adjusted over time.

For budgets that span longer period of time, the budget count is persisted in the database to avoid losing all state during master failures. See Attribute: PersistentBudgetTimeThreshold.

#### Budget Overrides

Budgets can have overrides defined in the SLAs. When a budget is configured with an override, the budget master determines if a given override is active. If an override is active, the budgt master enforces limits based on that active override configuration. If overrides are overlapping, no guarantees are provided on which override will be enforced.

Note: | For an override to be active all of the following must be true:

- Today’s date must be the same as or later than `startDate`
- Today’s date must be earlier than `endDate` (must not be the same date)
- Current time must be between `startTime` and `endTime`. If `endTime` is earlier than `startTime` the limit spans midnight.
- Current day of week must be between `startDow` and `endDow` or equal to `startDow` or `endDow`. If `endDow` is less than `startDow` the limit spans the week end.

Overrides are not enforced across geographically redundant sites.

#### Budget Calculations and Relationship to SLA Settings

Budgets are calculated based on the following SLA settings:

- <reqLimit> and <timePeriod> for request limits.
- <qtaLimit> and <days> for quotas.
- <reqLimitGuarantee> and <timePeriodGuarantee> for guarantee settings

The limits divided by the time-period translates into a budget increase rate, expressed in transactions per second.

Each budget has a maximum value define in the limits (<reqLimit>, <qtaLimit, and <reqLimitGuarantee>). This value is also the starting value of the budget. For each requests that is processed, the budget is decreased with one (1). Over time, the budget increases with the budget increase rate multiplied with the time, and its maximum value is the request limit. When a budget has reached the value of zero (0), requests are denied.

A maximum request rate is expressed as the number of request during a a time-period, so it offers very flexible ways to define the limits. For a given budget increase rate, expressed in transactions per second:

- The longer time-period defined, the longer it takes for requests to start to be rejected if the request rate is higher than allowed since the maximum budget value is higher.
- The shorter time-period defined, the sooner requests are starting to be rejected if the request rate is higher than allowed since the maximum budget value is lower.

Having a shorter time period means that budget synchronizations are more frequent and this has a performance impact.

If an application has used up its budget by sending more requests than allowed, and requests have started to be rejected, and the application reduces the request rate, the budget starts to increase. The budget is increased with the delta between the budget increase rate and the request rate.

Example:

An application sends 250 requests per second.

The SLA settings are:

<reqLimit>2000</reqLimit>

<timePeriod>10000</timePeriod>

This means that the budget increase rate is 2000/10000= 200 requests per second.

The difference between the request rate and the budget increase factor is 50 (250-200) so the budget will be zero (0) after 40 seconds (2000/50). When the budget is zero, requests are rejected.

Example:

An application sends 250 requests per second.

The SLA settings are

<reqLimit>200</reqLimit>

<timePeriod>1000</timePeriod>

This means that the budget increase rate is 200/1000= 200 requests per second.

The difference between the request rate and the budget increase rate is 50 (250-200) so the budget will be zero (0) after 4 seconds (200/50). When the budget is zero, requests are rejected.

Example:

An application sends 180 requests per second.

The SLA settings are

<reqLimit>200</reqLimit>

<timePeriod>1000</timePeriod>

Also, the current budget is zero (0) since it previously had a request rate that was higher than the allowed.

This means that the budget increase rate is 200/1000= 200 requests per second.

The difference between the budget increase rate and the request rate is 20 (200-180) so the budget will be at its maximum value (200) after 10 seconds (200/20). When the budget reaches its maximum value it does not increase any further.

## Configuration and Management

Configure the following attributes:

- Attribute: PersistentBudgetFlushInterval
- Attribute: PersistentBudgetTimeThreshold
- Attribute: AccuracyFactor
- Attribute: ConfigUpdateInterval

No management operations are available.

## Reference: Attributes and Operations for BudgetService

Managed object: Container ServicesBudgetService

MBean: com.bea.wlcp.wlng.core.budget.management.configuration.BudgetServiceMBean

Below is a list of attributes for configuration and maintenance.

- Attribute: PersistentBudgetFlushInterval
- Attribute: PersistentBudgetTimeThreshold
- Attribute: AccuracyFactor
- Attribute: ConfigUpdateInterval

### Attribute: PersistentBudgetFlushInterval

Scope: Cluster

Format: int

Units: milliseconds

Specifies the time interval between flushes of budgets to persistent storage. See Introduction.

### Attribute: PersistentBudgetTimeThreshold

Scope: Cluster

Format: int

Units: milliseconds

Specifies threshold value for budgets. Budgets for all time intervals defined in the SLA larger than this value are persisted. See Introduction.

### Attribute: AccuracyFactor

Scope: Cluster

Format: int

Specifies the accuracy factor. See Introduction.

### Attribute: ConfigUpdateInterval

Scope: Cluster

Format: int

Unit: milliseconds

Configuration synchronization interval between the slave nodes and the master node.

## Adding a Datasource

Under normal operating conditions, Oracle Communications Services Gatekeeper, including the Budget service, and the WebLogic Server automatic migration framework share the common transactional (XA) datasource (wlng.datasource) that has been set up for the Oracle Communications Services Gatekeeper at large. A datasource is an abstraction that handles connections with the persistent store. Under very heavy traffic it is possible for the Budget singleton service to be deactivated on all servers. This can happen if the automatic migration mechanism that supports the service becomes starved for connections. In this case, a major severity alarm is thrown: Alarm ID 111002, “Budget master unreachable”.

Note: | Datasource issues are not the only reason this alarm might be thrown.

If you encounter this problem, you can set up a separate singleton datasource for the migration mechanism that will assure that the singleton service always has access to the persistent store. This datasource should be configured to use the same database as the common transactional (XA) datasource (wlng.datasource). For more information on automatic migration of singleton services, see Oracle WebLogic Using Clusters at http://download.oracle.com/docs/cd/E12840_01/wls/docs103/cluster. Also see the section about high-availability database leasing in that document the mechanism underlying migration.

For information on setting up a separate datasource to support migration of singleton services, like the Budget service, see the section Configuring JDBC Data Sources in Oracle WebLogic Server Configuring and Managing WebLogic JDBC at http://download.oracle.com/docs/cd/E12840_01/wls/docs103/jdbc_admin/jdbc_datasources.html.