Overview

The perfMonitor package provides a PerfMonitor API for managing counters, measures, and timers that can be used to instrument an application in order to collect metrics about the application's runtime performance. For example:

• Using counters to count the number of user sessions.
• Using measures to track the size of caches and other data structures
• Using timers to measure the amount of time spent inside subsystems

Categories

All of the entries (counters, measures, and timers) obtained from the PerfMonitor are assumed to be part of a hierarchy based on a naming convention that is similar to the Java package naming convention. However, the following conventions are used by the PerfMonitor which differ from the standard Java convention:

• The TRACE! prefix is reserved for use by entries that are not normally enabled by the application but are enabled only when specific tracing is to be performed and/or when the extra tracing overhead is acceptable.
• The BENCHMARK<...>! prefix is reserved for entries that are enabled by the PerfContext. These entries provide server-side tracing for requests that have been specially tagged. For example, the Content Manager server-side benchmarking feature uses the special X-Cognos-ContentManager-Benchmark HTTP header to tag requests for use with PerfContext.

To test whether an entire category is enabled or disabled a PerfCategory instance can be obtained from the PerfMonitor.getCategory method:

private static final PerfCategory PERF_CATEGORY1 =
		PerfMonitor.getCategory(
			"TRACE!org.myorg.test", 
			"", 
			PerfOptions.PERMANENT);
		
if (PERF_CATEGORY1.isEnabled()) {
  // do something ...
}

PerfOptions

• OPTIONAL entries can be enabled and disabled.
• MANDATORY entries cannot be disabled and are always enabled.
• PERMANENT entries cannot be removed from the PerfMonitor, even when/if they are disabled. It is important to use the PERMANENT option for any entries that referred to by static fields or other references which must not be orphaned when attempts are made to enable/disable the entries in the PerfMonitor.
• DEFAULT entries are currently marked as OPTIONAL.

Enabling/Disabling Entries

If an entry was not created as a mandatory entry, then the entry may be enabled or disabled by invoking the PerfMonitor.enableCategory or PerfMonitor.enabledCategories methods. Mandatory entries are always enabled although their metrics won't be reported by PerfOutput if their category isn't enabled.

Counters

The most basic entry is a PerfCounter. A counter can be incremented or decremented. Each PerfCounter instance is MT-safe (thread-safe or synchronized) so multiple threads can safely increment and decrement the same instance without corrupting the underlying counter value.

Measures

A PerfMeasure tracks two metrics: i) the number of times the measurement is incremented/decremented and ii) the current value for the measurement. The PerfMeasure is also MT-safe.

Timers

Dynamic timers

A PerfTimer is used to record the amount of (wall-clock) time spent executing some block of code. A timer is started by calling the start() and is stopped by calling the stop() method. Each timer has an underlying PerfMeasure that is updated with the recorded duration every time a running timer is stopped. Note: A timer obtained from a PerfMonitor.getTimer is not MT-safe so every thread would need to obtain its own timer instance. To share the same timer instance across threads use a PerfMonitor.getThreadLocalTimer method.

PerfTimer timerAdd = PerfMonitor.getTimer("org.myorg.test.timer1");
timerAdd.start();
doSomething(); // anything...
timerAdd.stop();

ThreadLocal (static) timers

An application will often have a set of standard subsystem timers that exist for the entire lifetime of the application. For these scenarios the perfMonitor package provides thread-local timers that can be statically allocated and referenced by many concurrent threads to update the same underlying counter with timing data.

private static final PerfTimer TIMER1 = 
	PerfMonitor.getThreadLocalTimer(
		"org.myorg.test.timer1", 
		"... description ...", 
		PerfOptions.PERMANENT);
	
public void testStaticCounters() {
	TIMER1.start();
	doSomething(); // anything ...
	TIMER1.stop();
}

These thread local timers were introduced to help reduce the amount of timer related code that has to be inserted in order to instrument code. Since the same static instance can be reused by multiple threads it isn't necessary for each thread to lookup and create their own dynamic timer that wraps the same underlying counter value.