6.8.2 Settings for collecting user-specific performance data

To collect user-specific performance data:

Determine the information to be stored in fields.
Create user commands.
Set the scheduler to collect user-specific performance data periodically.
Specify the settings for collecting information from the user data file.

The following subsections describe the steps in this procedure.

Organization of this subsection

(1) Determining the information to be stored in fields
(2) Creating user commands
(3) Setting a scheduler to collect user-specific performance data periodically
(4) Specifying the settings for collecting information from the user data file
(5) Example of collecting user-specific performance data (for a physical host environment)
(6) Examples of user commands (for a physical host environment)
(7) Example of a batch file used to perform periodic collection (for a physical host environment)
(8) Example of collecting user-specific performance data (for a logical host environment)
(9) Examples of user commands (for a logical host environment)
(10) Example of a batch file used to perform periodic collection (for a logical host environment)

(1) Determining the information to be stored in fields

The fields of a user-defined record store two types of information, key information and data information. You will need to consider what to store as key information and what to store as data information.

(a) Key information

A user-defined record for storing user-specific performance data is a multi-instance record in which one or more rows can be stored by one collection run. To identify each record instance in one user-defined record, key information must be set. If you specify multiple user-created data files in the jpcuser command, you must set key information that uniquely identifies each record instance across all of the specified files. The following table describes the types of key information.

Table 6‒19: Types of key information
Type	Field name	Explanation
Transaction type	`Trans` `Type`	Identifies the instance type.
Transaction key	`Trans` `Data` `Key` (numeric type)	Identifies each of the instances that have the same transaction type.
Transaction key	`Trans` `String` `Key` (string type)

The transaction type is used to identify the type of the performance data. For example, assume that information about a database is stored in one record and information about a Web server is stored in another record. In this case, you can use DATABASE and WEB as transaction types to indicate which type of information (information about a database or information about a Web server) is stored.

When there are multiple instances that have the same transaction type, the transaction key is used to identify each instance. If neither the Trans Data Key field nor the Trans String Key field is set or the same value is set for multiple transaction keys, the record instances cannot be identified uniquely. As a result, the first instance of each record is used.

(b) Data information

As data information, user-defined records can store three types of numeric data (double, long, and ulong types), three lengths of string data, and time data. The number of data items that can be stored differs depending on the user-defined record. For numeric data of the PI record type, either average or cumulative can be selected as the consolidation rule.

Select the user-defined record to be used based on the performance data to be collected. Note that a user-defined record that can store a larger amount of information consumes a larger amount of memory and other resources. We recommend that you select the user-defined record whose size is the minimum necessary.

The following table lists the number of fields for each type of user-defined record.

Table 6‒20: Number of fields for each type of user-defined record
Record type	User-defined record type	Number of fields
Record type	User-defined record type	Numeric data	String data	Time data
`PD` record type	User Data Detail (`PD_UPD`)	2 × 3 = 6	1 + 2 + 4 = 7	1
`PD` record type	User Data Detail - Extended (`PD_UPDB`)	5 × 3 = 15	5 + 5 + 5 = 15	1
`PI` record type	User Data Interval (`PI_UPI`)	4 × 3 = 12	1 + 2 + 4 = 7	1
	User Data Interval - Extended (`PI_UPIB`)	10 × 3 = 30	5 + 5 + 5 = 15	1
	User Data Interval - Expanded `n`^#1 (`PI_XUIn`^#1)	60 × 1 = 60^#2	1^#3 + 2^#4 = 3	1

#1: n denotes a number in the range from 1 to 5.
#2: These are all double type.
#3: This is the number of 128-byte character strings.
#4: This is the number of 64-byte character strings.

The following table lists the criteria for selecting the recommended user-defined record.

Table 6‒21: Criteria for selecting the recommended user-defined record
Will cumulative data be stored as the performance data?	Will many types of performance data be stored?	Recommended user-defined record
Yes	No	`PI_UPI`
Yes	Yes	`PI_UPIB`, `PI_XUI1` to `PI_XUI5`
No	No	`PD_UPD`
No	Yes	`PD_UPDB`

