This chapter describes how to generate and manage transaction statistics that Oracle Communications Services Gatekeeper uses for licensing purposes.
Services Gatekeeper also provides a variety of API and application usage reports through the PRM Portals. For more information and instructions on how to implement them, see ”Managing Application and API Usage with Report Statistics” in Services Gatekeeper API Management Guide.
Services Gatekeeper keeps usage statistics on the number of transactions handled over time. Transactions are grouped into transaction types. Transaction types are used for calculating usage costs and grouping reports. Transaction types are in turn grouped into different categories. For more information on transaction types, see "Transaction Types" and Services Gatekeeper Licensing Guide.
These statistics are generated by communication services. Verification mechanisms ensure that all network protocol plug-ins have the statistics aspects applied. This verification takes place when the plug-in is deployed into Services Gatekeeper.
Statistics are held in an in-memory store and are periodically flushed to database. Statistics reports are created based on information in the database. You can get a snapshot of the current status of the transaction, or request, counters from the in-memory store.
Statistics are used to generate reports filtered on a number of parameters:
Time interval
Start time
End time
Individual statistics types or an aggregate of all statistics types.
Originator of the transaction:
Service provider account ID
Application account ID
Per cluster or per server
Note:
Not all combinations of the above are supported.You can retrieve reports in the following ways:
View the report in the administration console. See "Accessing the System Report from the Console".
Access online. See "Retrieving the System Report as a File".
Obtain a system report. See "Retrieving the Weekly System Report".
Obtain a transaction log report. See "Retrieving the Transaction Usage Log Report".
This report is created by the getSystemStatistics method in StatisticsServiceMBean. The output is presented in the console.
See "StatisticsServiceMBean Reference" for information on using StatisticsServiceMBean.
This report is created by the saveStatisticsToFile method in StatisticsServiceMBean. The format is adapted for programmatic processing of the file.
The weekly report is a predefined report. It shows the total number of transactions through Services Gatekeeper hour by hour during a specified week. It also shows total usage for each day and the average transaction rate (transactions/second) during the busy hour of each day. The busy hour is defined as the 60 minutes during which the largest number of transactions are handled, and it does not depend on clock hours. Any 60-minute period (5-minute intervals are used) can be identified as the busy hour.
A weekly system statistics report shows:
The total number of transactions during the specified week
The number of transactions during each hour of the days in the week
The number of transactions during each day of the week
The transaction rate (transactions/second) during the busy hour of each day
This report is stored on file.
A transaction usage log (called the license_limit log) can be extracted from Services Gatekeeper, which records the transactions on which usage costs are based. The log file contains a set of entries, where each entry represents the average transactions per second during the busy hour of a 24-hour period starting at 12:00 AM and ending 11:59 PM the previous day.
The transaction usage log report is an XML file with a header and a footer.
Example 14-1 Structure of license_limit log file
<transaction_limit_log> <start> </start> <end> </end> <log_entry> </log_entry> <checksum> </checksum> </transaction_limit_log>
All information is contained within the <transaction_limit_log> element.
A header, encapsulated by the tag <header>, contains information on the time period over which the log is generated, with a start and end date in the tags <start> and <end>, respectively. The format is DD-MM-YYYY.
Directly following the tag </end>, one or more log entries are found in the tag <log_entry>.
There is one <log_entry> element created for each day and transaction type.
This element contains a set of attributes:
group: The transaction group for which it is valid. Possible values are Platform or Oracle-modules.
start: The start date and time for the busy hour. Format is YYYY-MM-DD HH:MM, where HH is in 24-hour format.
end: The end date and time for the busy hour. Format id YYYY-MM-DD HH:MM, where HH is in 24-hour format.
tps: The average transactions per second during the busy hour. This value is compared with contractual levels by the file auditor to determine usage costs.
limit: No longer used. Filled with dummy value.
exceeded: No longer used. Always false.
A checksum is contained in the <checksum> element. The checksum is created based on the content of the file. The checksum is used for validating that the file has not been changed.
Example 14-2 License limit log file example
<transaction_limit_log> <start>2006-01-01</start> <end>2006-01-31</end> <log_entry group="BEA-modules" start="2007-01-01 13:45" end="2007-01-01 14:45" tps="27.35" limit="50" exceeded="false"/> <checksum>f8b904410896b3f92159524c6c68</checksum> </transaction_limit_log>
For more information about licensing, see Services Gatekeeper Licensing Guide.
Counter snapshots are real-time snapshot of the statistics counters. To see the counter snapshot for the local server, use the CounterSnapshot (r) field to StatisticsServerMBean.
Table 14-1 describes the different categories into which the snapshot is organized.
Table 14-1 Snapshot Categories
| Counter snapshot category | Description |
|---|---|
|
Per server |
Sum of the statistics counters for all requests regardless of the originator of the request |
|
Per server and service provider |
Sum of the statistics counters for all requests originating from a given service provider, regardless of application |
|
Per server and service provider and application |
Sum of the statistics counters for all requests originating from a given service provider and application |
The output is in the form of key/value pairs, described below in Table 14-2.
Table 14-2 Snapshot Key-Value Pairs
| Key | Value |
|---|---|
|
Source |
Server name |
|
applicationIdentifier |
Application ID; Empty if counter snapshot category is per server or per server and service provider |
|
serviceProviderIdentifier |
Service provider ID; Empty if counter snapshot category is per server or per server and service provider |
|
type |
Statistics type |
|
num of transactions |
The snapshot of the counter |
See "StatisticsServiceMBean Reference" for information on using StatisticsServiceMBean.
The following sections describe how to manage statistics StatisticsServiceMBean.
Table 14-3 describes how to configure statistics persistence interval.
Table 14-4 describes the operations to configure statistics types.
Table 14-4 Operations to Configure Statistics types in StatisticsTypeMBeans
| To configure... | Use |
|---|---|
|
Add a new type |
The addStatisticType method |
|
Remove an existing type |
The removeStatisticType method |
|
List existing |
The removeStatisticType method The listStatisticTypes method The listStatisticTypeDescriptors method |
Table 14-5 shows the attribute used to configure a subset of the statistics counter.
Table 14-6 shows the operations used to generate statistics reports.
Table 14-6 Operations to Create Statistics Reports Using StatisticsServiceMBean
| To generate a... | Use |
|---|---|
|
Transaction usage log report |
The createLicenseLimitLog method. |
|
Weekly report |
The createWeeklyReport method |
|
Statistics summary over a time interval |
The getStatistics method |
|
Statistics summary over the last minutes |
The getSystemStatistics method |
|
Statistics report to file |
The saveStatisticsToFile method The saveAccountStatisticsToFile method |
See "StatisticsServiceMBean Reference" for information on using StatisticsServiceMBean.
Table 14-7 shows the attributes used to add usage thresholds.
Table 14-7 Attributes to Add Usage Thresholds in StatisticsServiceMBean
| To add a... | Use |
|---|---|
|
Limit alarm threshold for Oracle module-based TUPS |
The ModuleBHTUPSThreshold field |
|
Limit alarm threshold for platform-based TUPS |
The PlatformBHTUPSThreshold field |
See "StatisticsServiceMBean Reference" for information on using StatisticsServiceMBean.
A set of transaction types are defined for the each of the communication services that come as a part of Services Gatekeeper. The transaction type TRANSACTION_TYPE_EXTENSION is used for new communication services, developed as extensions to Services Gatekeeper.
For a description of the events that generate statistics for a certain transaction type, see the discussion about the statistics for the communication service in Services Gatekeeper Communication Service Reference Guide.
The information includes correlation maps between methods invoked from either an application or the telecommunication network and the corresponding transaction type. See Services Gatekeeper Communication Service Reference Guide for more information.
Set field values and use methods from the Administration Console by selecting OCSG, then servername, then Container, and then StatisticsService. Use the StatisticsService operations to manage transaction types. 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.