11 Managing and Configuring Statistics and Transaction Licenses

This chapter describes the statistics functionality and the operation and maintenance procedures for statistics for Oracle Communications Services Gatekeeper.

About Statistics Generation and Reports

Oracle Communications Services Gatekeeper keeps usage statistics in terms of the number of transactions handled over time. Transactions are grouped into transaction types. Transaction types are used for calculating usage costs and for grouping reports. Transaction types are in turn grouped into different categories. For more information on transaction types, see Licensing Guide.

Statistics are generated only 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 Oracle Communications Services Gatekeeper.

Statistics are held in an in-memory store and are fflushed to database at a given time interval. Statistics reports are created based on information in the database.

It is possible to get a snapshot of the current status of the transaction, or request, counters. This information is fetched from the in-memory store.

These report types are available:

System Report to Console
System Report to File
Weekly System Report
Transaction Usage Log Report

Overview of Statistics Reports

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.

System Report to Console

This report is created by Operation: getSystemStatistics. The output is presented in the console.

System Report to File

This report is created by Operation: saveStatisticsToFile. The format is adapted for programmatic processing of the file.

Weekly System Report

The weekly report is a predefined report. It shows the total number of transactions through Oracle Communications 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.

Transaction Usage Log Report

A transaction usage log (called the license_limit log) can be extracted from Oracle Communications 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 11-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 11-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 Oracle Communications Services Gatekeeper Licensing Guide.

Counter Snapshots

Counter snapshots are real-time snapshot of the statistics counters. To see the counter snapshot for the local server, use Attribute: CounterSnapshot (r).

Table 11-1 describes the different categories into which the snapshot is organized.

Table 11-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 11-2.

Table 11-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

Managing StatisticService

The following describes managing the StatisticsService.

Configure the StatisticService

Table 11-3 describes how to configure statistics persistence interval.

Table 11-3 Configuring Statistics Persistence Interval

To configure...	Use
Statistics persistence interval	Attribute: StoreInterval

Configure Statistics Types and Transaction Types

Table 11-4 describes the operations to configure statistics types.

Table 11-4 Operations to Configure StatisticsTypes

Statistics types	Use
Add a new	Operation: addStatisticType
Remove an existing	Operation: removeStatisticType
List existing	Operation: removeStatisticType Operation: listStatisticTypes Operation: listStatisticTypeDescriptors

Statistics types

Use

Add a new

Operation: addStatisticType

Remove an existing

Operation: removeStatisticType

List existing

Operation: removeStatisticType

Operation: listStatisticTypes

Operation: listStatisticTypeDescriptors

View In-Flight Statistics counters

Table 11-5 shows the attribute used to configure a subset of the statistics counter.

Table 11-5 Attribute to Configure Subset of Statistics Counter

To Configure...	Use
A subset of the statistics counters	Attribute: CounterSnapshot (r)

Generate Statistics Reports

Table 11-6 shows the operations used to generate statistics reports.

Table 11-6 Operations to Create Statistics Reports

To generate a...	Use
Transaction usage log report	Operation: createLicenseLimitLog
Weekly report	Operation: createWeeklyReport
Statistics summary over a time interval	Operation: getStatistics
Statistics summary over the last minutes	Operation: getSystemStatistics
Statistics report to file	Operation: saveStatisticsToFile Operation: saveAccountStatisticsToFile

Add Usage Thresholds

Table 11-7 shows the atributes used to add usage thresholds.

Table 11-7 Attributes to Add Usage Thresholds

To add a...	Use
Limit alarm threshold for Oracle module-based TUPS	Attribute: ModuleBHTUPSThreshold
Limit alarm threshold for platform-based TUPS	Attribute: PlatformBHTUPSThreshold

Reference: attributes and operations for StatisticsService

Managed object: Container Services−>StatisticsService

MBean: com.bea.wlcp.wlng.statistics.management.StatisticsServiceMBean

Following is a list of attributes and operations for configuration and maintenance:

