How to integrate a Performance Guard agent with a CapaInstaller agent on a client PC.

Owned by Former user (Deleted)
Sept 07, 2020
5 min read

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:


Name

Default

Range

Precedence

CMSDir

CMS\

Three valid path types:

1) "."

2) "<subdir>"

3) "<drive>:<path>"

Local directory where data files are stored.

CMSMaxFiles

20

[1;n]

Maximum number of data files in the directory. The oldest files are deleted when the number of files reaches CMSMaxFiles.

CMSReportTime

900

ReportInterval x [1;n]

The number of seconds between each data file is stored to disk. The number of seconds should be larger than the ReportInterval value from the Configuration registry parameter - and preferably a multiplum of ReportInterval.


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:


Parameter

Default

Range

Description

CMSEnabled

false

true/false

Enables/disables CMS integration

When this is enabled´, the PG agent will also generate a full Startup report, regardless of any other options.

CMSForced

false

true/false

If set to true, the value of the CMSInterface registry parameter is ignored, i.e. PG agent is in control. If set to false, the value of the CMSInterface registry parameter takes precedence over the Configuration registry parameter, i.e. the CMS agent is in control.

CMSDir

CMS

Three valid types:

Three valid path types:

1) "."

2) "<subdir>"

3) "<drive>:<path>"

Local directory where data files are stored.

CMSMaxFiles

20

[1;n]

Maximum number of data files in the directory. The oldest files are deleted when the number of files reaches CMSMaxFiles.

CMSReportTime

900

ReportInterval x [1;n]

The number of seconds between each data file is stored to disk. The number of seconds should be larger than the ReportInterval value from the Configuration registry parameter - and preferably a multiplum of ReportInterval.

ReportInterval

60

[1;n]

Report period in seconds. See PG documentation

ServerMetrics

false

true/false

Measure context switches etc. See PG documentation

CollectOSStart

false

true/false

Measure startup/login time. See PG documentation

StartupCondition

-

-

End condition for startup measurement. See PG documentation

StartupTimeOutSecs

300

[1;n]

The timeout value for the startup condition. See PG documentation

LoginStartCondition

-

-

Start condition for login measurement. See PG documentation

LoginEndCondition

-

-

End condition for login measurement. See PG documentation

DynamicMachineReport

true

true/false

See PG documentation

DiskIOReport

false

true/false

See PG documentation

ProcessStatInterval

10

[1;n]

Sample period in seconds.

ContextSwitchPerProcessfalsetrue/falseMeasure context switches per process. See PG documentation


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:

OS

%ProgramData%

Windows 7

C:\ProgramData

Windows Vista

C:\ProgramData

Windows XP

C:\Documents  and  Settings\All  Users\Application  Data



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:

Example :


Default

Info

E2EReportAssembler

CMS parameter

Data Files Path='C:\ProgramData \CMS\'


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>