This chapter describes how to configure the Oracle Communications Services Gatekeeper (OCSG) Plug-in Manager to route traffic and provides a configuration workflow. It also describes Services Gatekeeper's implementation of overload protection and how to manage it.
A plug-in is the part of a communication service that routes traffic and translates that traffic from one protocol to another. This chapter primarily explains how to use the Plug-in Manager to route traffic.
Plug-ins are modules that can be plugged into an existing deployment to extend target management or other vertical functionality. Network protocol plug-ins consist of two parts: a plug-in service and a plug-in instance. The plug-in service is the deployable and updatable unit. It does not itself process any traffic.
A plug-in service has a unique ID and a version number. It is packaged in an EAR file, with other plug-ins that share the same set of application-facing interfaces.
Plug-in instances are instantiated from a plug-in service. One plug-in service can be the base for many plug-in instances. A plug-in instance:
Has a unique ID.
Is versioned based on the plug-in service it is instantiated from.
Belongs to a type.
Exposes a set of traffic interfaces to the service communication layer. This set is a Java representation of the web services interfaces exposed by the service access layer.
Interfaces with network nodes using one or more protocols.
Supports a set of address schemes.
Is configured and managed independently of other instances.
Can be assigned a node ID to be used when setting up node SLAs.
A plug-in Manager serves as a solution for performing all plug-in deployment-related activities, through GUI as well as CLIT. The plug-in manager inspects a request and determines which interface and method the request belongs to, along with the names of any arguments. This is useful for creating a service provider group and application group SLAs.
In Services Gatekeeper, plug-in instances are created using PluginManagerMBean. A managed bean (MBean) is a Java bean that provides a Java Management Extensions (JMX) interface. For more information, see the entries in the "All Classes" section of Services Gatekeeper OAM Java API Reference.
The following section describes the execution and evaluation flow.
Plug-in managers ensure that an application's request is routed to the required network protocol plug-in instance. Service interceptors are employed to decide whether to permit, deny, or stay neutral to a particular request.
When it receives a request from an application, the plug-in manager triggers a chain of service interceptors that evaluate the following information in the request:
Data in the request originating from the application.
Status of the plug-in (only plug-ins in active status are considered).
Properties of the registered plug-ins, including:
Plug-in type.
Plug-in ID.
Refer to the Services Gatekeeper Communication Service Reference Guide for each communication service for the plug-in service ID and plug-in type under which individual plug-ins are registered.
Address plan, indicating the kind of network to which a plug-in is connected. For example, E.164 for the international public telecommunication numbering plan, or SIP.
Usage policies based on SLA settings.
Load balancing.
Data from external sources: any custom data-lookups implemented as service interceptors.
Routing logic
Service interceptors evaluate the routing logic expressed in XML. The evaluation results in the selection of a plug-in instance and the plug-in manager forwards the request to the selected plug-in.
The following interceptors use data configured using the Plug-in Manager:
CreatePluginList
RemoveInvalidRoute
The plug-in routing logic matches data in a request, and data associated with a request, with routing logic and results in the selection of a plug-in instance. The request is handed off to the selected plug-in instance for further processing.
The routing logic offers a fine grained way to select a network protocol plug-in instance and makes it possible to select a plug-in instance, and thereby a network node, to be targeted for individual requests, based on all data available in the request.
In combination with the plug-in instance feature make it possible to single out a certain network node based on the above operands and thereby:
Offer different QoS levels. Example: different network nodes offers different QoS, for example latencies for message delivery.
Ensure that requests are routed to a node that can actually handle the request. Example: one SMSC is capable of handling binary content in the form of SM logos, while another is not.
Maximize utilization of the network nodes. Example: Two network nodes offers exactly the same functionality, but one processes the request more expensively, so the selection is done based on the charging code the application supplied.
In combination with the plug-in instance feature make it possible to single out a network protocol plug-in instance even if the different plug-in instances connect to the same network node and thereby use different configurations for the request toward the network node.
For example, a network protocol plug-in offers the possibility to configure a priority parameter when sending request to the network node, by setting the parameter differently in different plug-in instances, different priorities can be used for different service providers. In the same way credentials can be mapped so the originator of the request is mapped to the request that is made to the network node.
The routing logic is expressed in XML and provides:
A set of logical operators:
AND
OR
NOT
Access to a set of operands:
The method name
All parameters in the request
The authentication data, and the data associated with the authentication data, such as service provider ID, application ID, and application instance ID.
The destination address in the request
Tunnelled parameters provided by the application as xparams in the SOAP header.
The XML based routing logic is specified per plug-in instance and routes requests to a plug-in based on logical expressions and tests that gets evaluated. Table 19-1 describes the logical operators (XML elements).
Table 19-1 Logical operators/elements for Plug-in routing
Operator/Element | Description |
---|---|
and |
This element contains 1 or many nested elements that in turn are evaluated. This expression will only be true if all the contained elements are true. |
or |
Contains 1 or many nested elements that in turn are evaluated. This expression will be true if any of the contained elements are true. |
not |
This element can contain only one nested element. This expression results in the inverse of the nested element. |
The operands are XML elements, as described in Table 19-2.
Table 19-2 Operands/elements for Plug-in routing
Operand/Element | Description |
---|---|
spId |
The service provider ID associated with the request is compared with the value given in this element. The result is true only if there is an exact match. |
appId |
The application ID associated with the request is compared with the value given in this element. The result is true only if there is an exact match. |
appInstanceId |
The application instance ID associated with the request is compared with the value given in this element. The result is true only if there is an exact match. |
destAddress |
The destination address provided in the request is compared with the value given in this element. Which parameter that is considered the destination address is plug-in specific. The format of the value is a regular expression specified as a string. The result is true only if the regular expression matches. See "Specifying Address Ranges in Routes" for examples of regular expressions. The element has the optional attribute |
method |
The name of the method that the application invoked is compared with the value given in this element. The result is true only if there is an exact match. For example:
|
param |
A named parameter in the request is compared with the value given in this element. There are three attributes to this element:
The result is true only if there is a match or if The result is true only if there is a match. The value can be expressed as a regular expression. For example:
<param name="arg0.senderName" value="tel:123.*"/> |
xparam |
A parameter supplied in the request as a tunnelled parameter (xparam) in the request is compared with the value given in this element. There are three attributes to this element:
The result is true only if there is a match or if The result is true only if there is a match. The value can be expressed as a regular expression. For example, the tunneled parameter is defined as:
A match occurs if the
|
The plug-in routing configuration XML document is validated when it is provisioned. The XML is validated according to the XSD. See "Plug-in Routing XSD".
For a set of examples, see "Plug-in Routing Configuration Examples".
The example in Example 19-1 matches requests sent to an address starting with tel:123
. If the request does not contain an address, this route does not match.
Example 19-1 Plug-in Routing Configuration Example 1
<?xml version="1.0" encoding="UTF-8"?> <route xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="route.xsd"> <destAddress>tel:123.*</destAddress> </route>
The example in Example 19-2 matches any address and also matches any request that does not contain an address.
Example 19-2 Plug-in Routing Configuration Example 2
<?xml version="1.0" encoding="UTF-8"?> <route xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="route.xsd"> <destAddress defaultResult="true">.*</destAddress> </route>
The example in Example 19-3 matches requests sent from the service provider with the ID sp1
, and the application with the ID app1
.
Example 19-3 Plug-in Routing Configuration Example 3
<?xml version="1.0" encoding="UTF-8"?> <route xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="route.xsd"> <and> <spId>sp1</appId> <appId>app1</appId> </and> </route>
The example in Example 19-4 matches all requests except the ones where the operation is sendSmsRingtone
and either sent from and application using application instance ID appInst1
or the operation is sendSms
withe the value of the parameter senderName
is tel:123456
.
Example 19-4 Plug-in Routing Configuration Example 4
<?xml version="1.0" encoding="UTF-8"?> <route xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="route.xsd"> <and> <not><method>sendSmsRingtone</method></not> <or> <appInstanceId>appInst1</appInstanceId> <and> <method>sendSms</method> <param name="arg0.senderName" value="tel:123456"/> </and> </or> </and> </route>
Following is the XSD to use when creating a plug-in routing configuration XML file.
<?xml version="1.0" encoding="utf-8"?> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:element name="route"> <xs:complexType> <xs:group ref="ConditionGroup" minOccurs="1" maxOccurs="1"/> </xs:complexType> </xs:element> <xs:group name="ConditionGroup"> <xs:choice> <xs:element name="and" type="AndType"/> <xs:element name="or" type="OrType"/> <xs:element name="not" type="NotType"/> <xs:element name="spId" type="xs:string"/> <xs:element name="appId" type="xs:string"/> <xs:element name="appInstanceId" type="xs:string"/> <xs:element name="destAddress" type="AddressType"/> <xs:element name="method" type="xs:string"/> <xs:element name="param" type="ParamType"/> <xs:element name="xparam" type="ParamType"/> </xs:choice> </xs:group> <xs:complexType name="AndType"> <xs:group ref="ConditionGroup" minOccurs="1" maxOccurs="unbounded"/> </xs:complexType> <xs:complexType name="OrType"> <xs:group ref="ConditionGroup" minOccurs="1" maxOccurs="unbounded"/> </xs:complexType> <xs:complexType name="NotType"> <xs:group ref="ConditionGroup" minOccurs="1" maxOccurs="1"/> </xs:complexType> <xs:complexType name="AddressType"> <xs:simpleContent> <xs:extension base="xs:string"> <xs:attribute name="defaultResult" type="xs:boolean" default="false"/> </xs:extension> </xs:simpleContent> </xs:complexType> <xs:complexType name="ParamType"> <xs:attribute name="name" type="xs:string" use="required"/> <xs:attribute name="value" type="xs:string" use="required"/> <xs:attribute name="defaultResult" type="xs:boolean" default="false"/> </xs:complexType> </xs:schema>
Address ranges are specified using UNIX regular expressions. A few examples are given below:
^.* specifies a route that matches all addresses.
^[0-5].* specifies a route that matches all address strings starting with 0, 1, 2, 3, 4, or 5.
^.*[6-9]$ specifies a route that matches all address strings ending with 6, 7, 8, or 9.
^46.* specifies a route that matches all address string starting with 46.
^46.{8}$ specifies a route that matches all address strings starting with 46 that contain exactly 10 total digits.
^.*@.*\.com$ specifies a route matching all mail addresses in the com domain. The dot in .com must be written "\.".
In the examples:
^ indicates the beginning of the string.
. matches anything except a new-line. That is, "a.b" matches any three-character string that begins with a and ends with b.
* is a suffix that means the preceding regular expression is to be repeated zero or more times. That is, the "." in the expression ”^46.*" is repeated until the whole string is matched.
$ is an indicator of end of line (or end of string).
The address scheme can be included in the expression. If not specified, any scheme will match. Examples:
tel:^46.*
matches all tel (E.164) numbers starting with 46.
sip:.*
matches any SIP address.
Plug-in routing logic is an extension of the plug-in routes and these PluginManagerMBean methods:
setRouteConfig
getRouteConfig
Plug-in routes added using the addRoute method, are converted into plug-in routing logic where a route is added as a logical OR given that the route that is being modified contains <or>
and <destAddress defaultResult="true">
elements only.
See "PluginManagerMBean Reference" for information on using this MBean.
Configuring the Plug-in Manager tasks include:
Configuring the general behavior of the plug-in manager.
Administering routes, which is tightly coupled to configuring individual communication services.
Following is an outline for configuring the Plug-in Manager using the PluginManagerMBean:
Specify whether or not to use policy-based routing in the PolicyBasedRouting. field. Policy based routing is necessary in order to enforce node SLAs.
Specify the network protocol plug-in behavior when it is being deployed or re-deployed in the ForceConnectInResuming field.
See "PluginManagerMBean Reference" for information on using this MBean..
Following is an outline for creating an instance of a plug-in service using the PluginManagerMBean:
Find the plug-in service ID for the service you want to use to create the plug-in instance. The plug-in service IDs are listed under the heading ”Properties” in the sections describing the management of each plug-in. To get a list of plug-in service IDs, use the listPluginServices method.
Use the createPluginInstance method to create the instance. The Plug-in Instance ID supplied as a parameter will be used to identify the instance for all routing and administration.
To destroy an instance, use the destroyPluginInstance method.
See "PluginManagerMBean Reference" for information on using this MBean.
You administer routes using these PluginManagerMBean operations:
To add new routing logic: getRouteConfig
To change or remove routing logic: getRouteConfig and setRouteConfig
To list all existing routes: listRoutes
To get information about a specific plug-in instance: getPluginServiceInfo
To get a list of all registered plug-in instances: listPluginInstances
To get a list of all registered plug-in services: listPluginServices
To define the node ID: setPluginNodeId.
A node ID is assigned to one or more Plug-in Instance IDs to enforce node SLAs. The node ID is then referred to in the node SLAs.
See "PluginManagerMBean Reference" for information on this MBean.
If a communication service does not already support bulk messaging, you can add support for it. If you want bulk messaging applied to the message address, have the PluginFactory implement the BulkRequestFactory, and implement the createSingleAddressRequest method.
To make bulk messaging apply to other types of information in the request:
Create a new class that extends AddressRequestInfo to contain the information after the message is split.
Create a new xparameter or other identifier in the original bulk request.
Define a new schema for the information in the bulk request, and add a process for it in the createRequestInfo method in the PluginFactory.
Set the information back in the createSingleAddressRequest method in the PluginFactory.
Set field values and use methods from the Administration Console by selecting Container, then Services followed by PluginManager. Alternately, use a Java application. For information on the methods and fields of the supported MBeans, see the "All Classes" section of Services Gatekeeper OAM Java API Reference.
Services Gatekeeper incorporates a framework that protects Dynamic API Framework (DAF) services against overload by rejecting incoming requests. Non-DAF communication services do not support overload protection.
Services Gatekeeper implements overload protection by periodically collecting relevant performance statistics like transaction number, Servlet session number, memory usage, CPU usage, and so on. If a metric exceeds the predefined overload threshold, Services Gatekeeper begins throttling traffic until it is no longer overloaded.
Overload protection makes the following assumptions:
It is intended to prevent the system from crashing or behaving abnormally. Features like flow control and rate limit are not taken into consideration during overload protection operations.
The system load can be represented by periodically collecting snapshot samples.
The system load is gradually increased as the system takes more and more traffic. Overload protection should take action when it detects that the system is in an overload condition and it does not recover within a period of time.
Overload Protection consists of the following four major modules:
OverloadProtectionMBean
The MBean to configure parameters related to overload protection and expose the statistics information.
StatisticsCollector
Collects the relevant performance statistics and reports to OverloadProtectionController.
OverloadProtectionController
The central controller for overload protection
TrafficThrottler
Throttles traffic with predefined ratio when the system becomes overloaded.
Services Gatekeeper overload protection does not conflict with WebLogic Server's overload protection. It works separately and focuses on:
System resource usage that is out of WebLogic Server's control, such as CPU usage
Services Gatekeeper's internal resources that reflect the system load
In general, requests are rejected before they enter WebLogic Server's overload processing.
The shaded elements in Figure 19-1 illustrate the Services Gatekeeperd overload protection components:
The OverloadProtectionMBean consists of two MBeans, one for configuration and one for producing statistics.
OverloadProtectionMBean configures the following options:
Enable overload protection attribute, EnableOverloadProtection
A true-or-false flag to enable or disable the feature (Default: true)
Enable load statistic collection attribute, EnableLoadStatisticCollection
A true-or-false flag that enables or disables the collection of system load statistics. If it is false, the system stops collecting and updating load data (Default: true).
Performance metrics to monitor, which include but are not limited to transaction number, Servlet session number, memory usage, CPU usage, and so on. Each metric has the following configuration items:
Name - name of the metric
Collector class - the class name of the PerformanceStatisticCollector for this metric
Critical metrics - true or false. If true, the metric can be the decisive factor in determining the overload status. If false, the metric is aggregated with other non-critical metrics to calculate the system load.
Valid on AT - true or false. Indicates whether the collector is valid on an AT server or not
Valid on NT - true or false. Indicates whether the collector is valid on an NT server or not. A collector must be valid on either an AT server, an NT server, or both.
Weight - a percentage between 0 and 100. If the metric is not critical, its load contributes to the system load according to the weight setting. The sum of all non-critical metrics should be 100 percent.
Overload threshold
The overload is defined in three levels: light, medium, and high. Normally, for each level, the exiting threshold should be a little bit less than the entering threshold to avoid a ping-pong effect. The following examples illustrate the three levels:
light - entering threshold of 85% and exiting threshold of 80%
medium - entering threshold of 90% and exiting threshold of 85%
high - entering threshold of 95% and exiting threshold of 90%
Number of consecutive overloads leading to protection
This option prevents the system from taking action on overload bursts, such as a one-second burst. Overload protection takes effect when the system is experiencing a heavy load and cannot recover soon. If the system can auto-recover, no action needs to be taken. The default setting is 8, which means that overload protection occurs when the system reaches the overload threshold for two consecutive collection windows.
Time period for statistics collection
Defines the timer for StatisticsCollector. Default is 4 seconds.
Traffic throttling ratio
Defines the traffic-rejecting ratio for each overload level. For example:
light: 20%
medium: 50%
high: 80%
When a change is made to the configuration, an event is issued and OverloadProtectionController and StatisticsCollector update accordingly.
Note:
SettingEnable overload protection
and Enable load statistic collection
to true
implements the complete overload protection feature.Performance statistics exposed by OverloadStatisticsMBean are based on data received from OverloadProtectionController and include:
Current system load for each metric
Current system overload status
Total time spent in overload for each level
Total number of rejected requests during overload
Statistics data is not stored in a database. It is collected and updated from system startup.
The StatisticsCollector should be a server service on each cluster node (in multi-tier, on each AT and NT machine) that is responsible for periodically collecting relevant performance data. It will use a set of collectors to do the job, as defined in the MBean, one collector for one metric. The collectors should follow the same interface so that it is easy to add new collectors. When the timer expires, the StatisticsCollector calls the getStats()
method of each collector, then composes a StatisticsReport to send to the OverloadProtectionController.
Overload protection includes three out-of-the-box collectors:
CpuLoadCollector
collects CPU usage, oracle.ocsg.overload_protection.collector.CpuLoadCollector
MemoryUsageCollector
collects memory heap usage, oracle.ocsg.overload_protection.collector.CpuLoadCollector
DafRequestCountCollector
collects the DAF request rate and compares it with a predefined threshold to determine the load percentage, oracle.ocsg.overload_protection.collector.DafRequestCountCollector
Note:
CpuLoadCollectof
is configured by defaultWith the MBean provided by WebLogic Server, the collector could collect some system metrics, like memory and CPU usage for all servers in the domain, so that it is not necessary to allocate this work to each collector. The OverloadProtectionController assigns a delegate across all collectors to collect data from WLS MBean during startup, by default the one stays on same node of the OverloadProtectionController. OverloadProtectionController should be able to change the delegate, if the current delegate is down.
If some Services Gatekeeper internal resources are important and can reflect the system load, you should create collectors to monitor the usage, one for each resource. The modules that hold such resources must provide an interface to enable the collectors to get the statistics.
The OverloadProtectionController is the central controller of overload protection, a singleton service that stays on one of the NT nodes in the domain. Each StatisticsCollector and TrafficThrottler should register itself with the OverloadProtectionController during startup, so that the controller knows how many instances are active. The major work of OverloadProtectionController includes:
Receiving a periodic StatisticsReport from StatisticsCollector
Updating the statistics data on the MBean
The OverloadProtectionController aggregates and summarizes the StatisticsReport from each StatisticsCollector and periodically updates it to the MBean.
Determining the system's overload status based on the StatisticsReport. The system load is calculated as follows:
For the non-critical metrics, the aggregated load is sum(weight * load)
The system load is the max value of the aggregated non-critical load and each critical metric's load
If the system load changes from normal to overload for predefined consecutive windows, regardless of which overload level, then the system is deemed overloaded.
Notifying the TrafficThrottler when the overload status changes
Receiving the periodic ThrottlingReport from TrafficThrottler during overload and updating the MBean
The OverloadProtectionController should aggregate and summarize the ThrottlingReport from each TrafficThrottler and then update to MBean periodically.
The communication between OverloadProtectionController and StatisticsCollector or TrafficThrottler is through RMI messages and an event channel. With WLS singleton service, the OverloadProtectionController can seamlessly switch between NT nodes without breaking service, if the current node is down.
The TrafficThrottler stays on each AT node. It is the first security provider so that it can take effect at the very beginning. If the system is not overloaded, it does nothing. When the OverloadProtectionController sends OverloadStatusInd()
to say that the system is in overload, the TrafficThrottler begins rejecting incoming requests based on the predefined ratio in the MBean, with code 503 Service Unavailable
, and collects the throttling data and sends a periodic ThrottlingReport back to the OverloadProtectionController. When the overload level is up or down, it applies a different throttling ratio. When the system quits overload, TrafficThrottler stops throttling.