Attribute: CounterSnapshot (r)
Attribute: StoreInterval
Attribute: ModuleBHTUPSThreshold
Attribute: PlatformBHTUPSThreshold
Operation: addStatisticType
Operation: createLicenseLimitLog
Operation: createWeeklyReport
Operation: getStatistics
Operation: getSystemStatistics
Operation: listStatisticTypeDescriptors
Operation: listStatisticTypes
Operation: removeStatisticType
Operation: saveAccountStatisticsToFile
Operation: saveStatisticsToFile

Attribute: CounterSnapshot (r)

Read only.

Scope: Server

Displays a snapshot with information about all statistics-related counters for the chosen Oracle Communications Services Gatekeeper server.

The information is useful for analyzing runtime traffic and, by invoking it periodically, can be used to get an approximate value of the traffic throughput. See "Counter Snapshots".

Note:

The counters are reset periodically.

Attribute: StoreInterval

Unit: seconds.

Scope: Cluster

Specifies how often statistics data is persisted to the database.

Attribute: ModuleBHTUPSThreshold

Unit: int

Scope: Cluster

Specifies the TUPS limit alarm threshold for Oracle modules. The value of 0 means no alarms.

Attribute: PlatformBHTUPSThreshold

Unit: int

Scope: Cluster

Specifies the TUPS limit alarm threshold for platform modules The value of 0 means no alarms.

Operation: addStatisticType

Scope: Cluster

Adds a statistic type. Used to add a statistics type for custom communication services.

Signature:

addStatisticType(Id: int, Name: String)

Table 11-8 describes these parameters.

Table 11-8 addStatisticType

Parameter	Description
id	Statistic type ID
Name	Statistic type name. Descriptive name for the statistic type.

Operation: createLicenseLimitLog

Scope: Cluster

Creates a transaction usage supervision log that contains information about the busy hour transaction rate for each transaction group and day during a given time period.

Signature:

createLicenseLimitLog(filename: String, startDate: String, endDate: String)

Table 11-9 describes these parameters.

Table 11-9 createLicenseLimitLog

Parameter	Description
filename	The filename for the report. The file is created on the local file system of the selected server. Must include an absolute path. Note: The file must not already exist. If it already exists, the operation will fail.
startDate	Specifies the start date for the report. Format is YYYY-MM-DD.
endDate	Specifies the end date for the report. Format is YYYY-MM-DD.

Parameter

Description

filename

The filename for the report. The file is created on the local file system of the selected server. Must include an absolute path.

Note: The file must not already exist. If it already exists, the operation will fail.

startDate

Specifies the start date for the report.

Format is YYYY-MM-DD.

endDate

Specifies the end date for the report.

Format is YYYY-MM-DD.

Operation: createWeeklyReport

Scope: Cluster

Creates a weekly report. See "Weekly System Report" for a description of the report.

Signature:

createWeeklyReport(SpAccountId: String, StartDate: String, FileName: String, Decimals: int)

Table 11-10 describes these parameters.

Table 11-10 createWeeklyReport

Parameter	Description
SpAccountId	Service provider ID to filter on. Note: Leave empty to include all service provider account in the report.
StartDate	Specifies the start date for the report. Format is YYYY-MM-DD.
FileName	The filename for the report. Must include an absolute path. The file is created on the local file system of the selected server. Note: The file must not already exist. If it already exists, the operation will fail.
Decimals	Number of decimals in the entry for transactions/second in the report.

Operation: getStatistics

Scope: Cluster or Server

Displays a detailed statistics report for a specific service provider and application. Wildcards and filters apply.

Signature:

getStatistics(ServerName: String, StatisticType: String, fromDate: String, toDate: String)

Table 11-11 describes these parameters.

Table 11-11 getStatistics

Parameter	Description
ServerName	Specifies the name of the server to display statistics from. Leave empty to display statistics generated in all servers.
StatisticType	Specifies the statistics type ID for the statistics type to display. See "Operation: listStatisticTypes". Note: Use -1 to display all statistics types.
fromDate	Specifies the start date and time for the interval to display. Format is YYYY-MM-DD hh:mm. Note: Leave empty to display all statistics up to the date and time specified in toDate.
toDate	Specifies the end date and time for the interval to display. Format is YYYY-MM-DD hh:mm. Note: Leave empty to display all statistics generated from the date and time specified in fromDate up to current date and time.
spAccountId	Service provider account ID to filter on. Leave empty to wildcard.
appAccountId	Application account ID to filter on. Leave empty to wildcard.

