PASSPORT PERFORMANCE LIBRARY README.txt 9/10/98
------------------------------------------------
This library defines an interface class and a single implementation to
synchronously set performance counters in a application. Currently
there is only one implementation: NT Performance Monitor. In the
future there may be other implementations for SNMP traps, etc.
A performance counter is a single DWORD, that an application may
increment, decrement or set. An application may define many performance
counters. Counters are communicated out-of-process to the perfmon
application via a memory-mapped files. Counters are lightweight: for
the application, incrementing a counter is just modifiying a DWORD in a
section of shared memory. Examples of performance counters are numbers
of items in a cache, number of failed authentications, etc.
Typing 'build' in each of the directories hubCounters, brokerCounter,
testCounters creates a single performance Dll for that directory. That
performance Dll is used both by the application and the performance
monitor itself.
This is an implementation of **static** performance counters: the
performance counters must be defined before running the application in
order to be useful. Counters may not be created dynamically while the
program is executing. The reason for this is that installing a perf
counter a pre-existing key for the perfmon application must be modified.
If the application dies suddenly, then the perfmon registry entry can
only be rolled back manually. Datacenter personel have complained that
dynamic counters are messing up their registries.
However, Instances (of performance objects, not counters) may be created
and destroyed dynamicially. This allows the monitoring of, for example,
open socket connections by name.
Initial Setup:
--------------
Build (type "build -c") in the $(PASSDEV)/common/PerfLibrary and in
relevant subdirectory (hubCounters or brokerCounters) to build the
hubCounters.dll or the brokerCoutners.dll.
Setting Up the Registry
-----------------------
In order to use the perfmon counters you must make chages to you
registry. If you do make those changes your application will not be
affected, but you will not be able to read the perfmon counters!
FIRST BACK UP YOUR REGISTRY! INSTALLING THE PERFMON COUNTERS MAKES
CHANGES TO YOUR REGISTRY! **ESPECIALLY** BACK UP THE KEY:
[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Perflib]
To install the counters, go to the directory where the <name>Counter.dll
lives Dll lives (most likely $(PASSDEV)/sdk/lib/i386). Make sure you have
these three files in that directory.
<name>Counters.dll
<name>Counters.ini
<name>Counters.h
If those three files are not present copy the from dev. tree (most likely
$(PASSDEV/common/PerfLibrary/<name>Counters) and run the command:
'regsvr32 <name>Counters.dll'
where <name> is hub or broker. You should see the respective key added
to the "SYSTEM\\CurrentControlSet\\Services\\<name>Counters"
registry location. This modifes both the above
"SYSTEM\\CurrentControlSet\\Services\\<name>Counters" registry key and
the registry you created when you installed NT at:
"HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Perflib"
Uninstalling the Registry
-----------------------
To uninstall the counters, go to the directory where the <name>Counter.dll
lives Dll lives (most likely $(PASSDEV)/sdk/lib/i386). Make sure you have
these three files in that directory.
<name>Counters.dll
<name>Counters.ini
<name>Counters.h
If those three files are not present copy the from dev. tree (most likely
$(PASSDEV/common/PerfLibrary/<name>Counters) and run the command:
'regsvr32 /u <name>Counters.dll'
Class Interface Usage:
----------------------
#include "PassportPerfDefs.h" // for SHM name defines
#include "TestCounters.h" // for counter defines
#include "PassportPerfInterface.h" // for object interface
static PassportPerfInterface * perf = NULL;
if (perf == NULL)
{
perf = (PassportPerfInterface *)
CreatePassportPerformanceObject(
PassportPerfInterface::PERFMON_TYPE);
if (perf != NULL)
{
if (!perf->init( PASSPORT_PERF_BLOCK))
// error
}
else
// error
}
// to increment a counter without an instance
if (!perf->incrementCounter(TESTCOUNTERS_PERF_TEST_COUNTER1))
{
// error
}
// to add an instance to that object
CHAR instanceName[PassportPerfInterface::MAX_INSTANCE_NAME];
strcpy( instanceName,"Instance");
if (!PA->addInstance( instanceName ))
{
// error
}
// to increment a counter with an instance
if (!perf->incrementCounter(TESTCOUNTERS_PERF_TEST_COUNTER1, instanceName))
{
// error
}
// note if you try perf->incrementCounter(TESTCOUNTERS_PERF_TEST_COUNTER1)
// after you've added an instance to that object it will fail
// to modify a counter type
if (!perf->setCounterType (TESTCOUNTERS_PERF_TEST_COUNTER1,
PassportPerfInterface::AVERAGE_TIMER))
{
// error
}
Modifying Counters
------------------
The counter definitions for the broker and hub have been created in the
brokerCounter and hubcounter directory. Modifyiing these counters has a few steps:
1. Make sure you've backed up your registry, especially the
[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Perflib] key.
2. go to the directory where the <name>Counter.dll
lives Dll lives (most likely $(PASSDEV)/sdk/lib/i386). Make sure you have
these three files in that directory.
<name>Counters.dll
<name>Counters.ini
<name>Counters.h
If those three files are not present copy the from dev. tree (most likely
$(PASSDEV/common/PerfLibrary/<name>Counters) and run the command:
'regsvr32 <name>Counters.dll'
This will both unistall the previous counters and re-install the new counters
3. Re-start the perfmon and check to see if the new counters
are in the addcounter menu.
