Using the HCL OneTest™ API command-line client to import data from Tivoli® Composite Application Manager for Transactions

If you are using HCL OneTest™ API 8.5.1 or later, you can use the HCL OneTest™ API command-line client to import service or transaction data from IBM® Tivoli® Composite Application Manager for Transactions.

Extraction tool

The Application Performance Monitoring (APM) extraction tool included in 8.5.1 or later can connect to a remote Tivoli® Monitoring system and extract performance information to a Microsoft™ Excel spreadsheet. The Microsoft™ Excel file can then be used to populate a performance profile, which is used to control the response-time characteristics of a stub.

Command-line usage

The APM extraction tool runs as part of the IntegrationTesterCmd command. The command name is apm-extract. For information about the apm-extract command, run the following command:

IntegrationTesterCmd help apm-extract

Output similar to the following snippet is displayed:

Options:
    --serverUrl/-u     URL of the Tivoli APM system, e.g. http//host:15210/
    --apmType          Type of APM system to connect to, defaults to Tivoli 
                       (optional)
    --file             file name to output to, will be excel (xls) format.
    --fromDate         the data and time to extract data from, in the format
                       YYYYMMDDTHHMMSS (optional)
    --toDate           the data and time to extract data to, in the format
                       YYYYMMDDTHHMMSS (optional)
    --columns          columns to extract from Tivoli database, if not supplied
                       the default is "all" (optional)
    --agentName        The Tivoli agent to query for data
    --operationName    The Tivoli operation to get statistics for (optional)
    --transactionGroup The Tivoli transaction group to query (optional)
    --period           The Tivoli time period, e.g. P1H for previous 1 hour, P2W
                       for previous 2 weeks, specify this or fromDate + toDate 
                       (optional)
    --filters          Custom filters to apply to the data in the form: column
                       =value,column=value. If using these operationName and
                       transactionGroup options will be ignored. Values will
                       need to be Tivoli API values. e.g. AGG_NAME=BuyStock or
                       GRP_LVL=Transactions (optional)
    --providerName     The Tivoli provider name to query, if not supplied will
                       default to TEMS (optional)
    --dataSourceName   The Tivoli data source name to query, if not supplied
                       this will default to "Transaction Reporter" (optional)
    --dataSetName      The Tivoli data set name to query. If not supplied this
                       will default to "Aggregates" (optional)
    --timestampColumn  Name of the column which holds the timestamp information,
                       this column will be converted from a timestamp to a
                       duration. If not specified the TIMESTAMP column will be
                       converted. (optional)
    --user             The username for HTTP authentication (optional)
    --pass             The password for HTTP authentication (optional)
Command: apm-extract

Extract performance profile information from an APM system

Output information

By default, the apm-extract command extracts information from the Aggregates table. For information about the meaning of columns, see Performance information for aggregates in IBM® Knowledge Center. The most important columns are TIMESTAMP, which the tool converts to a duration period in minutes, and TIME, which is the average time that a transaction took during the period in milliseconds.

Selecting the operation from which to extract data

To extract data, provide enough information to filter the results to an appropriate transaction group and operation name. Transaction Group is the parent of the child folders that are displayed under Transaction Reporter in the IBM® Tivoli® Enterprise Portal application. Operation Name is the name of the transaction from the Name column in the table that is displayed in that view.

Selecting the agent from which to export statistics

Provide the name of the Tivoli® Enterprise Portal agent from which to obtain data. This agent is usually in the form of hostname:TO.

Specifying the output file

Specify an output filename by using the --file option. This file will be overwritten with the information that is extracted from Tivoli® Enterprise Portal. The information from Tivoli® Enterprise Portal is extracted as a Microsoft™ Excel spreadsheet file (.xls). If no rows of data are found, the output file will contain the appropriate headers but no rows of data.

History information: Specifying a time period

To obtain history data, provide a time period by using either of the following methods:

--fromDate and --toDate
--period

Specify From and To dates in the following format (no spaces): YYYYMMDDTHHMMSS.

This format represents:

A four-digit year
A two-digit month
A two-digit day
The letter T (time)
Two-digit hours
Two-digit minutes
Two-digit seconds

for example, 20130924T141216 is September 24th, 2013 at 12 minutes and 16 seconds past 2:00 PM.

The period starts with PT followed by a number, and then a time-period identifier in hours. For example, PT24H runs a query of the last 24 hours of data.

Customizing the returned columns

By default, all of the available data columns are returned. You can filter the data columns to a smaller subset using the --columns option. Separate the columns with commas. For example, TIMESTAMP,TIME would result in an .xls file that contains only those two columns.

Data Provider, Source, and Set

By default, the APM extract command extracts information from a Tivoli® Monitoring system with the default Tivoli® Monitoring data provider. It also extracts information from the transaction reporter data source and the aggregates data set. These correspond to the Transaction Reporter view in the Tivoli® Enterprise Portal application.

Custom filters

If the default extraction from the Aggregates data set is not correct, you can provide a custom set of filters to filter on any column in any other data set. You provide these filters with the --filters option. When you provide custom filters, the --operationName and --transactionGroup options are ignored, and the filter values specified with the --filter option are used. You can specify multiple filters by using comma-separated notation. The extraction tool converts enum values from their string representation to the required numeric form.

For example, to manually specify the operationName and transactionGroup files, you would use the following option:

--filters AGG_NAME=BuyStock,GRP_LVL=Transactions

Because GRP_LVL is an enum field, transactions must be converted to the appropriate numeric value. The extraction tool uses the column information to look up the value Transactions and to convert it to the numeric value of 400, which is required for the query. AGG_NAME is the aggregate name, which in this case is a simple match.

Example usage

To retrieve information about the last week of transactions for the operation Apply For Credit Card in the Transactions group:

IntegrationTesterCmd --serverUrl http://<host name>:15210/ --agentName "sysitmsles:TO" --period P1W --user sysadmin --pass password --file c:/tmp/apm.xls --operationName "Apply For Credit Card" --transactionGroup Transaction apm-extract

To retrieve only the columns for the TIMESTAMP and the average execution time over the last hour for the BuyStock operation:

IntegrationTesterCmd --serverUrl http://<host name>:15210/ --agentName "sysitmsles:TO" --columns "TIMESTAMP,TIME" --period PT1H --user sysadmin --pass password --file c:/tmp/apm.xls --operationName BuyStock --transactionGroup Transaction apm-extract