To Page Top

(2) Creating user commands

User commands are scripts that are used to collect performance data to generate user-created data. You must code the scripts so that performance data is output in the format used for user-created data files.

For details about the format of user-created data files, see 6.8.4 Format of user-created data files.

Store the user-created data at a path that can be specified by the -file option when the jpcuser command is executed. For details, see the description of the arguments in 6.8.3 Format of the jpcuser command.

To verify the user-created data output by the user commands, execute the jpcuser command in the following format:

Physical host environment:

installation-folder\agtt\agent\jpcuser\jpcuser PI_UPI -file user-created-data -debug 1

Logical host environment:

installation-folder\agtt\agent\jpcuser\jpcuser PI_UPI -file user-created-data -debug 1 -lhost logical-host-name

When the command is executed, the following debug log file is generated:

Physical host environment:

installation-folder\agtt\agent\jpcuser\debug\jpcuser_dbg_01.log

Logical host environment:

environment-folder\jp1pc\agtt\agent\jpcuser\debug\jpcuser_dbg_01.log

Use the debug log file to check for errors.

For details about the jpcuser command, see 6.8.3 Format of the jpcuser command.

To Page Top

(3) Setting a scheduler to collect user-specific performance data periodically

The following explains how to set up the functionality for periodically executing user commands, to periodically collect user-specific performance data.

To periodically collect user-specific performance data:

Set up user record collection in PFM - Web Console.

The execution interval for functionality for periodically executing user commands depends on the Collection Interval setting for each user record.
Set the properties for functionality for periodically executing user commands in PFM - Web Console.

In PFM - Web Console, set the following properties for each user record to run functionality for periodically executing user commands^#. The method for setting these properties is the same for PD_UPD records, PD_UPDB records, PI_UPI records, PI_UPIB records, and PI_XUI1 to PI_XUI5 records.

#

Note that when you use PFM - Web Console to specify the settings for periodically collecting user-specific performance data, the service to be selected differs depending on whether a physical host or a logical host is used:

Physical host environment: Windowsphysical-host-name or TA1physical-host-name
Logical host environment: Windowslogical-host-name or TA1logical-host-name

Figure 6‒6: Properties for functionality for periodically executing user commands

Table 6‒22: Setting properties for user records
Property	Value	Description	Default value
User Command Setting - User Command Execution Timing	After/Before	By using the functionality for periodically executing user commands, specify when to execute user commands. After: Execute user commands after record collection. Before: Execute user commands before record collection.	After
User Command Setting - User Command Timeout	Integer in the range from 1 to 86,400	If you select Before as the User Command Execution Timing property of the functionality for periodically executing user commands, specify the time (seconds)^# after which the execution of user commands is discontinued. #: The specified time when the execution of user commands is discontinued must not affect the timing of other record collection processing.	5
User Command Setting - `record-name` - Execute	Yes/No	Specify whether to execute functionality for periodically executing user commands. Yes: Perform execution No: Do not perform execution	No
User Command Setting - `record-name` - UserCommand	Absolute path	Specify the absolute path for user commands. The maximum length of the string that can be specified for an absolute path is 255 bytes. Half-width alphanumeric characters and half-width symbols can be specified, except for the following characters: `\| < >`	Blank

Notes:

1. When the Execute property is set to Yes and the UserCommand property is blank, the KAVF11318-W message is output, and the user command is not executed.

2. If the specified user command does not exist, or the user command does not have execution permissions, the KAVF11007-W message is output.

3. When a logical host is used, you can use the UserCommand property to specify the path to the user commands located on the shared disk. If user commands are not located on the shared disk, you need to locate them at the same path for both the executing node and standby node.

4. If you select After as the User Command Execution Timing property, and if the executed user commands do not finish by the time the next record collection processing begins, no user command is executed.

