Introduction

This document describes how to integrate a Performance Guard agent with a CMS agent on a client PC.

The integration enables you to pass performance data measured by a PG agent to a CMS agent.

The PG agent will measure performance data and at regular intervals, specified by the CMS agent, store the performance data in local xml files. The CMS agent will later collect the xml file content and send it to the CMS backend.

Installation

The installation procedure consists of the following steps:

1. Install a CapaInstaller agent on the PC, if not already installed.
2. Install a PG agent (version 5.6 and later) on the PC, if not already installed.

Install a CapaInstaller agent if not already installed

Please follow the CapaInstaller documentation for installing an agent.

Install a PG agent if not already installed

Please follow the PG agent installation documentation if you are deploying an agent that should connect to the PG server.

If you are deploying a standalone PG agent you should simply install the agent using the msi file by executing the following command (as an administrator):

32-bit:  msiexec  /i  CI_PGAgent.msi  /qn

64-bit:  msiexec  /i  CI_PGAgent64.msi  /qn

The agent can of course be deployed using CMS.

The agent will be installed in the following default directory:

32-bit:  c:\Program  Files (x86)\CI\Performance  Guard  Agent

64-bit:  c:\Program  Files\CI\Performance  Guard  Agent

The agent will be installed as a windows service called "CI Performance Guard Agent" and the service is started automatically.

Configuration

Standalone configuration

If the PG agent does not communicate with a PG server you must do the following to configure the integration between PG and CMS:

1. Stop the Performance Guard Agent Service
2. Create a text file with agent registry settings. The following is an example text file:

Configuration = "ReportInterval=60
DynamicMachineReport=true 
DiskIOReport=true 
ProcessStatInterval=10 
ContextSwitchPerProcess=false 
ServerMetrics=true 
CollectOSStart=true 
DoFullStartupReport=true 
StartupTimeoutSecs=300 
StartupCondition=<PROCESS; winlogon.exe; started> 
LoginStartCondition=<SESSION; logon> 
LoginEndCondition=<PROCESS; explorer.exe; started> 
CMSEnabled=true 
CMSForced=false
CMSMaxFiles=300 
CMSDir=CMS\ 
CMSReportTime=180"

     3. Open a command prompt in the Performance Guard agent directory.

     4. Install the registry settings from the text file (in this case "CMS_PG.cfg") by executing the following command

CI_GUARDagent -configfile="CMS_PG.cfg" -updateregistry

     5. Start the Performance Guard Agent Service

The above steps can be done by the CapaInstaller agent at any time to control the behavior of the PG agent.

Server Configuration

If the PG agent is communicating with a PG server you must enable the "Integration Enabled" option in the CMS section of the agent configuration using the PG Web Console on the PG server. There you can specify all CMS integration parameters.

If you need to control the CMS integration parameters locally on the client you can do the following:

1. Disable the "Always send reports to CMS" option in the CMS section of the agent configuration using the PG Web Console on the PG server.
2. Stop the Performance Guard Agent Service
3. Create a text file with agent registry settings. The following is an example text file:

CMSInterface = "CMSMaxFiles=300 CMSDir=CMS\ CMSReportTime=180"

     4. Open a command prompt in the Performance Guard agent directory.

     5. Install the registry settings from the text file (in this case "CMS_PG.cfg") by executing the following command

GUARDagent -configfile="CMS_PG.cfg" -updateregistry

     6. Start the Performance Guard Agent Service

Registry Parameters

The PG agent reads/stores its configuration from the following registry key:

32 Bit system: HKLM\SOFTWARE\Premitech\E2EAgent

64 bit system:  HKLM\SOFTWARE\wow6432Node\Premitech\E2EAgent

If the PG agent is an OEM version, the registry key will be:

32 Bit system: HKLM\SOFTWARE\Premitech\<OEM-name>_E2EAgent

64 bit system:  HKLM\SOFTWARE\wow6432Node\Premitech\<OEM-name>_E2EAgent

The CMSInterface registry parameter

The CapaInstaller agent can control the behavior of the PG agent by setting the value of the "CMSInterface" registry parameter. The value is itself a multi-line string with a name-value pair on each line.

The possible named values are:

The "Configuration" registry parameter

If the PG agent is connected to a PG server it will initially receive its configuration from the PG server. The configuration is then stored locally in the registry parameter "Configuration". If the PG agent is not connected to a PG server, the value of the "Configuration" parameter will be empty.

The "Configuration" parameter value is a multi-line text string, where each line is a configuration parameter and value pair.

