Performance Monitor
Interface to the PI System

Version 1.4.2.0
RevisionB

7/14/2008 7:43:00 AM1

How to Contact Us

OSIsoft, Inc.
777 Davis St., Suite 250
San Leandro, CA94577USA
Telephone
(01) 510-297-5800 (main phone)
(01) 510-357-8136 (fax)
(01) 510-297-5828 (support phone)

Houston, TX
Johnson City, TN
Mayfield Heights, OH
Phoenix, AZ
Savannah, GA
Seattle, WA
Yardley, PA / Worldwide Offices
OSIsoft Australia
Perth, Australia
Auckland, New Zealand
OSI Software GmbH
Altenstadt,Germany
OSI Software Asia Pte Ltd.
Singapore
OSIsoft Canada ULC
Montreal, Canada
OSIsoft, Inc. Representative Office
Shanghai, People’s Republic of China
OSIsoft Japan KK
Tokyo, Japan
OSIsoft Mexico S. De R.L. De C.V.
Mexico City, Mexico
Sales Outlets and Distributors
  • Brazil
  • Middle East/North Africa
  • Republic of South Africa
  • Russia/Central Asia
/
  • South America/Caribbean
  • Southeast Asia
  • South Korea
  • Taiwan


OSIsoft, Inc. is the owner of the following trademarks and registered trademarks: PI System, PI ProcessBook, Sequencia, Sigmafine, gRecipe, sRecipe, and RLINK. All terms mentioned in this book that are known to be trademarks or service marks have been appropriately capitalized. Any trademark that appears in this book that is not owned by OSIsoft, Inc. is the property of its owner and use herein in no way indicates an endorsement, recommendation, or warranty of such party’s products or any affiliation with such party of any kind.
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
Unpublished – rights reserved under the copyright laws of the United States.
© 2000-2007 OSIsoft, Inc.PI_PIPerfMon.doc

7/14/2008 7:43:00 AM1

Table of Contents

Introduction

Reference Manuals

Supported Features

Diagram of Hardware Connection

Principles of Operation

Full and Basic Versions

Limitations

Installation Checklist

Interface Installation

User Account

Naming Conventions and Requirements

Interface Directories

The PIHOME Directory Tree

Interface Installation Directory

Interface Installation Procedure

Installing the Interface as a Windows Service

Installing the Interface Service with PI Interface Configuration Utility

Installing the Interface Service Manually

Files Installed for Full Version

Files Installed for Basic Version

PointSource

PI Point Configuration

Performance Counter Path

Point Attributes

Tag

PointSource

PointType

Location1

Location2

Location3

Location4

Location5

InstrumentTag

ExDesc

Scan

Shutdown

Convers

PIPerfCreator Utility

PI SMT 3 add-in

Monitoring a Remote Node

Performance Point Configuration

I/O Rate Tag Configuration

Monitoring I/O Rates on the Interface Node

Configuring I/O Rate Tags with PI ICU (Windows)

Configuring I/O Rate Tags Manually

Configuring the PI Point on the PI Server

Configuration on the Interface Node

Startup Command File

Configuring the Interface with PI ICU

piperfmon Interface Tab

Command-line Parameters

Sample PIPerfMon.bat File

Interface Node Clock

Security

Windows

Starting / Stopping the Interface

Starting Interface as a Service

Stopping Interface Running as a Service

Other Command-line Parameters

Which Performance Counters to Monitor

Translating Counters to the Localized Language

Buffering

Configuring Buffering with PI ICU (Windows)

Configuring Buffering Manually

Example piclient.ini File

Appendix A: Troubleshooting

Common Problems

Error Codes

Informational Messages

Warning Messages

Error Messages

Revision History

Performance Monitor Interface to the PI System1

Introduction

The PI Performance Monitor interface, PIPerfMon, obtains Microsoft Windows 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 NT4, 2000, Windows XP and Windows 2003 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
  • UniIntInterface User Manual
  • PI Data Archive Manual
  • PI API Installation Instructions

Supported Features

Features / Support
Part Number / PI-IN-OS-PERF NTI
*Platforms / 32-bit Platforms:
Windows (NT4, 2000, XP, 2003)
64-bit Platforms:
Windows 2003 (IA64, X64)
APS Connector / No
*Point Builder Utility / Yes
*ICU Control / Yes
PI Point Types / PI 3: Float16 / Float32 / Float64 / Int16 / Int32/ Digital
Sub-second Timestamps / Yes
Sub-second Scan Classes / Yes
Automatically Incorporates PI Point Attribute Changes / Yes
Exception Reporting / Yes
Outputs from PI / No
Inputs to PI: Scan-based / Unsolicited / Event Tags / Scan-based
Supports Questionable Bit / No
Supports Multi-character PointSource / Yes
Maximum Point Count / Unlimited (full), 512 points (basic)
*Uses PI SDK / No
PINet String Support / N/A
* Source of Timestamps / PI System Time
History Recovery / No
Failover / No
* UniInt-based
* Disconnected Startup
* SetDeviceStatus / Yes
Yes
Yes
Vendor Software Required on PI API / PINet node / No
Vendor Software Required on Foreign Device / No
Vendor Hardware Required / No
*Additional PI Software Included with Interface / Yes
Device Point Types / Numeric only
Serial-Interface / No

