Performance MonitorFisher- Rosemount CHIP on NT/VMS/HP- UX Interface to the PI System

and greater Document revision A

OSI Software, Inc. How to Contact Us

Phone (510) 297-5800 (main number) (510) 297-5828 (technical support) Fax (510) 357-8136 Internet [email protected] World Wide http://www.osisoft.com Web Bulletin (510) 895-9423 Board Telebit WorldBlazer modem (Hayes, MNP, or PEP compatible) 8 data bits, 1 stop bit, no parity, up to 14400 bps download protocols: Xmodem, Ymodem, Zmodem, Kermit Mail OSI Software, Inc. P.O. Box 727 San Leandro, CA 94577-0427 USA

OSI Software GmbH OSI Software, Ltd Hauptstrae 30 P. O. Box 8256 D-63674 Altenstadt 1 Level One, 6-8 Nugent Street Deutschland Auckland 3, New Zealand

Unpublished -- rights reserved under the copyright laws of the United States. RESTRICTED RIGHTS LEGEND Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013

Trademark statement—PI is a registered trademark of OSI Software, Inc. Microsoft Windows, Microsoft Windows for Workgroups, and Microsoft NT are registered trademarks of Microsoft Corporation. Solaris is a registered trademark of Sun Microsystems. HP-UX is a registered trademark of Hewlett Packard Corp. IBM AIX RS/6000 is a registered trademark of the IBM Corporation. DUX, DEC VAX and DEC Alpha are registered trademarks of the Digital Equipment Corporation. 00f5c8fe863fb20a1062557828a9c424.doc

 2000 - 2001 OSI Software, Inc. All rights reserved 777 Davis Street, Suite 250, San Leandro, CA 94577

10／16／2004 02:02:00 上午 ii Table of Contents

Introduction...... 1 Reference Manuals...... 1 Supported Features...... 1 Diagram of Hardware Connection...... 3

PI Point Configuration...... 5 Performance Counter Path...... 5 Point Attributes...... 5

PIPerfCreator Utility...... 9

Installing PIPerfmon on NT/2000...... 13

Startup Command File...... 15 PIPerfMon ICU Control...... 15 Command Line Parameters...... 15

Interface Node Clock...... 21

Running the Interface on NT/2000...... 23 PIPerfmon as an NT Service...... 25 PIPerfmon Interactively, Not as a Service...... 26

Picking up PIPerfmon Point Database Changes...... 27

Full and Basic Versions...... 29

Monitoring Basics...... 31

Limitations...... 39

Troubleshooting...... 41 Common Problems...... 41 Error Codes...... 42

iii OSI Software, Inc. Introduction

The PI Performance Monitor interface obtains Microsoft Windows NT/2000 performance counter data and sends it to the PI System. The interface program reads the PI point database to determine which performance counters to read. It then scans for the performance counter and sends exception reports to the PI system. This interface runs on Microsoft Windows NT/2000 operating systems. There are two versions of the interface, the FULL version and the BASIC version. Please refer to the Full and Basic Versions section of this manual for further details.

Reference Manuals

OSIsoft  UniInt End User Document  PI Data Archive Manual  PI-API Installation Instructions

Supported Features

Features Support Part Number PI-IN-OS-PERF NTI Interface Platforms NT-Intel PI Point Types Float16 / Float32 / Float64 / Int16 / Int32 Sub-Second Timestamps Yes Sub-Second Scan Classes Yes Automatically Incorporates PI Point Attribute Yes Changes Exception Reporting Yes, done by Interface Outputs from PI No Inputs to PI: Scan-based / Unsolicited / Event Scan-based Tags Maximum Point Count Unlimited (full), 32 points (basic) Uses PI-SDK Yes PINet to PI 3 String Support No Source of Timestamps PI System Time History Recovery No

Performance Monitor Interface to the PI System 1 Introduction

Features Support Failover No *UniInt-Based Yes Vendor Software Required on PI API / PINet No node Vendor Software Required on Foreign Device No Vendor Hardware Required No *Additional PI Software Included with Interface Yes Device Point Types No * Further explanation below.

Source of Timestamps The interface uses the PI System timestamp.

UniInt-Based UniInt stands for Universal Interface. UniInt is not a separate product or file; it is an OSIsoft-developed template used by our developers, and is integrated into many interfaces, such as the PI Performance Monitor interface. The purpose of UniInt is to keep a consistent feature set and behavior across as many of our interfaces as possible. It also allows for the very rapid development of new interfaces. In any UniInt-based interface, the interface uses some of the UniInt-supplied configuration parameters and some interface-specific parameters. UniInt is constantly being upgraded with new options and features. The UniInt End User Document is a supplement to this manual.

Additional PI Software The interface provides a performance counter point creation utility ( PIPerfCreator ) to help facilitate the creation of performance monitor points. This is a stand-alone application that requires that the PI-SDK be installed on the same machine the utility is installed on. The details of the utility will be discussed later in this document.

2 OSI Software, Inc. Diagram of Hardware Connection

P I S e r v e r O p e n V M S , N T , H P U X , D U X T C P / I P

P I - A P I - N T I P I - S D K - N T I P I S e r v e r

P I - I N I n t e r f a c e P I - A P I - N T I P I - S D K - N T I

P I - I N I n t e r f a c e P e r f o r m a n c e C o u n t e r s P e r f o r m a n c e W i n d o w s C o u n t e r s W i n d o w s N T / 2 0 0 0 N T / 2 0 0 0

T C P / I P T C P / I P

P e r f o r m a n c e P e r f o r m a n c e C o u n t e r s C o u n t e r s

W i n d o w s W i n d o w s N T / 2 0 0 0 N T / 2 0 0 0

Performance Monitor Interface to the PI System 3 PI Point Configuration

