Agent Error Logging

Errors and important events that occur on the agent are logged in the agent as special Error Log Reports.

It’s possible to view these reports on the agent using the web and telnet interfaces, but it’s also possible to let the agent send the reports to the PerformanceGuard server, that stores them in the database.

Error reports sent to the server may be viewed centrally using the web interface.

Error types and severities

Events are classified according to the situation in which they occurred:

Internal Name	Numerical Value	Description
DEFAULT	1000	The event occurred in an unspecified state
CONFIG	1001	The event occurred while the agent was being configured
TYPE_RUNTIME	1002	The event occurred during the agent’s normal operation
TYPE_WINPCAP	1003	The event occurred when the agent interacted with the packet capture driver
TYPE_BTM	1004	The event occurred when the agent interacted with an AutoSteps (BTMv2) component or inside an AutoSteps component
TYPE_IEAGENT	1005	The event occurred in the Internet Explorer helper
TYPE_CITRIXAGENT	1006	The event occurred when the agent interacted with the Citrix helper or inside the Citrix helper

Events generated by the agent have one of the following severities:

Internal Name	Numerical Value	Description
SEVERITY_INFO	0	An event that’s part of the agent’s normal operation has occurred
SEVERITY_USER	11	Some user-supplied data, for example part of the configuration caused a problem
SEVERITY_MINOR	128	A minor problem was encountered, but the overall operation of the agent is unaffected
SEVERITY_SEVERE	129	A problem occurred that means that some part of the agent’s normal operation is affected
SEVERITY_BLOCKING	130	A problem occurred that causes a major or all parts of the agent to malfunction

Configuration

The agent will always collect all error reports locally. By default, all error reports that have a severity of User (11) or higher are also sent to the PerformanceGuard backend and stored in the database.

In the Error Handling section of the agent configuration, you can change the minimum severity with Minimum severity level of error reports that are sent.

With Include details in error reports. you control whether error details are sent from agents to the PerformanceGuard server. By default, error details are not sent.

If you configure agents to send all error reports, you’ll put a stress on the system, with respect to bandwidth and database, as the agent generates a significant amount of informational error logs, for example during configuration.

View errors

View locally on the agent

Errors may be viewed using the agent Telnet interface (view errors) and the web interface (View > Errors).

The agent keeps error log reports for a number of configuration periods. A new configuration period starts each time the agent is configured, for example when it receives a new configuration. When the limit is exceeded, the agent deletes the error log reports from the oldest configuration period. The number of configuration periods is controlled by the agent registry value ErrorConfigKeepPeriods. The default is 2.

The Telnet interface lists all error log entries sorted by time stamp. The web interface lets you filter on the location, the name and the severity of events.

View centrally in the PerformanceGuard web interface

You can view agent error log reports in the PerformanceGuard web interface: Select ADMINISTRATION > Status > Errors. You can filter on interval, name, component, agent ID and severity.

Event processor debug messages

If the LogErrorsToFile registry value is specified for the agent, special event processor log entries will be created in the log file.

An example of these messages and their meaning: Consider an agent with the following login configuration:

• Text

LoginStartCondition=<SESSION; logon>
LoginEndCondition=<PROCESS; GUARDagent; started> and <PROCESS; explorer; started> and <CPU; explorer; below; 10>

Two event processors will be instantiated:

LoginStartEvaluator

• Value : Expr1
• Expr1 : <SESSION; logon>

and LoginEndEvaluator

• Value : And( Expr2, And( Expr3, Expr4 ) )
• Expr2 : <PROCESS; GUARDagent; started>
• Expr3 : <PROCESS; explorer; started>
• Expr4 : <CPU; explorer; below; 10>

For each expression the event processors will calculate a list of <value; time> pairs that record the value of the expression for specific points in time.

Error log file entries

In the error log file you can follow how the value of the expressions evolve over time. The LoginStartEvaluator logs its state like this:

• Text

Mon Jun 21 15:22:20 2010|Config|Info|E2EDynamicMachine|LoginStartEvaluator|State='<SESSION;logon> Values: 0ms:unknown, 12921600507781ms:true'|

The state of an evaluator is expressed as a number of lines, one for each sub-expression, each ending with a list of <value; time> pairs, indicating the value of the sub-expression at different points in time.

The expression is read like: the value of Expr1, that is at t=0 the value is unknown, at t = 12921600507781 ms the value changes to true.

This means that the Login Start Condition is true from the time 12921600507781 ms.

In this example, the LoginEndEvaluator is slightly more complicated, and the state logged is:

• Text

Mon Jun 21 15:22:20 2010|Config|Info|E2EDynamicMachine|LoginEndEvaluator|State='
AND: 12921600508968ms:unknown, 12921600519625ms:unknown
    <PROCESS;GUARDagent;started> Values: 12921600519625ms:true
    AND: 12921600508968ms:unknown
        <PROCESS;explorer;started> Values: 12921600508968ms:true
        <CPU;explorer;below;10> Values:
'|

This is easiest read from the bottom and up. The value of Expr4 is unknown, which results in the last AND being unknown (from 12921600508968 ms), which in turns renders the entire result unknown.

Five seconds later in the log file, the following entry is found:

• Text

Mon Jun 21 15:22:25 2010|Config|Info|E2EDynamicMachine|LoginEndEvaluator|State='
AND: 12921600508968ms:unknown, 12921600519625ms:unknown, 12921600531046ms:true
    <PROCESS;GUARDagent;started> Values: 12921600519625ms:true
    AND: 12921600508968ms:unknown, 12921600531046ms:true
        <PROCESS;explorer;started> Values: 12921600508968ms:true
        <CPU;explorer;below;10> Values: 12921600531046ms:true
'|

Here, Expr4 turns true at 12921600531046ms, as Expr2 and Expr3 have turned true earlier, the result of the entire expression is that the login end condition is true at 12921600531046ms.

From the examples, the login time can be calculated as : 12921600531046ms - 12921600507781 ms = 23265 ms = 23.265 s

Log agent errors to a file

The agent can create a detailed log file. This is not enabled by default. To enable it, add the LogErrorsToFile value to the agent registry and set it to the path of an existing folder.

By default the PerformanceGuard agent uses registry values under the key: HKEY_LOCAL_MACHINE\SOFTWARE\PremiTech\E2EAgent

Name:	LogErrorsToFile/DontLogErrorsToFile
Type:	Name of folder
Default value:
Description:	If the LogErrorsToFile value is set in the registry, the agent will try to create a log file and log errors in the file. This can be useful for examining the behavior of the agent, for example during boot and shutdown of the instrumented computer. The value is the name of a folder. The agent tries to create the log file in the named folder first, then in the C:\Users\<user name>\AppData\LocalLow folder of the account that runs the agent, and finally in the agent’s working folder. Log files are named GuardAgent-<process ID>-<time stamp>.log. Some special debugging type messages are only visible in the log file, that is they will never be visible in neither the error display on the agent web service nor transmitted to the PerformanceGuard frontend server. Among these are debugging messages for event processing. Consult CapaSystems technical staff before you use/change this setting.