* Further explanation below.

Platforms

The Interface is designed to run on the above mentioned Microsoft Windows operating systems and greater. See Limitations for further information about requirements for running on Windows NT4.

Point Builder Utility

The point builder utility can only create 32bit performance counters.

ICU Control

The ICU Control is not supported on IA64.

Uses PI SDK

The PI SDK and the PI API are bundled together and must be installed on each PI Interface node. This Interface does not specifically make PI SDK calls.

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 developers, and is integrated into many interfaces, including this interface. The purpose of UniInt is to keep a consistent feature set and behavior across as many of OSIsoft’s 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 UniIntsupplied configuration parameters and some interface-specific parameters. UniInt is constantly being upgraded with new options and features.

The UniInt Interface User Manual is a supplement to this manual.

Disconnected Startup

The interface now supports startup without a connection to the PI server. Previously a PI server connection was required in order to obtain a list of which PI points belonged to an interface. Now this information is stored in a local cache. This cache is synchronized with the PI server point database. This not only reduces the time required for interface startup but also prevents data loss if starting the interface when the PI server is unavailable. Refer to the New Interface Features PR1 Manual for a more complete discussion on disconnected startup. Note this functionality requires PI API 1.6.1.x or later and is only supported for PI 3.x servers.

DeviceStatus Point Support (SetDeviceStatus)

The Interface is built with a version of UniIntthat supports interface health points. The health point with the point attribute Exdesc = [UI_DEVSTAT], is used to represent the status of the source devices. The following events can be written into the point:

a)"Good" - the interface is properly communicating and reading data from the devices.If no data collection points have been defined, this indicates the interface has successfully started.

b)"3 | n devices(s) in error | Device1,...,DeviceN" - the interface has determined that the listed device(s) are offline. A device is considered offline when all its scan classes fail to retrieve data.

The event "2 | Connected / No Data | " is not used by this interface.

Note: In some cases, it may be possible for a device to beincorrectly reported as offline. Please see the sectionPerformance Counter Path for furtherdetails.

Please refer to the UniInt Interface User Manual for more information on how to configure health points.

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 as the utility. The details of the utility will be discussed later in this document.

Diagram of Hardware Connection

There are 2 possible hardware configurations. The first (which is recommended by OSIsoft, Inc.) is to have the interface on a separate node from the PI Server, to take advantage of buffering should the connection to the PI server be lost.

The second possible configuration is to install the interface on the same node as the PI Server. This is less desirable, because the benefit of buffering is reduced. However, users running the basic version of the interface must run in this configuration, because the basic version of the interface must reside on the PI Server.

Performance Monitor Interface to the PI System1

Principles of Operation

PIPerfMon collects data from the Microsoft Windows Performance Counters. Each counter may be collected as frequently as needed; the frequency is defined on a point-by-point basis. Exception reporting is used as described in the Data Archive or PI Server manuals.

The data collected is all numeric and as such only floating point or integer PI points may be configured for use with this interface.

Full and Basic Versions

There are two versions of this interface, a FULL version and a BASIC version.

Basic Version

The basic version executable of the interface is appended by “_basic”. The BASIC version of the interface is bundled with the PI Server 3.3 and greater. The basic version has these characteristics:

  • Must run on the machine with the PI Server.
  • Will collect data for a maximum of 512 points.
  • Allows one instance of the interface.
  • Will collect data for local performance counters only
  • Default point source of #
Full Version

The full version has more capability than the basic version. The full version has these characteristics:

  • May run on either a PI Interface node or on the PI Server.
  • Will collect data for an unlimited number of points.
  • Allows multiple instances of the interface.
  • Will collect data for remote as well as local performance counters.
  • Default point source of #

Limitations

There are known limitations for this version of the interface.

  • It is not advisable to sample at a rate of less than 0.1 second. This is near the resolution limit of the counters.
  • The interface and the PIPerfCreator cannot run on a Windows NT Server with NNTP counters activated or with a Windows NT Server with Option Pack 4 and Windows 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.

Note: It is required that at least Service Pack 6a be applied to all NT machines.

Performance Monitor Interface to the PI System1

Installation Checklist

For those users who are familiar with running PI data collection interface programs, this checklist helps get the PIPerfMon interface running. If not familiar with PI interfaces, return to this section after reading the rest of the manual in detail.

1.Install the PI Interface Configuration Utility (which installs PI SDK and PI API)

2.Verify that PI SDKhas been installed.

3.Install the interface.

4.Choose a point source.

5.Configure PI points.
Location1 is the interface instance.
Location2 is not used by this interface.
Location3 is not used by this interface.
Location4 is the scan class.
Location5 is not used by this interface.
ExDesc is the Performance Counter Path.
InstrumentTag is not used by this interface.

