Performance Monitor
Interface to the PI System
Version 1.4.3.0
Revision B
Copyright © 2000-2011 OSIsoft, Inc.
OSIsoft, Inc.777 Davis St., Suite 250
San Leandro, CA 94577 USA
(01) 510-297-5800 (main phone)
(01) 510-357-8136 (fax)
(01) 510-297-5828 (support phone)
http://techsupport.osisoft.com
Houston, TX
Johnson City, TN
Longview, TX
Mayfield Heights, OH
Philadelphia, PA
Phoenix, AZ
Savannah, GA
Yardley, PA
/ OSIsoft Australia
Perth, Australia
Auckland, New Zealand
OSI Software GmbH
Altenstadt,Germany
OSIsoft Asia Pte Ltd.
Singapore
OSIsoft Canada ULC
Montreal, Canada
Calgary, 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
OSIsoft do Brasil Sistemas Ltda.
Sao Paulo, Brazil
Sales Outlets/Distributors
Middle East/North Africa
Republic of South Africa
Russia/Central Asia / South America/Caribbean
Southeast Asia
South Korea Taiwan
www.osisoft.com
All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, mechanical, photocopying, recording, or otherwise, without the prior written permission of OSIsoft, Inc.
OSIsoft, the OSIsoft logo and logotype, PI Analytics, PI ProcessBook, PI DataLink, ProcessPoint, Sigmafine, Analysis Framework, PI Datalink, IT Monitor, MCN Health Monitor, PI System, PI ActiveView, PI ACE, PI AlarmView, PI BatchView, PI ManualLogger, PI ProfileView, ProTRAQ, RLINK, RtAnalytics, RtBaseline, RtPortal, RtPM, RtReports and RtWebParts are all trademarks of OSIsoft, Inc. All other trademarks or trade names used herein are the property of their respective owners.
RESTRICTED RIGHTS LEGEND
Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph I(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013
Table of Contents
Terminology vii
Introduction 1
Reference Manuals 1
Supported Features 1
Diagram of Hardware Connection 5
Principles of Operation 7
Full and Basic Versions 7
Limitations 8
Installation Checklist 9
Data Collection Steps 9
Interface Diagnostics 10
Advanced Interface Features 10
Interface Installation 11
User Account 11
Naming Conventions and Requirements 11
Interface Directories 12
PIHOME Directory Tree 12
Interface Installation Directory 12
Interface Installation Procedure 12
Installing Interface as a Windows Service 13
Installing Interface Service with PI Interface Configuration Utility 13
Installing Interface Service Manually 16
Files Installed for Full Version 17
Files Installed for Basic Version 17
Digital States 19
PointSource 21
PI Point Configuration 23
Performance Counter Path 23
Point Attributes 24
Tag 24
PointSource 25
PointType 25
Location1 25
Location2 25
Location3 25
Location4 25
Location5 25
InstrumentTag 25
ExDesc 26
Scan 26
Shutdown 26
Convers 27
PIPerfCreator Utility 29
PI SMT 3 add-in 33
Monitoring a Remote Node 35
Performance Point Configuration 37
Startup Command File 39
Configuring the Interface with PI ICU 39
piperfmon Interface page 41
Command-line Parameters 43
Sample PIPerfMon.bat File 46
UniInt Failover Configuration 47
Introduction 47
Quick Overview 48
Configuring Synchronization through a Shared File (Phase 2) 49
Synchronization through a Shared File (Phase 2) 53
Configuring UniInt Failover through a Shared File (Phase 2) 54
Start-Up Parameters 54
Failover Control Points 57
PI Tags 57
Detailed Explanation of Synchronization through a Shared File (Phase 2) 62
Steady State Operation 63
Failover Configuration Using PI ICU 65
Create the Interface Instance with PI ICU 65
Configuring the UniInt Failover Startup Parameters with PIICU 66
Creating the Failover State Digital State Set 66
Using the PI ICU Utility to create Digital State Set 67
Using the PI SMT 3 Utility to create Digital State Set 67
Creating the UniInt Failover Control and Failover State Tags (Phase 2) 70
Interface Node Clock 71
Security 73
Windows 73
Starting / Stopping the Interface on Windows 75
Starting Interface as a Service 75
Stopping Interface Running as a Service 75
Other Command-line Parameters 75
Which Performance Counters to Monitor 77
Translating Counters to the Localized Language 83
Buffering 85
Which Buffering Application to Use 85
How Buffering Works 85
Buffering and PI Server Security 86
Enabling Buffering on an Interface Node with the ICU 87
Choose Buffer Type 87
Buffering Settings 88
Buffered Servers 90
Installing Buffering as a Service 93
Interface Diagnostics Configuration 95
Scan Class Performance Points 95
Performance Counters Points 98
Interface Health Monitoring Points 101
I/O Rate Point 107
Configuring I/O Rate Tags Manually 110
Configuring the PI Point on the PI Server 110
Configuration on the Interface Node 110
Interface Status Point 111
Appendix A: Error and Informational Messages 113
Message Logs 113
Troubleshooting 113
Common Problems 113
Error Codes 115
Informational Messages 115
Warning Messages 115
Error Messages 116
System Errors and PI Errors 117
UniInt Failover Specific Error Messages 117
Informational 117
Errors (Phase 1 & 2) 118
Errors (Phase 2) 118
Appendix B: PI SDK Options 121
Revision History 123
Performance Monitor Interface to the PI System 103
Terminology
To understand this interface manual, you should be familiar with the terminology used in this document.
Buffering
Buffering refers to an Interface Node’s ability to store temporarily the data that interfaces collect and to forward these data to the appropriate PI Servers.
N-Way Buffering
If you have PI Servers that are part of a PI Collective, PIBufss supports n-way buffering. N-way buffering refers to the ability of a buffering application to send the same data to each of the PI Servers in a PI Collective. (Bufserv also supports n-way buffering to multiple PI Server however it does not guarantee identical archive records since point compressions specs could be different between PI Servers. With this in mind, OSIsoft recommends that you run PIBufss instead.)
ICU
ICU refers to the PI Interface Configuration Utility. The ICU is the primary application that you use to configure and run PI interface programs. You must install the ICU on the same computer on which an interface runs. A single copy of the ICU manages all of the interfaces on a particular computer.
You can configure and run an interface by editing a startup command file. However, OSIsoft discourages this approach. Instead, OSIsoft strongly recommends that you use the ICU for interface management tasks.
ICU Control
An ICU Control is a plug-in to the ICU. Whereas the ICU handles functionality common to all interfaces, an ICU Control implements interface-specific behavior. Most PI interfaces have an associated ICU Control.
Interface Node
An Interface Node is a computer on which
· the PI API and/or PI SDK are installed, and
· PI Server programs are not installed.
PI API
The PI API is a library of functions that allow applications to communicate and exchange data with the PI Server. All PI interfaces use the PI API.
PI Collective
A PI Collective is two or more replicated PI Servers that collect data concurrently. Collectives are part of the High Availability environment. When the primary PI Server in a collective becomes unavailable, a secondary collective member node seamlessly continues to collect and provide data access to your PI clients.
PIHOME
PIHOME refers to the directory that is the common location for PI client applications. A typical PIHOME is C:\Program Files\PIPC. PI interfaces reside in a subdirectory of the Interfaces directory under PIHOME. For example, files for the Modbus Ethernet Interface are in C:\Program Files\PIPC\Interfaces\ModbusE.
This document uses [PIHOME] as an abbreviation for the complete PIHOME directory. For example, ICU files in [PIHOME]\ICU.
PI SDK
The PI SDK is a library of functions that allow applications to communicate and exchange data with the PI Server. Some PI interfaces, in addition to using the PI API, require the use of the PI SDK.
PI Server Node
A PI Server Node is a computer on which PI Server programs are installed. The PI Server runs on the PI Server Node.
PI SMT
PI SMT refers to PI System Management Tools. PI SMT is the program that you use for configuring PI Servers. A single copy of PI SMT manages multiple PI Servers. PI SMT runs on either a PI Server Node or a PI Interface Node.
Pipc.log
The pipc.log file is the file to which OSIsoft applications write informational and error messages. While a PI interface runs, it writes to the pipc.log file. The ICU allows easy access to the pipc.log.
Point
The PI point is the basic building block for controlling data flow to and from the PI Server. For a given timestamp, a PI point holds a single value.
A PI point does not necessarily correspond to a “point” on the foreign device. For example, a single “point” on the foreign device can consist of a set point, a process value, an alarm limit, and a discrete value. These four pieces of information require four separate PI points.
Service
A Service is a Windows program that runs without user interaction. A Service continues to run after you have logged off from Windows. It has the ability to start up when the computer itself starts up.
The ICU allows you to configure a PI interface to run as a Service.
Tag (Input Tag and Output Tag)
The tag attribute of a PI point is the name of the PI point. There is a one-to-one correspondence between the name of a point and the point itself. Because of this relationship, PI System documentation uses the terms “tag” and “point” interchangeably.
Interfaces read values from a device and write these values to an Input Tag. Interfaces use an Output Tag to write a value to the device.
Performance Monitor Interface to the PI System 103
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 2000 SP3 & SP4, Windows XP and Windows 2003 operating systems. There are two versions of the interface, the FULL version and the BASIC version. The interface supports phase 2 failover with HOT and COLD configuration for 32-bit FULL version. Please refer to the Full and Basic Versions section of this manual for further details.
Reference Manuals
OSIsoft
· PI Server manuals
· PI API Installation manual
· UniInt Interface User Manual
Supported Features
Feature / Support /Part Number / PI-IN- OS-PERF-NTI
* Platforms / 32-bit Platforms:
Windows (2000 SP3 & SP4, 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 PIPoint 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
* UniInt-based
* Disconnected Startup
* SetDeviceStatus / Yes
Yes
Yes
* Failover / UniInt Interface Level Failover (Phase 2, Cold and Hot)
* Vendor Software Required on PI Interface Node / 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-Based Interface / No
* See paragraphs below for further explanation.
Platforms
The Interface is designed to run on the above mentioned Microsoft Windows operating systems and their associated service packs. Please contact OSIsoft Technical Support for more information.
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 Start-Up
The PI Perfmon interface is built with a version of UniInt that supports disconnected start-up. Disconnected start-up is the ability to start the interface without a connection to the PI server. This functionality is enabled by adding /cachemode to the list of start-up parameters or by enabling disconnected startup using the ICU. Refer to the UniInt Interface User Manual for more details on UniInt Disconnect startup.
Device Status Point Support (SetDeviceStatus)
The Interface is built with a version of UniInt that 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:
· "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.
· "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 be incorrectly reported as offline. Please see the section Performance Counter Path for further details.