By default the PG agent does not integrate with CMS, so you must set some parameters manually if they are not controlled by a PG server.

The following table is a subset of parameters that can be set in the "Configuration" registry parameter:

LocationData Files

The name of the produced data files is PGData<nn>.xml (<nn> is the date in seconds since epoch).

The location of the files is defined by the CMSDir parameter. Be aware that a service like the PG agent is not allowed to write anywhere on the local disk.

If the value of the CMSDir parameter is not a full path, it is considered to be a subdirectory of the “%ProgramData%" folder. This is a safe location for services to write files.

The value of the %ProgramData% environment variable  depends on the type of operating system:

The actual path used by the agent can be seen in the web console of the agent:

 http://127.0.0.1:4007/cmd/cmd?group=view&cmd=VIEW_ERRORS

Use the Search filter to look for:

NOTE: If you can't find the folder in Windows, the reason can be that you don't have the permission to view the folder, or that your Windows Explorer options hide protected and hidden folders from you. Try opening the folder anyway by typing the name of the folder into Windows Explorer.

File Format

1. AggregateRunningSystemReport :Aggregated values describing the usage of the CPU, Memory, DiskIO, NetIO, and TotalUtilizationMeasure. All the values are described in a 1 to 100 usage measure. Where 1 is very low usage and 100 is maximum usage. NetworkIO and DiskIO usages are calculated from reference values stored in the PG configuration. The TotalUtilizationMeasure is the worst (highest) of the 4 basic usage measures.
2. RunningSystemReport: Detailed information about the current performance of the machine
3. StartupBriefReport: information about the time and duration of an operating system startup event.
4. LoginBriefReport: Information about the time and duration of a user login event. Also contains the name of the user that logged in.

<?xml version="1.0" encoding="windows-1252"?>
<PerformanceGuardData>
	<PGData Version="SVN- ="/>
	<AggregateRunningSystemReport>
		<CPU ValueType='ULong'>4</CPU>
		<Mem ValueType='ULong'>83</Mem>
		<DiskIO ValueType='ULong'>14</DiskIO>
		<NetIO ValueType='ULong'>0</NetIO>
		<TotalUtilizationMeasure ValueType='ULong'>83</TotalUtilizationMeasure>
	</AggregateRunningSystemReport>
	<RunningSystemReport>
		<SampleInterval ValueType='ULong'>1351000440</SampleInterval>
		<PeakCPUUsage ValueType='UChar'>100</PeakCPUUsage>
		<AverageCPUUsage ValueType='ULong'>4</AverageCPUUsage>
		<LowFreePhysicalMemory ValueType='ULong'>2095064</LowFreePhysicalMemory>
		<AverageFreePhysicalMemory ValueType='ULong'>2127962</AverageFreePhysicalMemory>
		<LowFreePagingFile ValueType='ULong'>2867</LowFreePagingFile>
		<AverageFreePagingFile ValueType='ULong'>2909</AverageFreePagingFile>
		<LowVirtualMemory ValueType='ULong'>5031348</LowVirtualMemory>
		<AverageFreeVirtualMemory ValueType='ULong'>5108404</AverageFreeVirtualMemory>
		<AverageDiskWrites ValueType='ULong'>256949</AverageDiskWrites>
		<AverageDiskReads ValueType='ULong'>10939</AverageDiskReads>
		<PeakDiskWrites ValueType='ULong'>5733826</PeakDiskWrites>
		<PeakDiskReads ValueType='ULong'>73735</PeakDiskReads>
		<AverageContextSwitches ValueType='ULong'>22910</AverageContextSwitches>
		<PeakContextSwitches ValueType='ULong'>94072</PeakContextSwitches>
		<AverageSendBytes ValueType='ULong'>632</AverageSendBytes>
		<PeakSendBytes ValueType='ULong'>3033</PeakSendBytes>
		<AverageRecvBytes ValueType='ULong'>21415</AverageRecvBytes>
		<PeakRecvBytes ValueType='ULong'>186573</PeakRecvBytes>
	</RunningSystemReport>
	<StartupBriefReport>
		<SampleTime>15035</SampleTime>
		<StartTime>1351000440</StartTime>
		<Success>true</Success>
	</startupBriefReport>
	<LoginBriefReport>
		<SampleTime>23000<SampleTime>
		<LoginTime>1351500440<LoginTime>
		<LoggedInUser>User25<LoggedInUser>
		<Success>true<Success>
	</LoginBriefReport>
</PerformanceGuardData>