Operation: getSystemStatistics

Scope: Cluster or Server

Displays a summary of system statistics for the last minutes. See "Overview of Statistics Reports" for information on output format.

Signature:

getSystemStatistics(minutes: int)

Table 11-12 describes this parameter.

Table 11-12 getSystemStatistics

Parameter	Description
minutes	The number of minutes relative to the current time.

Operation: listStatisticTypeDescriptors

Scope: Cluster

Displays a list of all available statistics type descriptors. The descriptors contain information on transactionTypeName and transactionTypeID.

Signature:

listStatisticTypeDescriptors()

Operation: listStatisticTypes

Scope: Cluster

Specifies the statistics types included in the statistics reports.

Signature:

listStatisticTypes()

Operation: removeStatisticType

Scope: Cluster

Removes a statistics type.

Signature:

removeStatisticType(statisticsType: int)

Table 11-13 describes this parameter.

Table 11-13 removeStatistics

Parameter	Description
statisticsType	ID for the statistics type.

Operation: saveAccountStatisticsToFile

Scope: Cluster/Server

Saves a statistics report to a file. Filters can be applied on service provider ID and application ID. The report is grouped by account.

Signature:

saveAccountStatisticsToFile(StatisticType: String, fromDate: String, toDate: String, serviceProviderIdentifier String, applicationIdentifier: String, filename: String)

Table 11-14 describes these parameters.

Table 11-14 saveAccountStatisticsToFile

Parameter	Description
StatisticType	ID for the statistics type. Note: Use -1 to display all statistics types.
fromDate	Specifies the start date and time for the time interval. Format is YYYY-MM-DD hh:mm. Note: Leave empty for all statistics up to the date and time specified in `toDate`.
toDate	Specifies the end date and time for the time interval. Format is YYYY-MM-DD hh:mm. Note: Leave empty for all statistics generated from the date and time specified in `fromDate` up to current date and time.
serviceProviderIdentifier	ID of the service provider to filter on. Leave empty for no filtering.
applicationIdentifier	ID of the application to filter on. Leave empty for no filtering.
filename	Specifies the filename for the report. Must include an absolute path. The file is created on the local file system of the selected server. Note: The file must not already exist. If it does already exist, the method will fail.

Operation: saveStatisticsToFile

Scope: Cluster/Server

Saves a statistics report to file.

Signature:

saveStatisticsToFile(serverName: String, StatisticType: String, fromDate: String, toDate: String, filename: String)

Table 11-15 describes these parameters.

Table 11-15 saveStatisticsToFile

Parameter	Description
serverName	Specifies the name of the server. Leave empty for statistics generated in all servers.
StatisticsType	ID for the statistics type. Note: Use -1 to display all statistics types.
fromDate	Specifies the start date and time for the time interval. Format is YYYY-MM-DD hh:mm. Note: Leave empty for all statistics up to the date and time specified in `toDate`.
toDate	Specifies the end date and time for the time interval. Format is YYYY-MM-DD hh:mm. Note: Leave empty for all statistics generated from the date and time specified in `fromDate` up to current date and time.
FileName	Specifies the filename for the report. Must include an absolute path. The file is created on the local file system of the selected server. Note: The file must not already exist. If it does already exist, the method will fail.

Transaction Types

A set of transaction types are defined for the communication services that come as a part of Oracle Communications Services Gatekeeper. The transaction type TRANSACTION_TYPE_EXTENSION is used for new communication services, developed as extensions to Oracle Communications Services Gatekeeper.

Which events generate which statistics for a certain transaction type are described in Oracle Communications Services Gatekeeper Communication Service Guide, in the discussion of statistics for the communication service in question.

The information includes correlation maps between methods being invoked from either an application or the telecom network and the corresponding transaction type. See Communication Service Guide.