How to Set Up Trace Logging

Contents
sm1252sp1
Contents
To set up trace logging, use the following process:
  1. Set up and Enable Trace logging.
  2. Determine what you want to record in the trace log by reviewing the following lists:
    • Trace Log Components and Subcomponents
    • Trace Message Data Fields
    • Data Field Filters
  3. Duplicate the default Trace Configuration File.
  4. Modify the duplicate file to include the items you want to record.
  5. Restart the agent.
Configure Trace Logging
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
  1. Locate the WebAgentTrace.conf file on your web server. Duplicate the file.
    If you are running the
    CA Single Sign-On
    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.
  2. Open your Agent Configuration Object or local configuration file.
  3. Set the TraceFile 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.
  4. Specify the full path to the trace log files in following parameters:
    • TraceFileName
      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
    • TraceFileName32
      Specifies the full path to the trace file for the 
      CA Single Sign-On
       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 Single Sign-On
       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.
       
  5. Specify the full path to the duplicate copies of WebAgentTrace.conf file (you created in Step 1) in the following parameters:
    • TraceConfigFile
      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
    • TraceConfigFile32
      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 Single Sign-On
       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.
       
    This file is not used until the web server is restarted.
  6. Define the format of the information in your trace log file by setting the following parameters in your Agent Configuration Object or local configuration file:
    • TraceAppend
      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
    • TraceFormat
      Specifies how the trace file displays the messages. Choose 
      one 
      of the following options:
      • default—uses square brackets [] to enclose the fields.
      • fixed—uses fields with a fixed width.
      • delim—uses a character of your choice to delimit the fields.
      • xml—uses XML-like tags. A DTD or style sheet is 
        not 
        provided with the Web Agent.
      Default:
       default (square brackets)
    • TraceDelimiter
      Specifies a custom character that separates the fields in the trace file.
      Default:
       No default
      Example:
       |
    • TraceFileSize
      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)
    • LogLocalTime
      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
  7. Edit the WebAgentTrace.conf file to have Web Agent monitor the activities you want.
    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.
    : 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.
  8. Restart the web server so the Web Agent uses the new trace configuration file.
Trace Log Components and Subcomponents
The
CA Single Sign-On
Agent can monitor specific
CA Single Sign-On
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:
  • AgentFramework
    Records all Agent framework messages. (Applies only to framework agents.) The following subcomponents are available:
    • Administration
    • Filter
    • HighLevelAgent
    • LowLevelAgent
    • LowLevelAgentWP
  • AffiliateAgent
    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:
    • RequestProcessing
  • SAMLAgent
    Web Agent messages related to the SAML Affiliate Agent. (Applies only to framework agents.) The following subcomponent is available:
    • RequestProcessing
  • WebAgent
    Records all Web Agent log messages. Applies to all Agents
    except
    IIS 6.0 or Apache 2.0 Agents. The following subcomponents are available:
    • AgentCore
    • Cache
    • authentication
    • Responses
    • Management
    • SSO
    • Filter
  • Agent_Functions
    Records all Agent API messages. The following subcomponents are available:
    • Init
    • UnInit
    • IsProtected
    • Login
    • ChangePassword
    • Validate
    • Logout
    • Authorize
    • Audit
    • FreeAttributes
    • UpdateAttributes
    • GetSessionVariables
    • SetSessionVariables
    • DeleteSessionVariables
    • Tunnel
    • GetConfig
    • DoManagement
  • Agent_Con_Manager
    Records messages related to internal processing of the Agent API. The following subcomponents are available:
    • RequestHandler
    • Cluster
    • Server
    • WaitQueue
    • Management
    • Statistics
Trace Message Data Fields
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:
  • Message
    Includes the actual trace message
  • SrcFile
    Includes the source file and line number of the trace message
  • Pid
    Includes the process ID
  • Tid
    Includes the thread ID
  • Date
    Includes the date
  • Time
    Includes the time
  • PreciseTime
    Includes the time, including milliseconds
  • Function
    Includes the function in the code containing the trace message
  • User
    Includes the name of the user
  • Domain
    Includes the
    CA Single Sign-On
    domain
  • Realm
    Includes the
    CA Single Sign-On
    realm
  • AgentName
    Includes the Agent name being used
  • TransactionID
    Includes the transaction ID
  • DomainOID
    Includes the
    CA Single Sign-On
    domain OID
  • IPAddr
    Includes the client IP address
  • RequestIPAddr
    Includes the trace file displays the IP of the server where Agent is present
  • IPPort
    Includes the client IP port
  • CertSerial
    Includes the certificate serial number
  • SubjectDN
    Includes the subject DN of the certificate
  • IssuerDN
    Includes the Issuer DN of the certificate
  • SessionSpec
    Includes the
    CA Single Sign-On
    session spec
  • SessionID
    Includes the
    CA Single Sign-On
    session ID
  • UserDN
    Includes the User DN
  • Resource
    Includes the requested resource
  • Action
    Includes the requested action
  • RealmOID
    Includes the realm OID
  • ResponseTime
    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].
