Interfaces and other applications that send values to the Snapshot should register these events by incrementing an event counter. This counter may then be used by the iorates program to periodically update a tag on the PI Server with event rate information. Application and system loading can then be observed through this rate tag.
Note: The iorates program is available on UNIX and Linux platforms only.
Starting with PI API version 1.6.6, the iorates program can also:
Starting with PI API 1.6.6, iorates is configured using
PIHOME/dat/iorates.ini instead of
PIHOME/dat/iorates.dat. In the .dat file structure, each entry consisted of only the PI point name and counter index. Because of iorates enhancements, it is not possible in PI API 1.6.6 and later to define the required configuration within the old .dat file structure.
The iorates.ini file defines the following:
When the iorates program starts, it reads the iorates.ini file. For each PI point defined in the file, it loads the point ID and point type from the PI Server and resets the point value to zero. The iorates program then loops through the defined PI points and does the following:
By default, iorates performs these steps every 10 minutes.
Bufserv processes also read the iorates.ini file on startup. Bufserv creates a separate process for each buffered server defined in piclient.ini. Each bufserv process looks in the iorates.ini file for BUFRCV and BUFSND settings specific to the buffered server. If the BUFRCV and BUFSND settings are defined, bufserv first resets the associated counters, and then updates the counter defined by BUFSND as it sends values to the buffered PI Server.
PI API applications, including interfaces, also read the iorates.ini file and look for BUFRCV settings when they connect to a PI Server. If these settings are defined, then the associated BUFRCV counter is incremented when the application calls functions that send events to the bufserv buffers.
UniInt-based interfaces can also update other counters when they send events to the PI Server. The UniInt counters can be specified by starting the interface with the -ec= command-line argument.
Some interfaces support other interface-specific event counters. Refer to the interface manuals for more details.
Also, when PI API functions are called that send events to the PI Server (standard and extended functions), counter 47 is incremented by the number of events to be sent. Counter 47 is a reserved counter that tracks the total event rate for the interface node.
When planning your iorates configuration, consider the following:
To configure iorates, use iorates.ini to define PI Servers as well as BUFRCV and BUFSND properties, PI points, and counters for each PI Server. The iorates.ini file uses the standard INI file format, with sections and properties.
The iorates.ini file requires a [PISERVERS] section listing PI Servers that iorates will use, and a section for each listed PI Server that defines BUFRCV, BUFSND, and individual PI points and counters for that server.
The properties within the [PISERVERS] section use the property names SERVER1, SERVER2,...SERVERn, and the values are the names of the PI Servers.
Example of [PISERVERS] section:
Note: Iorates attempts to read property names in the [PISERVERS] section in numeric order starting with SERVER1. Property names can be listed in any order, but if there is a gap in the numeric sequence of the property names, iorates will not be able to read values after the gap.
For example, iorates can read the following, because even though the list is not in numeric order, the three property names use consecutive numbering:
However, iorates will read only srv1name (SERVER1) in the example below, because no SERVER2 value is specified:
The section name for each PI Server is the PI Server name. Using the above example, the sections for individual PI Servers would be named [srv1name] [srv2name], and [srv3name]. The properties listed in the section for each PI Server define the iorates points for that server. The properties for iorates points are named IOTAG1, IOTAG2,...IOTAGn.
Note: Like the server property names SERVER1, SERVER2... SERVERn, the IORATES property names are read in numeric order and must use consecutive numbering. If there is a gap in the numeric sequence of the property names, iorates will not be able to read values after the gap.
There are also two special property names, BUFRCV and BUFSND, which are used to specify the iorates points used to monitor the throughput of the PI Server's instance of bufserv. BUFRCV specifies a point used to monitor events sent by PI API applications to bufserv, and BUFSND specifies a point used to monitor events sent by bufserv to PI Server.
Each iorates point defined requires the PI point name and the iorates counter index. Optionally, if a RAW argument is specified, then iorates writes the raw value of the counter rather than the default rate of change of the counter (change per minute). Each of these definitions is listed as a comma separated string with the following syntax:
Example of sections for individual PI Servers, including BUFRCV, BUFSND, and IOTAG1:
The following section for a PI server named srv1name defines iorates points for the following:
Note: The names used for the specified PI points are not relevant, provided that the points specified in the iorates.ini file exist on the corresponding PI Server.
If the default PI server is piserver1 and the
iorates.dat file contains the following entries:
Then you can define the same server, PI points, and counters in an
iorates.ini file as follows:
In this example, the interface node has one interface running, and the interface is sending data to a collective with the members PIServerA and PIServerB. To use iorates to monitor the throughput of the instances of bufserv, iorates.ini must contain sections and properties similar to the following:
Note: For a collective, the iorates point for the event rate of the interface only needs to be specified in one of the PI server sections. In the above example, the event rate is calculated and sent when PIServerA is processed, and because of n-way buffering, that value is also sent to PIServerB. The bufserv monitoring points have to be specified under both PI Server sections because they are different points, monitoring the different instances of the bufserv process.
To verify the configuration of iorates, check
PIHOME/dat/pimesslogfile on startup. When iorates starts and reads the contents of the iorates.ini file, it logs both the number of servers and the details of the points loaded for each PI Server. If errors are found, or property keys are incorrect, the resulting messages may help identify the problem.
The following example shows the results for a single PI server configured with 5 iorates points.
iorates>> Number of PI Servers: 1
iorates>> Connecting to PI Server (1): SERVER1
iorates>PI-API> Initial connection to [SERVER1](192.168.1.1) Buffered
iorates>loadioratestags> IOrates tag: SY.VM-CENTOS4_S1_RANDOM.IORATE registered. Calc type: 0 Counter: 2
iorates>loadioratestags> IOrates tag: SY.VM-CENTOS4_TOTAL_IORATE registered. Calc type: 0 Counter: 47
iorates>loadioratestags> IOrates tag: SY.VM-CENTOS4_TOTAL_IORATE_RAW registered. Calc type: 1 Counter: 47
iorates>loadioratestags> IOrates tag: SY.VM-CENTOS4_BUFRCV registered. Calc type: 0 Counter: 3
iorates>loadioratestags> IOrates tag: SY.VM-CENTOS4_BUFSND registered. Calc type: 0 Counter: 4
iorates>loadioratestags> 5 rate tag(s) registered.
iorates>> Total number of tags: 6
If iorates quits or exits and you find messages like the following in
PIHOME/dat/pimesslogfile, then check whether ioshmsrv is running. When PI API processes start, the IO shared memory server (ioshmsrv) also starts and allocates a block of shared memory for up to 200 event counters (1-200). Since the shared memory is used for iorates counters, ioshmsrv must be running in order for iorates to function properly.
iorates>cntclsshm> error, exit
iorates>cntgetshm> error, exit