Skip to content
CapaSystems Docs

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

Introduction

Section titled “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

Section titled “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

Section titled “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

Section titled “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:

NameDefaultRangePrecedence
CMSDirCMS\Three valid path types:
1) ”.”
2) “<subdir>”
3) “<drive>:<path>“		Local directory where data files are stored.
CMSMaxFiles20[1;n]Maximum number of data files in the directory. The oldest files are deleted when the number of files reaches CMSMaxFiles.
CMSReportTime900ReportInterval 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:

ParameterDefaultRangeDescription
CMSEnabledfalsetrue/falseEnables/disables CMS integration
When this is enabled´, the PG agent will also generate a full Startup report, regardless of any other options.
CMSForcedfalsetrue/falseIf 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.
CMSDirCMSThree valid types:
Three valid path types:
1) ”.”
2) “<subdir>”
3) “<drive>:<path>“		Local directory where data files are stored.
CMSMaxFiles20[1;n]Maximum number of data files in the directory. The oldest files are deleted when the number of files reaches CMSMaxFiles.
CMSReportTime900ReportInterval 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.
ReportInterval60[1;n]Report period in seconds. See PG documentation
ServerMetricsfalsetrue/falseMeasure context switches etc. See PG documentation
CollectOSStartfalsetrue/falseMeasure startup/login time. See PG documentation
StartupCondition--End condition for startup measurement. See PG documentation
StartupTimeOutSecs300[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
DynamicMachineReporttruetrue/falseSee PG documentation
DiskIOReportfalsetrue/falseSee PG documentation
ProcessStatInterval10[1;n]Sample period in seconds.
ContextSwitchPerProcessfalsetrue/falseMeasure context switches per process. See PG documentation

Location****Data 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 7C:\ProgramData
Windows VistaC:\ProgramData
Windows XPC:\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 :

DefaultInfoE2EReportAssemblerCMS parameterData 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 permissionto 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>