Note: The Windows Task Scheduler can be used to periodically collect user-specific performance data. Windows includes Task Scheduler, which can automatically execute a batch file or program at the specified time and interval. After creating a batch file that executes the user commands and then the jpcuser command, set Task Scheduler so that the batch file is executed periodically.

To Page Top

(4) Specifying the settings for collecting information from the user data file

The user data file contains data that the jpcuser command has converted from user-created data into a record format that can be managed by PFM - Agent for Platform. The data in the user data file is stored in user-defined records every time PFM - Agent for Platform collects records. Make sure that PFM - Web Console is set so that PFM - Agent for Platform will collect user-defined records.

For details about how to collect records, see the chapter on Performance Management functionality in the JP1/Performance Management Planning and Configuration Guide.

To Page Top

(5) Example of collecting user-specific performance data (for a physical host environment)

This subsection provides an example of collecting process information into the PI_UPI record under the conditions shown in the following table.

Table 6‒23: Conditions for collecting performance data in the example
Option	Explanation	Corresponding field	Value
`tt`	Transaction type	`Trans` `Type`	`PROCESS`
`ki`	Transaction key (numeric type)	`Trans` `Data` `Key`	Process ID
`ks`	Transaction key (string type)	`Trans` `String` `Key`	Process name
`sm`	32-byte character string	`User` `String(32)`	Process name
`u`	Unsigned long type	`User` `Unsigned` `Long` `1`	Number of threads

To Page Top

(6) Examples of user commands (for a physical host environment)

The following are examples of user commands (userproc1.vbs and userproc2.vbs) that acquire process information from Windows and output user-created data.

userproc1.vbs:

' Output header.
WScript.Echo "Product Name=PFM-Agent for Platform (Windows)"
WScript.Echo "FormVer=0001"
' Output option header.
WScript.Echo "tt ki sm u"
' Get and output a list of processes. A string including a space is enclosed in Chr(34) codes.
for each Process in GetObject("winmgmts:").InstancesOf("win32_process")
  WScript.Echo "Process", Process.ProcessId, Chr(34) & Process.Name & Chr(34), Process.ThreadCount
next

userproc2.vbs:

' Output header.
WScript.Echo "Product Name=PFM-Agent for Platform (Windows)"
WScript.Echo "FormVer=0001"
' Output option header.
WScript.Echo "tt u"
' Get and output total amount of physical memory.
for each Memory in GetObject("winmgmts:").InstancesOf("Win32_OperatingSystem")
  WScript.Echo "TotalPhysicalMemory", Memory.TotalVisibleMemorySize
next

The following examples are examples of user-created data output by the user commands above.

Example of user-created data output by userproc1.vbs:

Product Name=PFM-Agent for Platform (Windows)
FormVer=0001
tt ki ks u
Process 0 "System Idle Process" 1
Process 8 "System" 41
Process 172 "SMSS.EXE" 6
Process 200 "CSRSS.EXE" 12
Process 196 "WINLOGON.EXE" 19
Process 248 "SERVICES.EXE" 41

Example of user-created data output by userproc2.vbs:

Product Name=PFM-Agent for Platform (Windows)
FormVer=0001
tt u
TotalPhysicalMemory 1048052

Note

For an example of collecting information about used ports, see 3.1.8 Examples of collecting information about used ports.
For an example of collecting performance data from multiple hosts on which PFM product is not installed, see 3.1.9 Examples of collecting performance data from multiple hosts on which PFM products are not installed.

To Page Top

(7) Example of a batch file used to perform periodic collection (for a physical host environment)

The following gives an example of a batch file (userperf.bat) using functionality for periodically executing user commands to perform periodic execution.

