Summary
In Sycamore release, we are adding a series of performance counters to AXEngine and License Server so that IT administrators can easily monitor the critical system performance, e.g. real time session counts and license usage data, via standard tools like Performance Monitor or other WMI tools.
The article will describe these performance counters in detail and tasks needed to be done by installer and QA.
Performance Counter General Concepts
Performance counters are grouped into categories. Each counter under the specific category is identified by a unique counter name. At runtime, performance counters are further identified by running instances. All the performance counters discussed here are multi-instanced and the runtime instance name is composed from current AppDomain name using following rules:
Illegal characters ("(", ")", "#", "\", or "/") in the AppDomain name are mapped into legal characters ("[", "]", "_", "_”, or "_").
Names longer than 128 characters are truncated to 128 characters max.
Some performance counters require a base counter (Average counter, percentage counters) which needs to be register together with the counter.
Before performance counters can be used, the counter categories and counters must be registered. This task must be performed beforehand. This is typically done via installer or in the case of engineering developer environment, manually register via .NET Framework’s InstallUtil.exe on modules that have the Installer defined.
To manually register the performance counters in development environment, follow these steps
Open a command windows with Administrator privilege.
Go to the directory where the assembly that contains Installer is located.
Type in following command to register the performance counters:
C:\Windows\Microsoft.NET\Framework64\v4.0.30319\InstallUtil.exe assembly-dll-name
To remove the registration, type in following command:
C:\Windows\Microsoft.NET\Framework64\v4.0.30319\InstallUtil.exe /u assembly-dll-name
Our product setup must register performance counters after installed the relevant component. The category names, counter names and counter types must match exactly what is defined in our code.
AXEngine performance counters have application specific settings to allow user selectively enable or disable certain or all categories of performance counters in app.config. This allows further reduction of any overhead of the performance counters by disable them if user doesn’t need to monitor them.
AXEngine Performance Counters
AXEngine is the core component used by WebAccess and ReST Service. Currently, following categories and counters are supported:
Category Name: ApplicationXtender Engine Sessions
Counter Name | Counter Type | Description |
Active Session Count | NumberOfItems32 | The number of active login sessions in current instance. |
Idle Session Count | NumberOfItems32 | The number of idle sessions in session pool of current instance. |
Total AX License Count | NumberOfItems32 | The number of AX user licenses reserved in license pool of current instance. |
Total IC License Count | NumberOfItems32 | The number of ImageCapture licenses reserved in license pool of current instance. |
Total WXPAL License Count | NumberOfItems32 | The number of WX Readonly user licenses reserved in license pool of current instance. |
Active AX License Count | NumberOfItems32 | The number of AX user licenses in use in current instance. |
Active IC License Count | NumberOfItems32 | The number of ImageCapture licenses in use in current instance. |
Active WXPAL License Count | NumberOfItems32 | The number of WX Readonly user licenses in use in current instance. |
Total Fulltext License Count | NumberOfItems32 | The number of Fulltext licenses reserved in license pool of current instance. |
Active Fulltext License Count | NumberOfItems32 | The number of Fulltext licenses in use in current instance. |
Category Name: ApplicationXtender Engine Rendering
Counter Name | Counter Type | Description |
Average Thumbnail Rendering Time | AverageTimer32 | Average thumbnail rendering job elapsed time. This only measures jobs that are waited by AXEngine. Jobs that are waited by client polling are not included. |
Average Thumbnail Rendering Time Base | AverageBase | This is the base counter of the above counter. |
Average Page Rendering Time | AverageTimer32 | Average page rendering elapsed time. |
Average Page Rendering Time Base | AverageBase | This is the base counter of the above counter. |
Average Rendering Job Time | AverageTimer32 | Average rendering job elapsed time (email, export, print). This only measures jobs that are waited by AXEngine. Jobs that are waited by client polling are not included. |
Average Rendering Job Time Base | AverageBase | This is the base counter of the above counter. |
Thumbnail Rendering Request Count | NumberOfItems64 | The number of thumbnail rendering requests. |
Page Rendering Request Count | NumberOfItems64 | The number of page rendering requests. |
Job Rendering Request Count | NumberOfItems64 | The number of job rendering requests. |
Category Name: ApplicationXtender Engine Docs & Batches
Counter Name | Counter Type | Description |
Average Doc Query Time | AverageTimer32 | Average document query elapsed time. |
Average Doc Query Time Base | AverageBase | This is the base counter of the above counter. |
Total Number of Files Imported | NumberOfItems64 | Total number of BIN files imported to documents or batches. |
Total Number of Indexes Created | NumberOfItems64 | Total number of doc indexes created. |
Total Number of Doc Checkouts | NumberOfItems64 | Total number of doc checkout operations. |
Total Number of Doc Checkins | NumberOfItems64 | Total number of doc checkin operations. |
Total Number of Batches Created | NumberOfItems64 | Total number of batches created. |
In the main application’s app.config/web.config file’s <appSettings> section, add following entry to enable or disable the performance counters of AXEngine by category:
<add key="AXEnginePerfCounters" value="Session,Rendering" />
The value could be one of the following:
None – disables all performance counter categories. This is the default value if this entry is missing.
All – enables all performance counter categories.
Session – enables ApplicationXtender Engine Sessions category of counters.
Rendering – enables ApplicationXtender Engine Rendering category of counters.
Doc – enables ApplicationXtender Engine Docs & Batches categories of counters.
Any combinations of Session, Rendering or Doc separated via comma, e.g. “Session,Doc”
XtenderSolutions.AXEngineApi.DLL contains Installer definition that you can run InstallUtil.exe on it to register the performance counters manually.
Counter definitions are contained in AXEngine\Instrumentation\AXEnginePerfCounterInstaller.cs source file.
AX License Server Performance Counters
Following performance counters are defined in AX License Server WCF service:
Category Name: ApplicationXtender License Server
Counter Name | Counter Type | Description |
Active AXUser License Count | RawFraction | The number of active AXUser licenses in use. |
Total AXUser License Count | RawBase | Total number of AXUser licenses. This is the base counter of the above counter. |
Active Full-text License Count | RawFraction | The number of active full-text licenses in use. |
Total Full-text License Count | RawBase | Total number of full-text licenses. This is the base counter of the above counter. |
Active WXPAL License Count | RawFraction | The number of WX Readonly user licenses in use. |
Total WXPAL License Count | RawBase | Total number of WX Readonly user licenses. This is the base counter of the above counter. |
Active Image Capture License Count | RawFraction | The number of Image Capture user licenses in use. |
Total Image Capture License Count | RawBase | Total number of Image Capture licenses. This is the base counter of the above counter. |
Active AX Connector License Count | RawFraction | The number of AX Connector licenses in use. |
Total AX Connector License Count | RawBase | Total number of AX Connector licenses. This is the base counter of the above counter. |
These performance counters can’t be disabled.
XtenderSolutions.Utility.Licensing.EXE contains Installer definition that you can run InstallUtil.exe on it to register the performance counters manually.
Counter definitions are contained in CMLicenseService\CMLicenseServiceInstaller.cs source file.
Setup Changes
As part of installer tasks, AX setup must register performance counters when installing following components:
WebAccess for AXEngine performance counters
ReST Service for AXEngine performance counters
AX License Server for License Server performance counters
Installer must register these performace counters exactly matching what is in our code if it creates the registration separately. Or use .NET InstallUtil to perform the registration.
QA Testing
QA should test to make sure that enable or disable these performance counters does not have adverse impact of product, e.g. no obvious slowdowns, no crashes result of these performance counters etc. And make sure the performance counters work the way it is intended.
Localization
These performance counters are not localized. All counter category names and counter names strictly follow what are hard-coded in the source code.