windows-server-2003/ds/security/passport/common/perflibrary/readme.txt

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.