6.Configure the interface using the PI ICU utility or edit startup command file manually. It is recommended to use PI ICU whenever possible.

7.Configure I/O Rate tag.

8.Set interface node clock.

9.Set up security.

10.Start the interface without buffering.

11.Verify data.

12.Stop interface, start buffering, start interface.

Performance Monitor Interface to the PI System1

Interface Installation

OSIsoft recommends that interfaces be installed on PI Interface Nodes instead of directly on the PIServer node. A PI Interface Node is any node other than the PI Server node where the PIApplication Programming Interface (PI API) has been installed (see the PI APImanual). With this approach, the PI Server need not compete with interfaces for the machine’s resources. The primary function of the PIServer is to archive data and to service clients that request data.

After the interface has been installed and tested, Bufserv should be enabled on the PI Interface Node (once again, see the PI API manual). Bufserv is distributed with the PI SDK. It is a utility program that provides the capability to store and forward events to a PI Server, allowing continuous data collection when communication to the PI Server is lost. Communication will be lost when there are network problems or when the PI Server is shut down for maintenance, upgrades, backups, or unexpected failures.

In most cases, interfaces on PI Interface Nodes should be installed as automatic services. Services keep running after the user logs off. Automatic services automatically restart when the computer is restarted, which is useful in the event of a power failure.

The guidelines are different if an interface is installed on the PI Server node. In this case, the typical procedure is to install the PI Server as an automatic service and interfaces as manual services that are launched by site-specific command files when the PI Server is started. Interfaces that are started as manual services are also stopped in conjunction with the PI Server by site-specific command files. This typical scenario assumes that Bufserv is not enabled on the PI Server node.Bufserv can be enabled on the PI Server node so that interfaces on the PI Server node do not need to be started and stopped in conjunction with PI, but it is not standard practice to enable buffering on the PI Server node. See the UniIntInterface User Manual for special procedural information.

User Account

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 the Log On tab. Change this service’s Log on As:, from the System Account to an account that is desired.

Naming Conventions and Requirements

In the installation procedure below, it is assumed that the name of the interface executable is PIPerfMon.exe and that the startup command file is called PIPerfMon.bat.

Interface Directories

The PIHOME Directory Tree

The PIHOME directory tree is defined by the PIHOME entry in the pipc.iniconfiguration file. This pipc.ini file is an ASCII text file, which is located in the %windir%directory. A typical pipc.ini file contains the following lines:
[PIPC]
PIHOME=c:\Program Files\pipc
The above lines define the \pipc directory as the root of the PIHOME directory tree on the C: drive. OSIsoft recommends using \Program Files\pipc as the root directory name. The PIHOMEdirectory does not need to be on the C: drive.

Interface Installation Directory

Place all copies of the interface into a single directory. The suggested directory is:

PIHOME\Interfaces\PIPerfMon\

Replace PIHOME with the corresponding entry in the pipc.ini file.

Interface Installation Procedure

The PIPerfMon interface setup program uses the services of the Microsoft Windows Installer. Windows Installer is a standard part of Windows 2000. When running on Windows NT 4.0 systems, the PIPerfMon setup program will install the Windows Installer itself if necessary. To install, run the PIPerfMon_x.x.x.x.exe installation kit.

Installing the Interface as a Windows Service

The PIPerfMonInterface service can be created, preferably, with the PI Interface Configuration Utility, or can be created manually.

Installing the Interface Service with PI Interface Configuration Utility

The PI Interface Configuration Utility provides a user interface for creating, editing, and deleting the interface service:

Service Configuration
Service name

The Service to Add box shows the name of the current interface service. This service name is obtained from the interface executable.

ID

This is the service id used to distinguish multiple instances of the same interface using the same executable.

Display name

The Display Name text box shows the current Display Name of the interface service. If there is currently no service for the selected interface, the default Display Name is the service name with a “PI-” prefix. Users may specify a different Display Name. OSIsoft suggests that the prefix “PI-” be appended to the beginning of the interface to indicate that the service is part of the OSI suite of products.

Log on as

The Log on as text box shows the current “Log on as” Windows User Account of the interface service. If the service is configured to use the Local System account, the Log on as text box will show “LocalSystem.” Users may specify a different Windows User account for the service to use.

Password

If a Windows User account is entered in the Log on as text box, then a password must be provided in the Password text box, unless the account requires no password.

Confirm password

If a password is entered in the Password text box, then it must be confirmed in the Confirm Password text box.

Dependencies

The Installed services list is a list of the services currently installed on this machine. Services upon which this interface is dependent should be moved into the Dependencies list using the button. For example, if API Buffering is running, then “bufserv” should be selected from the list at the right and added to the list on the left. Often interface services also depend on a vendor program, such as the Fisher-Rosemount chipservice. To remove a service from the list of dependencies, use the button, and the service name will be removed from the Dependencies list.