Trace Message Data Field Filters
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:
  • == (exact match)
  • != (does not equal)
The filters use boolean logic as shown in the following examples:
Action:!=get (all actions except get)
Resource:==/html (all resources ending in /html)
Determine the Content of the Trace Log
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:
  • Entries are case-sensitive.
    When you specify a component, data field, or filter, the values must match exactly the options in the WebAgentTrace.conf file instructions.
  • Uncomment the configuration settings lines.
  • If you modify the WebAgentTrace.conf file before installing a new agent over an existing agent, the file is overwritten. Rename or back up the file first. After the installation, you can integrate your changes into the new file.
Follow these steps:
  1. Open the WebAgentTrace.conf file.
    We recommend duplicating the original file and changing the copy. Modifying the copy preserves the default settings.
  2. Add components and subcomponents using the following steps:
    1. Find the section that matches your type of agent. For example, if you have an Apache 2.0 Agent that is installed on your server, look for a line resembling the following example:
      # For Apache 2.0, Apache 2.2, IIS 7.0 and SunOne Web Agents
    2. Locate the following line in that section:
      #components:
    3. Uncomment the line. Then add the component names that you want after the colon. Separate multiple components commas as shown in the following example:
      components: AgentFramework, HTTPAgent
    4. (Optional) Follow the component name with the name of a subcomponent you want. Separate the subcomponent name with a slash as shown in the following example:
      components: AgentFramework/Administration
  3. Add data fields and filters using the following steps:
    1. Locate the following line in the appropriate section:
      #data:
    2. Uncomment the line. Then add the data fields that you want after the colon. Separate multiple data fields with commas as shown in the following example:
      data: Date, Time, Pid, Tid, TransactionID, Function, Message, IPAddr
    3. (Optional) Add filters to your data fields by following the data field with a colon, the Boolean operator and the value you want. The values you specify for the filters must match exactly. The following example shows a filter which logs activities for a specific IP address:
      IPAddr:==127.0.0.1
      If there is more than one filter, add each filter on a separate line in the file.
  4. Save your changes and close the file.
  5. Restart the web server to apply your changes.
    The content of the trace log has been determined.
Limit the Number of Trace Log Files Saved
You can limit the number of trace logs that a
CA Single Sign-On
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:
TraceFilesToKeep
Specifies the number of
CA Single Sign-On
agent trace log files that are kept. New trace logs are created in the following situations:
  • When the agent starts.
  • When the size limit of the trace log (specified by the value of the TraceFileSize parameter) is reached.
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:
  1. Archive or delete any existing trace logs from your system.
  2. Set the value of the TraceAppend parameter to no.
  3. Change the value of the TraceFilesToKeep parameter to the number of trace logs that you want to keep.
 
Collect Detailed Agent Connection Data with an Agent Connection Manager Trace Log
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
  1. Open your Agent Configuration object or local configuration file.
  2. Set the value of the TraceFile parameter to yes.
    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.
  3. Specify the full path to the trace log file for your Agent Connection Data in the TraceFileName parameter. This is the file that contains the trace log output.
  4. Set the value of the TraceConfigFile parameter to the full path of the following file:
    web_agent_home
    /config/AgentConMgr.conf
    • web_agent_home
      Indicates the directory where the
      CA Single Sign-On
      Agent is installed.
      Default
      (Windows 32-bit installations of
      CA Single Sign-On
      Web Agents only): C:\Program Files\CA\webagent
      Default
      (Windows 64-bit installations [
      CA Single Sign-On
      Web Agents for IIS only]): C:\Program Files\CA\webagent\win64
      Default
      (Windows 32-bit applications operating on 64-bit systems [Wow64 with
      CA Single Sign-On
      Web Agents for IIS only]): C:\Program Files (x86)\webagent\win32
      Default
      (UNIX/Linux installations): /opt/ca/webagent
  5. Define the format the trace log file for your Agent Connection Data by setting the following parameters:
    • TraceAppend
      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
    • TraceDelimiter
      Specifies a custom character that separates the fields in the trace file.
      Default:
       No default
      Example:
       |
    • TraceFileSize
      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)
    • TraceFormat
      Specifies how the trace file displays the messages. Choose 
      one 
      of the following options:
      • default—uses square brackets [] to enclose the fields.
      • fixed—uses fields with a fixed width.
      • delim—uses a character of your choice to delimit the fields.
      • xml—uses XML-like tags. A DTD or style sheet is 
        not 
        provided with the Web Agent.
      Default:
       default (square brackets)
    • LogLocalTime
      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
  6. Restart your web server so the new settings take effect.
    Detailed information about the Web Agent connections will be collected.
    For
    CA Single Sign-On
    12.52, the BusyHandleCount and FreeHandleCount attributes are not used.