This section contains the following topics:
To assist in debugging, startup events are recorded in a log. Each message may provide clues about the problem. These logs are stored in the following locations:
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 SiteMinder® 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.
Note: 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:
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:
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.
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.
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.
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:
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.
Note: 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.
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 not recorded in the log file.
Error logs require the following settings:
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.
Note: 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:
Note: 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.
Specifies the full path (including the file name) of the log file.
Default: No
Example: (Windows) web_agent_home\log\WebAgent.log
Example: (UNIX/LInux) /export/iPlanet/servers/https-jsmith/logs/WebAgent.log
Specifies the full path of a log file for a CA SiteMinder® 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.
Default: No
Limits: For Windows 64-bit operating environments only. Specify the file name at the end of the path.
Example: (Windows 64-bit operating environments using Wow64 mode) web_agent_home\log\WebAgent32.log.
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.
Default: No
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:
Archive or remove the old files manually.
Default: 0 (no rollover)
Example: 80
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.
Default: Yes
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.
When you want to examine the connections between the agent and the Policy Server, enable transport layer interface logging.
To enable TLI logging
SM_TLI_LOG_FILE
directory_name/log_file_name.log
TLI logging is enabled.
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:
Changing the value of this parameter does not 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 not delete the other 450 files.
Setting the value of this parameter to zero retains all the log files.
Default: 0
To set up trace logging, use the following process:
Before you can use trace logging, you must configure it by specifying a name, location, and parameters for the trace log file. These settings control the size and format of the file itself. After trace logging is configured, you determine the content of the trace log file separately. This lets you change the types of information contained in your trace log at any time, without changing the parameters of the trace log file itself.
To configure trace logging
Note: If you are running the CA SiteMinder® Agent for IIS and protecting 32-bit applications on a 64-bit system (WoW64 mode), create two duplicates. There are separate directories for 32 and 64-bit applications on 64-bit Windows operating environments.
Note: 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.
Specifies the full path to the trace log file.
Default: No default
Limits: Specify the file name in this parameter.
Example: web_agent_home\log\trace.log
Specifies the full path to the trace file for the CA SiteMinder® Agent for IIS is running on a 64-bit Windows operating environment and protecting 32-bit applications. Set this parameter if you have a CA SiteMinder® Agent for IIS installed on a 64-bit Windows operating environment and protecting a 32-bit Windows application. The 32-bit applications run in Wow64 mode on the 64-bit Windows operating environment. If trace logging is enabled but this parameter is not set, the Web Agent for IIS appends _32 to the file name.
Default: No default.
Limits: For Windows 64-bit operating environments only. Specify the trace file name at the end of the path.
Example: (Windows 64-bit operating environments using Wow64 mode) web_agent_home\log\WebAgentTrace32.log.
Specifies the location of the WebAgentTrace.conf configuration file that determines which components and events to monitor.
Default: No default
Example: web_agent_home\config\WebAgentTrace.conf
Specifies the location of the WebAgentTrace.conf configuration file that determines which components and events to monitor. Set this parameter if you have a CA SiteMinder® Agent for IIS installed on a 64-bit Windows operating environment and protecting a 32-bit Windows application. 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 file name.
Default: No default.
Limits: For Windows 64-bit operating environments only. Specify the configuration file name at the end of the path.
Example: (Windows 64-bit operating environments using Wow64 mode) web_agent_home\config\WebAgentTrace32.conf.
Note: This file is not used until the web server is restarted.
Adds new logging information to the end of an existing log file instead of rewriting the entire file each time logging is invoked.
Default: No
Specifies how the trace file displays the messages. Choose one of the following options:
Default: default (square brackets)
Specifies a custom character that separates the fields in the trace file.
Default: No default
Example: |
Specifies (in megabytes) the maximum size of a trace file. The Web Agent creates a new file when this limit is reached.
Default: 0 (a new log file is not created)
Example: 20 (MB)
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.
Default: Yes
Framework Web Agents do not support dynamic configuration of log parameters set locally in the Agent configuration file. Consequently, when you modify a parameter, the change does not take effect until you restart the web server. However, these log settings can be stored and updated dynamically if you configure them in an Agent configuration object on the Policy Server.
Note: 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 CA SiteMinder® Agent can monitor specific CA SiteMinder® components. When you monitor a component, all of the events for that component are recorded in the trace log. Each component has one or more subcomponents that the agent can also monitor. If you do not want the agent to record all of the events for a component, you can specify only those subcomponents you want to monitor instead.
For example, if you want to record only the single sign-on messages for an agent on a web server, you would specify the WebAgent component and the SSO subcomponent.
The following components and subcomponents are available:
Records all Agent framework messages. (Applies only to framework agents.) The following subcomponents are available:
Records web Agent messages related to the 4.x Affiliate Agent, which is part of Federation Security Services, a separately-purchased product. (Applies only to framework agents.) The following subcomponent is available:
Web Agent messages related to the SAML Affiliate Agent. (Applies only to framework agents.) The following subcomponent is available:
Records all Web Agent log messages. Applies to all Agents except IIS 6.0 or Apache 2.0 Agents. The following subcomponents are available:
Records all Agent API messages. The following subcomponents are available:
Records messages related to internal processing of the Agent API. The following subcomponents are available:
For an explanation of each subcomponent, see the WebAgentTrace.conf file.
You can define what each trace message for a specific component contains by specifying which data fields to include in the message.
Data fields use the following syntax:
data:data_field1,data_field2,data_field3
Some data fields are shown in the following example:
data:message,date,time,user,agentname,IPAddr
There may not be data for fields in each message, so blank fields my occur. For example, if you select RealmOID as a data field, some trace messages will display the realm's OID while others will not.
The following data fields are available:
Includes the actual trace message
Includes the source file and line number of the trace message
Includes the process ID
Includes the thread ID
Includes the date
Includes the time
Includes the time, including milliseconds
Includes the function in the code containing the trace message
Includes the name of the user
Includes the CA SiteMinder® domain
Includes the CA SiteMinder® realm
Includes the Agent name being used
Includes the transaction ID
Includes the CA SiteMinder® domain OID
Includes the client IP address
Includes the trace file displays the IP of the server where Agent is present
Includes the client IP port
Includes the certificate serial number
Includes the subject DN of the certificate
Includes the Issuer DN of the certificate
Includes the CA SiteMinder® session spec
Includes the CA SiteMinder® session ID
Includes the User DN
Includes the requested resource
Includes the requested action
Includes the realm OID
Includes the average response time in milliseconds of the Policy Servers associated with a CA Web Agent or SDK Agent and API application
Note: To output the ResponseTime to a trace log, include the component Agent_Con_Manager along with the data field ResponseTime in the WebAgentTrace.conf file or other file specified in the Policy Server Configuration Object (ACO) and restart the Policy Server. The Agent_Con_Manager component, or Agent API Connection Manager, calculates the ResponseTime each time a response is received from a Policy Server and keeps a running average. To locate the ResponseTime in the trace log, search for [PrintStats].
To focus on a specific problem, you can narrow the output of the trace log by specifying a filter based on the value of a data field. For example, if you are having problems with an index.html page, you can filter on resources with an html suffix by specifying Resource:==/html in the trace configuration file. Each filter should be on a separate line in the file.
Filters use the following syntax:
data_field:filter
The following types of filters are available:
The filters use boolean logic as shown in the following examples:
Action:!=get (all actions except get)
Resource:==/html (all resources ending in /html)
The WebAgentTrace.conf file determines the content of the trace log. You can control which components and data items appear in your trace log by modifying the settings of the WebAgentTrace.conf file on your web server. The following factors apply when editing the file:
When you specify a component, data field, or filter, the values must match exactly the options in the WebAgentTrace.conf file instructions.
Follow these steps:
Note: We recommend duplicating the original file and changing the copy. Modifying the copy preserves the default settings.
# For Apache 2.0, Apache 2.2, IIS 7.0 and SunOne Web Agents
Note: For more information, see the CA SiteMinder® Web Agent Installation Guide.
#components:
components: AgentFramework, HTTPAgent
components: AgentFramework/Administration
#data:
data: Date, Time, Pid, Tid, TransactionID, Function, Message, IPAddr
data: Date, Time, Pid, Tid, TransactionID, Function, Message, IPAddr:==127.0.0.1
Note: Each filter must be on a separate line in the file.
The content of the trace log has been determined.
You can limit the number of trace logs that a CA SiteMinder® 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 trace logs using the following parameter:
Specifies the number of CA SiteMinder® agent trace log files that are kept. New trace logs are created in the following situations:
Changing the value of this parameter does not automatically delete any existing trace logs which exceed the number that you want to keep. For example, If your system has 500 trace logs stored, and you decide to keep only 50 of those files, the agent does not delete the other 450 trace logs.
Setting the value of this parameter to zero retains all the trace logs.
Default: 0
Follow these steps:
To collect detailed information about the connections between a Web Agent and Policy Server, you create a Trace Log file that contains information gathered by the Agent Collection Manager.
To collect detailed web agent connection data
Note: Setting the value of this parameter to yes in a local configuration file of a web server overrides any of the logging settings defined on the Policy Server. For example, when the value of this parameter is set to yes in a LocalConfig.conf file log files are generated even if the value of the AllowLocalConfig parameter in the corresponding Agent Configuration object on the Policy Server is set to no. Additionally, set the related trace logging parameters (that define the file name, size, and so on) in the LocalConfig.conf file to override any Policy Server trace log settings.
web_agent_home/config/AgentConMgr.conf
Indicates the directory where the CA SiteMinder® Agent is installed.
Default (Windows 32-bit installations of CA SiteMinder® Web Agents only): C:\Program Files\CA\webagent
Default (Windows 64-bit installations [CA SiteMinder® Web Agents for IIS only]): C:\Program Files\CA\webagent\win64
Default (Windows 32-bit applications operating on 64-bit systems [Wow64 with CA SiteMinder® Web Agents for IIS only]): C:\Program Files (x86)\webagent\win32
Default (UNIX/Linux installations): /opt/ca/webagent
Adds new logging information to the end of an existing log file instead of rewriting the entire file each time logging is invoked.
Default: No
Specifies a custom character that separates the fields in the trace file.
Default: No default
Example: |
Specifies (in megabytes) the maximum size of a trace file. The Web Agent creates a new file when this limit is reached.
Default: 0 (a new log file is not created)
Example: 20 (MB)
Specifies how the trace file displays the messages. Choose one of the following options:
Default: default (square brackets)
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.
Default: Yes
Detailed information about the Web Agent connections will be collected.
Note: For CA SiteMinder® 12.52, the BusyHandleCount and FreeHandleCount attributes are not used.
|
Copyright © 2013 CA.
All rights reserved.
|
|