Error Logs and Trace Logs

You can use the Web Agent logging function to monitor the performance of the Web Agent and its communication with the Policy Server. The logging feature provides accurate and comprehensive information about the operation of
CA Single Sign-On
processes to analyze performance and troubleshoot issues.
A log is a record of events that occur during program execution. A log consists of a series of log messages, each one describing some event that occurred during program execution. Log messages are written to log files.
IIS Agents create log files only after the first user request is submitted. Apache 2.0 Web Agents create log files when the Apache server starts.
The Web Agent uses the following log files:
  • Error log
    Contains program and operational-level errors. One example is when the Web Agent cannot communicate with Policy Server. The level of detail output in this log cannot be customized. Error logs contain the following types of messages:
    • Error messages
      Contain program-level errors, which indicate incorrect or abnormal program behavior, or an inability to function as expected due to some external problem, such as a network failure. There are also operational-level errors. This type of error is a failure that prevents the operation from succeeding, such as opening a file or authenticating a user.
    • Informational messages
      Contain messages for the user or administrator that some event has occurred; that is, that a server has started or stopped, or that some action has been taken.
    • Warning messages
      Contain warnings for the user or administrator of some condition or event that is unusual or indicative of a potential problem. This does not necessarily mean there is anything wrong.
  • Trace log
    Contains detailed warning and informational messages, which you can configure. Examples include trace messages and flow state messages. This file also includes data such as header details and cookie variables. Trace logs contain the following messages:
    • Trace messages
      Provide detailed information about program operation for tracing and/or debugging purposes. Trace messages are ordinarily turned off during normal operation. In contrast to informational, warning, and error messages, trace messages are embedded in the source code and can not easily be localized. Moreover, trace messages may include significant data in addition to the message itself; for example, the name of the current user or realm.
You specify the location of both the error and trace log files when you configure the Web Agent. Use the error and trace logs to help solve any issues that may prevent the Web Agent from operating properly.
For Agents on Windows platforms, set the EnableWebAgent parameter to yes to ensure that the Web Agent log gets created. If you leave EnableWebAgent set to no (the default) and set the logging parameters, the Agent log gets created only for Agents on UNIX platforms.
Parameter Values Shown in Log Files
Web Agents list configuration parameters and their values in the Web Agent error log file, but there are differences between the ways that Traditional and Framework agents do this.
Framework agents record the configuration parameters and their values in the log file exactly as you entered them in the Agent Configuration Object or the local configuration file. All of the parameters, including those which may contain an incorrect value, are recorded in the log file.
Traditional agents process the parameter values before recording them. If the parameter has a proper value, the parameter and its value are recorded in the log file. Parameters with incorrect values are
recorded in the log file.
Set Up and Enable Error Logging
Error logs require the following settings:
  • Logging is enabled.
  • A location for the log file is specified.
The parameters that enable error logging and determine options such as appending log data are defined in a local configuration file or an Agent Configuration Object at the Policy Server.
Agents that are installed on an IIS or Apache web servers do not support dynamic configuration of log parameters that are set locally in a local configuration file. The changes take effect when the Agent is restarts. However, these log settings can be stored and updated dynamically in an agent configuration object at the Policy Server.
IIS Agents create log files only after the first user request is submitted. Apache 2.0 Web Agents create log files when the Apache server starts.
Follow these steps:
  1. If you do not have a log file already, create a log file and any related directories.
  2. Set the value of the LogFile parameter to yes.
    Setting the value of this parameter to yes in a local configuration file of a web server overrides any of the logging settings that are defined on the Policy Server. For example, suppose that the value of this parameter is set to yes in a LocalConfig.conf file. The agent creates log files even though the value of the AllowLocalConfig parameter in the corresponding agent configuration object is set to no. You can also set the related logging parameters in the LocalConfig.conf file also to override any other settings in the agent configuration object.
  3. Specify the full path to the error file, including the file name, in any of the following parameters:
    • sm1252sp1
      Specifies the full path (including the file name) of the log file.
      (UNIX/LInux) /export/iPlanet/servers/https-jsmith/logs/WebAgent.log
    • sm1252sp1
      Specifies the full path of a log file for a
      CA Single Sign-On
      Web Agent for IIS (on 64-bit Windows operating environments protecting 32-bit applications). The 32-bit applications run in Wow64 mode on the 64-bit Windows operating environment. If logging is enabled but this parameter is not set, the Web Agent for IIS appends _32 to the log file name.
      : No
      : For Windows 64-bit operating environments only. Specify the file name at the end of the path.
      : (Windows 64-bit operating environments using Wow64 mode)
  4. (Optional) Set the following parameters (in the Agent Configuration Object on the Policy Server or in the local configuration file):
    • sm1252sp1
      Adds new log information to the end of an existing log file. When this parameter is set to no, the entire log file is rewritten each time logging is invoked.
    • sm1252sp1
      Specifies the size limit of the log file in megabytes. When the current log file reaches this limit, a new log file is created. The new log file uses one of the following naming conventions:
      • For framework agents, the new log file has a sequence number that is appended to the original name. For example, a log file named myfile.log is renamed to myfile.log.1 when the size limit is reached.
      • For traditional agents, the new log files are named by appending the date and timestamp to the original name. For example, a log file named myfile.log, is renamed to myfile.log.09-18-2003-16-07-07 when the size limit is reached.
      Archive or remove the old files manually.
      0 (no rollover)
    • sm1252sp1
      Specifies whether the logs use Greenwich Mean Time (GMT) or local time. To use GMT, change this setting to no. If this parameter does not exist, the default setting is used.
      If you use a local configuration file, your settings resemble the following example:
      LogFile="yes" LogFileName="/export/iPlanet/servers/https-myserver/logs/errors.log" LogAppend="no" LogFileSize="80" LogLocalTime="yes"
    Error logging is enabled.
Enable Transport Layer Interface (TLI) Logging
When you want to examine the connections between the agent and the Policy Server, enable transport layer interface logging.
To enable TLI logging
  1. Add the following environment variable to your web server.
  2. Specify a directory and log file name for the value of the variable, as shown in the following example:
  3. Verify that your agent is enabled.
  4. Restart your web server.
    TLI logging is enabled.
Limit the Number of Log Files Saved
You can limit the number of log files that an agent keeps. For example, if you want to save disk space on the system that stores your agent logs, you can limit the number of log files using the following parameter:
Specifies the number of agent log files that are kept. New log files are created in the following situations:
  • When the agent starts.
  • When the size limit of the log file (specified by the value of the LogFileSize parameter) is reached.
Changing the value of this parameter does
automatically delete any existing logs files which exceed the number that you want to keep. For example, If your system has 500 log files stored, and you decide to keep only 50 of those files, the agent does
delete the other 450 files.
Setting the value of this parameter to zero retains all the log files.
: 0
Follow these steps:
Archive or delete any existing log files from your system.
Set the value of the LogAppend parameter to no.
Change the value of the LogFilesToKeep parameter to the number of log files that you want to keep.