Move the REM folder
cd C:\Program Files (x86)\Hitachi\jp1pc\agtt\agent\jpcuser
REM Generate user-created data.
cscript //nologo userproc1.vbs > UPI1.txt
cscript //nologo userproc2.vbs > UPI2.txt
REM Use the jpcuser command to convert the data into a record format.
jpcuser PI_UPI -file UPI1.txt -file UPI2.txt^#

#: If -debug 2 is specified, debug log information is output to the following folder:

installation-folder\agtt\agent\jpcuser\debug\

Store the batch file (userperf.bat) and VB script in the following location:

C:\Program Files (x86)\Hitachi\jp1pc\agtt\agent\jpcuser

Note: This batch file can be periodically executed using the Windows Task Scheduler.

To Page Top

(8) Example of collecting user-specific performance data (for a logical host environment)

The table below describes an example of collecting process information into the PI_UPI record. In a logical host environment, if you include name information about the host on which user commands are executed, you can easily tell which node the command is executed on.

Table 6‒24: Conditions for collecting performance data in the example
Option	Explanation	Corresponding field	Value
`tt`	Transaction type	`Trans Type`	`PROCESS`
`ki`	Transaction key (numeric type)	`Trans Data Key`	Process ID
`sm`	32-byte character string	`User String 5`	Process name
`u`	Unsigned long type	`User Unsigned Long 1`	Number of threads
`sm`	32-byte character string	`User String 6`	Host name

To Page Top

(9) Examples of user commands (for a logical host environment)

The following are examples of user commands (userproc1.vbs) that acquire process information from Windows and output user-created data.

userproc1.vbs:

' Declare variables.
Dim objNetwork
Dim hostName
' Generate a network object.
Set objNetwork = CreateObject("WScript.Network")
' Acquire the name of the host who is executing the user command.
hostName = objNetwork.ComputerName
' Output header.
WScript.Echo "Product Name=PFM-Agent for Platform (Windows)"
WScript.Echo "FormVer=0001"
' Output option header.
WScript.Echo "tt ki sm u sm"
' Get and output a list of processes. A string including a space is enclosed in Chr(34) codes.
' Include the host name in the last field.
for each Process in GetObject("winmgmts:").InstancesOf("win32_process")
  WScript.Echo "Process", Process.ProcessId, Chr(34) & Process.Name & Chr(34), Process.ThreadCount, hostName
next
' Release the network object.
Set objNetwork = Nothing

Example of user-created data output by userproc1.vbs:

Product Name=PFM-Agent for Platform (Windows)
FormVer=0001
tt ki sm u sm
Process 0 "System Idle Process" 1 jp1-aop
Process 8 "System" 41 jp1-aop
Process 172 "SMSS.EXE" 6 jp1-aop
Process 200 "CSRSS.EXE" 12 jp1-aop
Process 196 "WINLOGON.EXE" 19 jp1-aop
Process 248 "SERVICES.EXE" 41 jp1-aop

Note

For an example of collecting information about used ports, see 3.1.8 Examples of collecting information about used ports.
For an example of collecting performance data from multiple hosts on which PFM products are not installed, see 3.1.9 Examples of collecting performance data from multiple hosts on which PFM products are not installed.

To Page Top

(10) Example of a batch file used to perform periodic collection (for a logical host environment)

The following gives an example of a batch file (userperf.bat) using functionality for periodically executing user commands to perform periodic execution.

REM Move the folder.
cd S:\jp1\userdata
REM Generate user-created data.
cscript //nologo userproc1.vbs > UPI1.txt
REM Use the jpcuser command to convert the user-created data into a record format.
"C:\Program Files (x86)\Hitachi\jp1pc\agtt\agent\jpcuser\jpcuser" PI_UPI -file UPI1.txt -lhost jp1-halaop^#

#

If -debug 2 is specified, debug log information is output to the following folder:

environment-folder\jp1pc\agtt\agent\jpcuser\debug\

Store the batch file (userperf.bat) and VB script in the following location:

S:\jp1\userdata

Note: This batch file can be periodically executed using the Windows Task Scheduler.

To Page Top