A PI point or tag is associated with a single performance counter. A counter is unit of performance associated with the performance object. It provides data related to a single item of the system. A machine's performance objects include physical components, such as processors, disks, and memory. There are also system objects, such as processes and threads. Each object is related to a functional element within the computer and has a set of standard counters assigned to it. For example the % Processor Time is a performance counter that measures the amount of processor time a performance object, such as the Processor, utilizes. Performance Counter Path

This interface needs the performance counter path in order to obtain data for the specific performance counter. A performance counter path is the identifier of a counter for inclusion in gathering performance data. The counter names must be formatted a specific way in order to be properly recognized. The format is:

\\Machine\PerfObject(ParentInstance/ObjectInstance#InstanceIndex)\Counter

The \\Machine portion is optional; if included, it specifies the name of the machine. If you do not include a machine name, the local machine that the interface is running on is used. The \PerfObject component is required; it specifies the performance object that contains the counter. If the object supports variable instances, then you must also specify an instance string. The format of the (ParentInstance/ObjectInstance#InstanceIndex) portion depends on the type of object specified. If the object has simple instances, then the format is just the instance name in parentheses. For example, an instance for the Process object would be the process name such as (Explorer) or (MyApp). The \Counter portion is required and it specifies the performance counter. For example the Process object has counters such as % Processor Time and Interrupts/Sec. Obtaining and knowing the performance counter path for every performance counter is a daunting task. Therefore, this interface includes the PIPerfCreator utility (referenced later). This program can be used to obtain the performance counter path and create the performance counter points. Point Attributes

The following are a list of point attributes that are required by the interface.

4 Tag A tag is a label or name for a point. Any tag name can be used in accordance to the normal PI point naming conventions.

Point Source The PointSource is a single, unique character that is used to identify the PI point as a point that belongs to a particular interface. For example, one may choose the letter # to identify points that belong to the PI Performance Monitor interface. To implement this, one would set the PointSource attribute to # for every PI Point that is configured for the PI Performance Monitor interface. Then, if one uses /ps=# on the startup- command line of the PI Performance Monitor interface, the Random interface will search the PI Point Database upon startup for every PI point that is configured with a PointSource of #. Before an interface loads a point, the interface usually performs further checks by examining additional PI point attributes to determine whether a particular point is valid for the interface. For additional information, see the /ps argument. The following point source characters are reserved on PI 2 systems and cannot be used as the point source character for an interface: C, ?, @, Q, T. Also, if one does not specify a point source character when creating a PI point, the point is assigned a default point source character of L. Therefore, it would be confusing to use L as the point source character for an interface. Before a PI point with a given point source can be created, the point source character must be added to the PI 2 point source table. For example, if point source #is not defined in the PI 2 point source table, a point with a point source of #cannot be created. This prevents the user from accidentally creating a point with an incorrect point source character.

Point Type R or I for PI 2 systems. Int16, Int32, float16, and float32 PI 3 systems.

Extended Descriptor (Performance Counter Path) This parameter is a string that is used to specify the performance counter path. The performance counter path can be obtained using the PIPerfCreator.exe utility for a PI 3 Server. For a PI 2 Server, the extended descriptor is limited to 80 characters. For a PI 3 Server, the extended descriptor is limited to 1024 characters.

Location1 (Interface ID) This parameter is used to specify the interface number, which corresponds to the /id=# flag in the pierfmon.bat (piperfmon_basic.bat for the basic version) file. Valid interface numbers are integer values 1 to 99, inclusive.

Location4 (Scan Class) Location4 defines the scan class for the PI point. The scan class determines the frequency at which input points are scanned for new values. This parameter determines the scan class of the tag. The number of scan classes and the scan frequencies are specified in the interface startup command file. A value of 1 in

Performance Monitor Interface to the PI System 5 PI Point Configuration

Location4 assigns this tag to the first scan class specified in the startup file; a value of 3 assigns the tag to the third scan class.

Convers This parameter is used to scale the input into the PI Server. The default is set to 1. The input is multiplied by this number and then sent to PI.

These point attributes also affect the interface program.  Scan  Exception Deviation  Exception Minimum Time  Exception Maximum Time  Shutdown

The following point attributes do not apply to this interface’s points.  SquareRoot  TotalCode  Location2  Location3  Location5  Digital Start Code and Digital Number (PI 2.X)  Digital State Set (PI 3.X)

6 OSI Software, Inc. PIPerfCreator Utility

The utility PIPerfCreator.exe is also included with the full and basic versions of the interface to obtain the performance counter strings and create PI points on PI 3 Servers. The utility also requires that the PI-SDK and the piperfmondll.dll be installed on the machine that runs the program. This program contains two tabs, Main and Compression. Figure 1shows the Main tab, which is the default when the program is launched.

Figure 1 PIPerfCreator Main tab Within the Main tab, the essential tag attributes of a performance monitor points are displayed. Most of these attributes have been explained in the Input section of this

manual. One of the most important features on this tab is the three dot button ( ) that is at the right of the ExDesc field. This three dot button is used to obtain the performance counter path from a list of performance counters. When this button is pressed, a dialog box appears (Figure 2).

7 PIPerfCreator Utility

Figure 2 Get Counter Path Dialog Box First select the performance object. Once the object is selected a list of performance counters will appear in the display box below. Simply select the performance counter that is desired and then press the OK button. (Selecting All Counter or All Instances will result in selecting the first counter and instance respectively.) This will put the performance counter path in the ExDesc field (Figure 3).

8 OSI Software, Inc. Figure 3 PIPerfCreator Main tab filled If the “Use counter path as name” check box is checked, the name of the tag will be the performance counter path with the illegal tag characters removed (refer to the PI Server manual for a list of the illegal tag characters). If the “Include Explain Text” check box is checked, the explanatory text associated with the performance counter is put in the Descriptor field. The Tag Style option refers to the style in which the tag name is to be shown. You can either choose to replace the illegal tag characters with a space or an underscore.

The second tab is the Compression tab (Figure 4). The compression tab contains the compression and exception information for the point.

Performance Monitor Interface to the PI System 9 PIPerfCreator Utility

Figure 4 Compression Tab

The standard defaults are chosen initially. The only parameters that may be changed automatically are the Span and Typical Value. When the three dot button is used to select the performance counter, the span will be changed to reflect the performance counter default span and the typical value will be half of the span. A default span is feature that is known for each performance counter. The PIPerfCreator utility can be run independently of the performance monitor interface. The interface does not need to be started for the utility to work. However, the interface will not pick up the created points and send data to the PI Server until the interface is started.

10 OSI Software, Inc. Installing PIPerfmon on NT/2000

The interface uses the Microsoft Windows Installer technology for installation. This installation will install the Microsoft Windows Installer and/or the PI-SDK if the Microsoft Installer and/or the PI-SDK are not installed. The file piperfmon.bat (piperfmon_basic.bat for the basic version) contains startup parameters described in the next section. You should modify that file to suit your system’s need. The full version performance monitor interface installation will install the following files: piperfmon.exe : PIPerfmon Interface executable file piperfmon.bat : Startup command file piperfmon.bat.new: Unedited shipped startup command file pdh.dll : Performance Data Helper (dynamic linked library) PIPerfCreator.exe : Performance counter path utility piperfmondll.dll: PIPerfmon utility dll piperfmon.doc: Interface documentation Example interface directory structure The following files should be installed: Program Files\ PIPC\ PIPerfMon\ piperfmon.exe piperfmon.bat piperfmon.bat.new PIPerfCreator.exe piperfmondll.DLL piperfmon.dic

WINNT\ system32\ Pdh.dll

The basic version of the performance monitor interface installation will install the following files: piperfmon_basic.exe : PIPerfmon Interface executable file piperfmon_basic.bat : Startup command file piperfmon.bat.new: Unedited shipped startup command file pdh.dll : Performance Data Helper (dynamic linked library) PIPerfCreator.exe : Performance counter path utility piperfmondll.dll: PIPerfmon utility dll piperfmon.doc: Interface documentation 11 Installing PIPerfmon on NT/2000

Example interface directory structure The following files should be installed: Program Files\ PIPC\ PIPerfMon\ piperfmon_basic.exe piperfmon_basic.bat piperfmon_basic.bat.new PIPerfCreator.exe piperfmondll.DLL piperfmon.dic

WINNT\ system32\ pdh.dll

12 OSI Software, Inc. Startup Command File

PIPerfMon ICU Control

The PI-Perfmon interface on Windows has an ICU Control that will aid in configuring the PI-Perfmon interface startup command file:

Interface Debug Levels The enable interface debugging option enables the interface to write debug messages to the log file. The debug levels are 0-9 where 9 is the setting for the most debug messages. The command line equivalent is /deb.

Additional Arguments The Additional Arguments section is provided for any flags that may be required in the future. Command Line Parameters

If the Interface Configuration Utility is not used to configure the startup parameters, the following explains the parameters and their usage. The command file names have a .bat extension. The continuation character (^) allows one to use multiple lines for the startup command. The maximum length of each line is 1024 characters (1 kilobyte). The number of flags is unlimited, and the maximum length of each flag is 1024 characters. Command-line arguments can begin with a / or with a -. For example, the /ps=M and -ps=M command-line arguments are equivalent.

13 Startup Command File

There are several option parameters in piperfmon.bat (piperfmon_basic.bat for the basic version) that control the operation of the interface program. Some of the parameters are optional. The parameters are described in the table below:

Parameter Description /ps=x The /ps flag specifies the point source for the interface. x is not case sensitive and can be any single character. For example, (required) /ps=# The point source that is assigned with the /ps flag corresponds to the PointSource attribute of individual PI Points. The interface will attempt to load only those PI points with the appropriate point source. Strategies for assigning a point source character vary depending on the interpretation of the /id flag by a particular interface. See the /id flag for more information. /host=host:port The /host flag is used to specify the PI Home node. host is the IP address of the PI Sever node or the domain name of the PI Server (optional) node. port is the port number for TCP/IP communication. The port is always 5450 for a PI 3 Server, and the port is always 545 for a PI 2 server. It is recommended to explicitly define the host and port on the command line with the /host flag. Nevertheless, if either the host or port is not specified, the interface will attempt to use defaults. Defaults: The default port name and server name is specified in the pilogin.ini or piclient.ini file. The piclient.ini file is ignored if a pilogin.ini file is found. Refer to the PI-API Installation Instructions manual for more information on the piclient.ini and pilogin.ini files. Examples: The interface is running on an API node, the domain name of the PI 3 home node is Marvin, and the IP address of Marvin is 206.79.198.30. Valid /host flags would be: /host=marvin /host=marvin:5450 /host=206.79.198.30 /host=206.79.198.30:5450

14 OSI Software, Inc. Parameter Description /id=x The /id flag is used to specify the interface identifier. For example, (required) /id=int1 The interface identifier is a string that is no longer than 9 characters in length. Uniint concatenates this string to the header that is used to identify error messages as belonging to a particular interface. See the section called “Error and Informational Messages” for more information. Uniint always uses the /id flag in the fashion described above. Many interfaces also use the /id flag to identify a particular interface copy number that corresponds to an integer value that is assigned to one of the Location code point attributes, most frequently Location1. For these interfaces, one should use only numeric characters in the identifier. For example, /id=1 When an interface uses the /id flag to specify an interface copy number, the point source character should be the same for all copies of the interface. For example, all PI points for the Modbus interface are typically configured with a point source of M. Modbus points are distinguished as belonging to a particular copy of the Modbus interface by assigning a copy number to the Location1 attribute of the point, which, in turn, corresponds to the copy number designated by the /id flag. If the interface does not have a flag such as the /id flag to identify a particular copy of the interface, a different point source must be used for each copy of the interface. Interfaces sometimes use other arguments besides the /id flag (such as /in, /ic, etc) to identify the copy of an interface. Consult the interface-specific documentation for more information.

Performance Monitor Interface to the PI System 15 Startup Command File

Parameter Description /f=SS The /f flag defines the time period between scans in terms of or hours (HH), minutes (MM), and seconds (SS). The scans can be /f=SS,SS scheduled to occur at discrete moments in time with an optional or time offset specified in terms of hours (hh), minutes (mm), and /f=HH:MM:SS seconds (ss). If HH and MM are omitted, then the time period that or is specified is assumed to be in seconds. /f=HH:MM:SS,hh:mm :ss Each instance of the /f flag on the command line defines a scan class for the interface. There is no limit to the number of scan (required) classes that can be defined. The first occurrence of the /f flag on the command line defines the first scan class of the interface, the second occurrence defines the second scan class, and so on. PI Points are associated with a particular scan class via the Location4 PI Point attribute. For example, all PI Points that have Location4 set to 1 will receive input values at the frequency defined by the first scan class. Similarly, all points that have Location4 set to 2 will receive input values at the frequency specified by the second scan class, and so on. Two scan classes are defined in the following example: /f=00:01:00,00:00:05 /f=00:00:07 or, equivalently: /f=60,5 /f=7 The first scan class has a scanning frequency of 1 minute with an offset of 5 seconds, and the second scan class has a scanning frequency of 7 seconds. When an offset is specified, the scans occur at discrete moments in time according to the formula: scan times = (reference time) + n(frequency) + offset where n is an integer and the reference time is midnight on the day that the interface was started. In the above example, frequency is 60 seconds and offset is 5 seconds for the first scan class. This means that if the interface was started at 05:06:06, the first scan would be at 05:06:10, the second scan would be at 05:07:10, and so on. Since no offset is specified for the second scan class, the absolute scan times are undefined. The definition of a scan class does not guarantee that the associated points will be scanned at the given frequency. If the interface is under a large load, then some scans may occur late or be skipped entirely. See the section called “Performance Point Configuration” for more information on skipped or missed scans.

Sub-Second Scan Classes One can also specify sub-second scan classes on the command line such as /f=0.5 /f=0.1 where the scanning frequency associated with the first scan class is 0.5 seconds and the scanning frequency associated with the second scan class is 0.1 seconds. Similarly, sub-second scan classes with sub-second offsets can be defined, such as /f=0.5,0.2 /f=1,0

16 OSI Software, Inc. Parameter Description /ec= Specifies the event counter number. The event counter is used for pi 2.x system. Current version of pi 3.x system does not support (optional) event counter. /sn Tells the interface to ignore the exception specifications of the tag and put all the input events into the PI snapshot. By default, the (optional) SN flag is not used to reduce data traffic. /dbuniint The /dbuniint flag is used to set a debug level for debugging UniInt code. level is a 32-bit integer. Setting a particular bit in (optional) level to 1 turns on a particular debug switch. To turn on every debug switch specify: /dbuniint=0xFFFF Note that level can be specified as either a decimal number or a hexadecimal number. A 0x must precede hexadecimal numbers. Debug Switches Section of code that is debugged 0x0002 Initialization 0x0004 Point addition (add_pt) 0x0008 Exit handler 0x0010 Sending data to PI (update_pi) 0x0020 The main control loop 0x0040 Point list creation (load_lists) 0x0080 Point edits 0x0100 IO Rate Points 0x0200 Services /stopstat If the /stopstat flag is present on the startup command line, or then the digital state I/O Timeout will be written to each PI Point /stopatat= when the interface is stopped. digstate If /stopstat=digstate is present on the command line, then default: the digital state, digstate, will be written to each PI Point when /stopstat= the interface is stopped. For a PI 3 Server, digstate must be in ”Intf shut” the system digital state table. For a PI 2 Server, where there is only optional one digital state table available, digstate must simply be somewhere in the table. UniInt uses the first occurrence in the table. If neither /stopstat nor /stopstat=digstate is specified on the command line, then no digital states will be written when the interface is shut down. Examples: /stopstat=”Intf shut” The entire parameter is enclosed within double quotes when there is a space in digstate.

Performance Monitor Interface to the PI System 17 Startup Command File

Parameter Description /q Tells the interface to queue up events before putting the data into the PI system. The q version is more efficient if the interface is on (optional) a separate computer from the PI Server. However, it will slightly delay the update of the snapshot value if the data rate is low. The buffer size of the event queue for the interface is 128 events.

The following is a sample full version interface startup command file (piperfmon.bat). Piperfmon /ps=# /Q /host=localhost:5450 /id= 1 /f=00:00:05 /f=00:01:00

Home Node is a PI 2.x Server For an interface talking to a PI 2.X Server, you need to configure the Server by adding event counter tags and the point source as described below. Define each tag added to IORates.dat using PIDIFF or the Point Def display on the PI System node. You may use SY:SNP001 as a template tag in the Point Def display. Add the point source character chosen for the PIPerfMon interface to the PI System using the Point Src display. This lets PI access and maintenance functions recognize the new interface and allow creation of its tags. The location maximum and minimum values are shown below.

Location 1 2 3 4 5 number Minimum 1 0 0 1 0 Maximum 99 0 0 32 0 You don’t need to define the point source character separately from the PI tags in a PI 3.X Server.

18 OSI Software, Inc. Interface Node Clock

The correct settings for the time and time zone should be set in the Date/Time control panel. If local time participates in Daylight Savings, from the control panel, configure the time to be automatically adjusted for Daylight Savings Time. The correct local settings should be used even if the interface node runs in a different time zone than the PI Server node. Make sure that the TZ environment variable is not defined. The currently defined environment variables can be listed by going to Start | Settings | Control Panel, double clicking on the system icon, and selecting the environment tab on the resulting dialog box. Also, make sure that the TZ variable is not defined in an autoexec.bat file. When the TZ variable is defined in an autoexec.bat file, the TZ variable may not appear as being defined in the System control panel even though the variable is defined. Admittedly, autoexec.bat files are not typically used on NT, but this does not prevent a rogue user from creating such a file and defining the TZ variable unbeknownst to the System Administrator.

19 Running the Interface on NT/2000

The PI Server that the interface connects to must be in the known servers table otherwise the interface will not start up. To check to see if the PI Server is in the known servers table, run the About PI-SDK executable in the pisdk directory and select the Connect button (Figure 5).

Figure 5 About PI-SDK Dialog

The Server Information Dialog box should appear with the name of the default PI Server (Figure 6).

20 Figure 6 Connections Dialog

If this is the name of the server of interest then you are done. If you need to add a server hit the Connections button and then choose Add Server if the list of servers does not include your PI Server (Figure 7).

Performance Monitor Interface to the PI System 21 Running the Interface on NT/2000

Figure 7 Adding a PI Server

PIPerfmon as an NT Service

The PIPerfmon Service The installation of the interface may have already installed the interface as a service. Check the Service Control in the Control Panel to see if the interface has been installed as a service. To register the full version of PIPerfMon as a service do the following: c:\pipc\interfaces\PIPerfMon\piperfmon –install –depend pinetmgr or c:\pipc\interfaces\PIPerfMon\piperfmon –install –auto –depend pinetmgr to register the PIPerfMon service to start automatically at NT startup. The basic version is registered in the same manner c:\pipc\interfaces\PIPerfMon\piperfmon_basic –install –depend pinetmgr or c:\pipc\interfaces\PIPerfMon\piperfmon_basic –install –auto –depend pinetmgr The service will run using the Local System account unless otherwise specified. For the full version of this interface, if this account does not have privileges to obtain performance counters on a remote computer, the service will have be changed to start using an account with sufficient privileges. To open the Services control panel for Windows 2000, click Start, point to Settings, and then click Control Panel. Double- click Administrative Tools, and then double-click Services. For Window NT, click Start, point to Settings, and then click Control Panel. Double-click on Services. Then, double-click on PI Performance Monitor Interface (full version) and select

22 OSI Software, Inc. the Log On tab. Change this service’s Log on As:, from the System Account to an account that is desired.

Starting, Stopping, Querying, and Removing the PIPerfmon Service Other command line parameters are listed as: -remove Remove the PIPerfmon Service -start Start the PIPerfmon Service -stop Gracefully stop the PIPerfmon Service -query Query the PIPerfmon Service -help Print usage statement -v Display Uniint and PI-API version information (does not disturb normal interface operation) The -depend option is only valid with the -install action

PIPerfmon Interactively, Not as a Service If you do not configure the software to run as a service, you can:  Build a startup batch command file and  Add the batch file to the startup group of program manager to start up the interface as soon as a user logs on the NT system. Alternatively, you can startup the system manually. You can start the interface by typing: piperfmon.bat or piperfmon.bat from the command prompt.

If you are not currently in the same directory where the interface program resides, you need to specify the full path name of the command file. Also, you may want to specify the full path name for the interface program in the command file.

Performance Monitor Interface to the PI System 23 Picking up PIPerfmon Point Database Changes

The interface program automatically:  Picks up points that are added to the PI database and  Changes in points that are edited in the PI database. It will process twenty-five point database changes every two minutes. Time-stamped error messages are written to the PI message log (pipc.log). Messages describing the number of points to scan are also written whenever the interface is restarted.

24 Full and Basic Versions

There are two versions of this interface. There is a FULL version and a BASIC version. The basic version of the interface is appended by “_basic”. The BASIC version of the interface is bundled with the PI Server 3.3 and greater. This basic version has four limitations. This basic version  Must run on the machine with the PI Server.  Will collect data for 32 points.  Allows one instance of the interface.  Will collect data for local performance counters only The full version does not have these limitations. Both version have a pointsource of # by default.

25 Monitoring Basics

There are many performance counters that can be evaluated and monitored. An example would be to use the interface to monitor IIS traffic (http://webtool.rte.microsoft.com/tutor/perf.htm). The following tables, which have been republished with permission from Microsoft, provide a guideline on what Microsoft believes is important counters to monitor. For more information about these table please refer to the Microsoft® Windows® 2000 Resource Kit documentation under the Performance Monitoring section. The following table is the minimum counters to monitor when you are looking for a specific problem.

Object Problem Counters LogicalDisk\% Free Space LogicalDisk\% Disk Time PhysicalDisk\Disk Reads/sec PhysicalDisk\Disk Writes/sec Use diskperf -y to enable disk counters and diskperf -n to disable them. To specify the type of counters you want to activate, include d for physical disk drives and v for logical disk drives or storage volumes. When the operating system starts up, it automatically sets the Usage diskperf command with the -yd switch to activate physical disk counters. Type diskperf -yv to activate Disk logical disk counters. For more information about using the diskperf command, type diskperf -? at the command prompt. The % Disk Time counter must be interpreted carefully. Because the _Total instance of this counter might not accurately reflect utilization on multiple-disk systems, it is important to use the % Idle Time counter as well. Note that these counters cannot display a value exceeding 100 percent. LogicalDisk\Avg. Disk Queue Length Bottlenecks PhysicalDisk\Avg. Disk Queue Length (all instances) Memory Usage Memory\Available Bytes Memory\Cache Bytes You can also use Memory\Committed Bytes and Memory\Commit Limit to detect problems with virtual memory.

26 Memory\Pages/sec Memory\Page Faults/sec Memory\Pages Input/sec Memory\Page Reads/sec Memory\Transition Faults/sec Memory\Pool Paged Bytes Bottlenecks or leaks Memory\Pool Nonpaged Bytes Although not specifically Memory object counters, the following are also useful for memory analysis: Paging File\% Usage Object (all instances) Cache\Data Map Hits % Server\Pool Paged Bytes and Server\Pool Nonpaged Bytes Network Segment: % Net Utilization Usage (Network Packet Protocol driver for Network Monitor must be installed). Network Network Interface\Bytes total/sec Throughput Network Interface\Packets/sec (TCP/IP) Server\Bytes Total/sec or Server\Bytes Sent/sec and Server\Bytes Received/sec Usage Processor\% Processor Time (all instances)

Processor System\Processor Queue Length (all instances) Bottlenecks Processor\Interrupts/sec System\Context switches/sec

The following table shows the recommended thresholds for the minimum set of system counters.

Resourc Object\Count Suggested Comments e er Threshold LogicalDisk\% 15 percent None Free Space LogicalDisk\% 90 percent None Disk Time Check the specified transfer rate for PhysicalDisk\ your disks to verify that this rate does Depends on Disk Reads/sec, not exceed the specifications. In manufacturer's Disk PhysicalDisk\ general, Ultra Wide SCSI disks can specifications Disk Writes/sec handle 50 to 70 I/O operations per second. This is an instantaneous counter; PhysicalDisk\ observe its value over several Number of Current Disk intervals. For an average over time, spindles plus 2 Queue Length use PhysicalDisk\Avg. Disk Queue Length. Memory Memory\ Less than 4 MB Research memory usage and add Available Bytes memory if needed.

Performance Monitor Interface to the PI System 27 Monitoring Basics

Memory\ 20 Research paging activity. Pages/sec You must determine the threshold Network based on the type of network you are Depends on type Network Segment\% Net running. For Ethernet networks, for of network Utilization example, 30 percent is the recommended threshold. Review this value in conjunction with Paging Paging File\% Above 70 Available Bytes and Pages/sec to File Usage percent understand paging activity on your computer. Find the process that is using a high Processor\% percentage of processor time. Upgrade 85 percent Processor Time to a faster processor or install an additional processor. A dramatic increase in this counter Depends on value without a corresponding Processor processor; for increase in system activity indicates a current CPUs, Processor\ hardware problem. Identify the use a threshold Interrupts/sec network adapter or disk controller card of 1500 causing the interrupts. You might need interrupts per to install an additional adapter or second controller card. If the sum of Bytes Total/sec for all servers is roughly equal to the Server\Bytes maximum transfer rates of your Total/sec network, you might need to segment the network. If the value reaches this threshold, consider tuning the InitWorkItems or Server\Work MaxWorkItems entries in the registry Server 3 Item Shortages (in HKEY_LOCAL_MACHINE \SYSTEM \CurrentControlSet \Services \lanmanserver \Parameters If the value reaches this threshold, Server Work there might be a processor bottleneck. Queues\Queue 4 This is an instantaneous counter; Length observe its value over several intervals. This is an instantaneous counter; Multiple System\Processo 2 observe its value over several Processors r Queue Length intervals.

The following table gives a description of the Task Manager items in the Process tab. If there is a corresponding performance counters it is also listed.

28 OSI Software, Inc. Task System Monitor Manager Description Process Object Process Tab Counters The base priority of the process, which determines the order in which its threads are scheduled for the processor. The base Base Priority priority is set by the process code, not the Priority Base operating system. The operating system sets and changes the dynamic priorities of threads in the process within the range of the base. The total processor time, in seconds, used by CPU Time None the process since it was started. The percentage of time the threads of the CPU Usage process used the processor since the last % Processor Time update. The number of Graphics Device Interface (GDI) objects currently used by a process. A GDI Objects GDI object is an object from the GDI library None of application programming interfaces (APIs) for graphics output devices. The number of object handles in the process's Handle Count Handle Count object table. The number of input/output operations generated by a process that are neither reads nor writes, including file, network, and I/O Other Operations/sec I/O Other device I/Os. An example of this type of operation would be a control function. I/O Others directed to CONSOLE (console input object) handles are not counted. The number of bytes transferred in input/output operations generated by a process that are neither reads nor writes, including file, network, and device I/Os. An I/O Other Bytes I/O Other Bytes/sec example of this type of operation would be a control function. I/O Other Bytes directed to CONSOLE (console input object) handles are not counted. The number of bytes read in input/output operations generated by a process, including I/O Read Bytes file, network, and device I/Os. I/O Read I/O Read Bytes/sec Bytes directed to CONSOLE (console input object) handles are not counted. The number of read input/output operations generated by a process, including file, I/O Reads network, and device I/Os. I/O Reads directed I/O Read Operations/sec to CONSOLE (console input object) handles are not counted.

Performance Monitor Interface to the PI System 29 Monitoring Basics

Task System Monitor Manager Description Process Object Process Tab Counters The number of bytes written in input/output operations generated by a process, including I/O Write Bytes file, network, and device I/Os. I/O Write I/O Write Bytes/sec Bytes directed to CONSOLE (console input object) handles are not counted. The number of write input/output operations generated by a process, including file, I/O Writes network, and device I/Os. I/O Writes I/O Write Operations/sec directed to CONSOLE (console input object) handles are not counted. The process name in the Image Name Name of the process. Instances box The amount of main memory, in kilobytes, Memory Usage Working Set used by the process. The change in memory use, in kilobytes, Memory Usage since the last update. Unlike System None Delta Monitor, Task Manager displays negative values. The amount of memory, in kilobytes, used by a process. Operating system memory that is never paged to disk. Paging is the moving of Nonpaged Pool Pool Nonpaged Bytes infrequently used parts of a program's working memory from RAM to another storage medium, usually the hard disk. The number of times that data had to be retrieved from disk for this process because it None Page Faults was not found in memory. This value is Page faults/sec is the rate accumulated from the time the process is of page faults over time. started. Page Faults The change in the number of page faults None Delta since the last update. The amount of system-allocated virtual memory, in kilobytes, used by a process. The paged pool is virtual memory available to be paged to disk. Paging is the moving of Paged Pool infrequently used parts of a program's Pool Paged Bytes working memory from RAM to another storage medium, usually the hard disk. The paged pool includes all of user memory and a portion of system memory. Peak Memory The peak amount of physical memory None Usage resident in a process since it started. PID (Process Numerical ID assigned to the process while it ID Process Identifier) runs.

30 OSI Software, Inc. Task System Monitor Manager Description Process Object Process Tab Counters The number of threads running in the Thread Count Thread Count process. The number of USER objects currently being used by a process. A USER object is an object from Window Manager, which USER Objects None includes windows, menus, cursors, icons, hooks, accelerators, monitors, keyboard layouts, and other internal objects. Virtual Memory The amount of virtual memory, or address Private Bytes Size space, committed to a process.

The following table gives a description of the Task Manager items in the Performance tab. If there is a corresponding performance counters it is also listed

Task Manager System Monitor Description Performance Counters Tab The percentage of time the processor is Processor\% Processor CPU Usage running a thread other than the Idle thread. Time The amount of virtual memory used, in MEM Usage Memory\Committed Bytes kilobytes. The number of object handles in the tables Process(_Total)\Handle Total Handles of all processes. Count The number of running threads, including Process(_Total)\Thread Total Threads one Idle thread per processor. Count Object\Processes is the The number of active processes, including Total Processes same, but excludes the Idle the Idle process. process. Amount of physical, random access Physical memory, in kilobytes, installed in the None Memory: Total computer. Physical Amount of physical memory available to Memory: processes, in kilobytes. It includes zeroed, Memory\Available Bytes Available free, and standby memory. Physical Amount of physical memory, in kilobytes, Memory: File Memory\Cache Bytes released to the file cache on demand. Cache Commit Size of virtual memory in use by all Memory\Committed Bytes Charge: Total processes, in kilobytes. Amount of virtual memory, in kilobytes, Commit that can be committed to all processes Memory\Commit Limit Charge: Limit without enlarging the paging file.

Performance Monitor Interface to the PI System 31 Monitoring Basics

Task Manager System Monitor Description Performance Counters Tab The maximum amount of virtual memory, Commit in kilobytes, used in the session. The None Charge: Peak commit peak can exceed the commit limit if virtual memory is expanded. None Kernel Sum of paged and nonpaged memory, in (Sum of Pool Paged Bytes Memory: Total kilobytes. and Pool Nonpaged Bytes) Kernel Size of the paged pool, in kilobytes, Memory\Pool Paged Bytes Memory: Paged allocated to the operating system. Kernel Size of the nonpaged pool, in kilobytes, Memory\Pool Nonpaged Memory: allocated to the operating system. Bytes Nonpaged

32 OSI Software, Inc. Limitations

There known limitations for this version of the interface. When the interface is collecting data for multiple computers, when one of the computers is disconnected from the network, data collecting for the entire interface is delay for about 2 minutes. After the two minutes the collection for the performance counters for the other computers will continue and the disconnected machine’s performance counters will not be collected until the machine is back online. It is advisable to run one instance of the interface per machine that is monitored. The interface picks up points during startup and when there is a change in the point’s configuration. Therefore if a machine or performance counter does not exist during the startup of the interface the point will be rejected and the interface will not collect data for that point. It is not advisable to sample at a rate of less than .1 seconds. This is near the resolution limit of the counters. The interface and the PIPerfCreateor can not run on a Windows NT Server with NNTP counters activated or with a Windows NT Server with Option Pack 4 and Window NT service pack 4 or lower. In order for the interface and PIPerfCreator to run on a Windows NT Server with NNTP, the NNTP counters (nntpctrs.dll) must be deactivated. A machine with Windows NT Server and NT Option Pack 4 must be at service pack 5 or greater. It is recommended that service pack 6a be applied to all NT machines.

33 Troubleshooting

One of the best ways to diagnose if there is a problem with the interface is to check the behavior of the Microsoft utility NT Performance Monitor (Sysmon for Windows 2000). The interface will be able to collect the same counters as the NT Performance Monitor or the Windows 2000 Sysmon utility. Common Problems

The following is a list of common problems and misunderstandings about the PIPerfmon Interface.

The remote computer you are monitoring is The interface will continue trying to monitor offline. the instance and will find it when the computer is restarted. I am unable to obtain remote counters. The interface is installed to run with the system account privileges as a service and the user account for interactive. Go to The PIPerfmon Service section for a description of the solution for services. Log on to the computer with a user account with sufficient privileges to run the interface interactively. The application or thread you are The interface continues trying to monitor the monitoring has stopped. instance and will find it when the process or thread is restarted. All values for my disks are zero. The counters for the Physical and Logical Disk objects don't work until you install the Disk Performance Statistics Driver in your I/O Manager disk stack. Use the Diskperf utility to install the Disk Performance Statistics Driver, then restart the computer. I have several disks, but values are only When you ran Diskperf, you used the standard shown for the first disk in the set. option, diskperf -y, which places the statistics collector above the fault tolerant driver, FTDISK. The statistics collector cannot see the different physical instances of the disk. Run Diskperf using the diskperf -ye option, then restart the computer. This places the statistics collector below the fault tolerant driver so it can see physical disks before they are combined into a volume set. %Disk Read Time and %Disk Write Time All disk counters include time in the queue. don't sum to %Disk Time When the queue gets long, the read and write time both include that time and don't sum to 100. %Disk Read Time:_Total and %Disk Write Time_Total sum to more than 100% because

34 you have more than one instance of the physical or logical disk. The percentage counters are limited, by definition to 100% and cannot display higher values. Use the Avg. Disk Read Queue Length, Avg. Disk Write Queue Length, and Avg. Disk Queue Length counters instead. These report on the same data as the %Disk Time counters, but display the values in decimals that can exceed 1.0. Why is there a _Total instance on the ID Items in the Instances box are the same for all counters? What would a total ID Thread counters of an object. counter show? When an instance has no meaning, as in the case of _Total for IDs, a zero value is displayed for the counter. Process: Pool Nonpaged Bytes:_Total The Memory: Pool Nonpaged Bytes value doesn't equal Memory: Pool Nonpaged comes from an internal counter that counts Bytes each byte. The Process: Pool Nonpaged Bytes counters are estimates from the Object Manager. The Object Manager counts accesses, not space, so its counts include requests to duplicate object handles as well as space for the object. Ignore the static value of the counters and, instead, monitor any changes in the values Where is the Processor Queue Length It's a System object counter. There is just one Counter? processor queue for all processors. Counter values for instances of an object The %Disk Time and %Processor Time are greater than those for the total counters are limited, by definition, to 100%. If you have multiple disks or processors, each could equal 100%, but the total counter cannot display the sum. Monitor the physical instances separately. For disks, use the Avg. Disk Queue Length counters instead of the %Disk Time counters. These display the totals as decimal, not percentages, so they can exceed 1.0. For processors, use the System: %Total Processor Time counter. This averages the active time of each processor over all processors.

Error Codes

The following are some common error codes from the interface and what they mean.

Information Messages These messages are normal and do not require action.

Performance Monitor Interface to the PI System 35 Troubleshooting

Error Code Error Description Interpretation 0x00000000L The returned data is valid PDH_CSTATUS_VALID_DATA 0x00000001L The return data value is PDH_CSTATUS_NEW_DATA valid and different from the last sample

Warning Messages These messages are returned when the function has completed successfully but the results may be different than expected.

0x800007D0L Unable to connect to PDH_CSTATUS_NO_MACHINE specified machine or machine is off line. 0x800007D1L The specified instance is PDH_CSTATUS_NO_INSTANCE not present 0x800007D5L No data to return PDH_NO_DATA 0x800007D6L A counter with a negative PDH_CALC_NEGATIVE_DENOMIN denominator value was ATOR detected 0x800007D7L A counter with a negative PDH_CALC_NEGATIVE_TIMEBAS timebase value was E detected 0x800007D8L A counter with a negative PDH_CALC_NEGATIVE_VALUE value was detected 0x800007D9L The user cancelled the PDH_DIALOG_CANCELLED dialog box

Error Messages These messages are returned when the function could not be complete as requested and some corrective action may be required by the caller or the user.

0xC0000BB8L The specified object is not PDH_CSTATUS_NO_OBJECT found on the system 0xC0000BB9L The specified counter PDH_CSTATUS_NO_COUNTER could not be found 0xC0000BBAL The returned data is not PDH_CSTATUS_INVALID_DATA valid 0xC0000BBBL A PDH function could not PDH_MEMORY_ALLOCATION_FAI allocate enough LURE temporary memory to complete the operation.

36 OSI Software, Inc. Close some applications or extend the pagefile and retry the function 0xC0000BBCL The handle is not a valid PDH_INVALID_HANDLE PDH object 0xC0000BBFL No counter was specified PDH_CSTATUS_NO_COUNTERNA ME 0xC0000BC0L Unable to parse the PDH_CSTATUS_BAD_COUNTERN counter path. Check the AME format and syntax of the specified path 0xC0000BC3L Unable to connect to the PDH_CANNOT_CONNECT_MACHI requested machine NE 0xC0000BC4L The specified counter PDH_INVALID_PATH path could not be interpreted 0xC0000BC5L The instance name could PDH_INVALID_INSTANCE not be read from the specified counter path 0xC0000BC6L The data is not valid PDH_INVALID_DATA 0xC0000BC7L The dialog box data block PDH_NO_DIALOG_DATA was missing or invalid 0xC0000BC8L Unable to read the counter PDH_CANNOT_READ_NAME_STRI and/or explain text from NGS the specified machine 0xC0000BCCL No more data is available PDH_NO_MORE_DATA 0xC0000BD4L Unable to find the PDH_STRING_NOT_FOUND specified string in the list of performance name and explain text strings

Performance Monitor Interface to the PI System 37 Troubleshooting

Revision History

Date Author Comments 10-Dec-99 JCW First Copy of Interface Manual Started 4-May-00 JCW First Released 15-Sep-00 JCW Added PWD file documentation 12-Dec-00 JCW Edited for 1.0.1 version 25-Jan-01 JCW Added Monitoring Basics section 8-Mar-01 JCW Added service startup user account documentation 25-Sep-01 JCW Modifications for version 1.0.3 11-Feb-02 RCP Added PI-PERFMON ICU Control to Startup Command File section. 11-Feb-02 RCP Added PI-PERFMON ICU Control to Startup Command File section. 27-Feb-02 HAB Corrected reference to /db – should be /dbuniint. 19-Apr-02 HAB Added new ICU Control screen shot (1.0.2, doc rev A)

38 OSI Software, Inc.