Previous Topic: Error Logs and Trace LogsNext Topic: Troubleshooting Agent Configuration

Web Agent Guides › Web Agent Configuration Guide › Logging and Tracing › How to Set Up Trace Logging

How to Set Up Trace Logging

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:
  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.

    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.

  2. Open your Agent Configuration Object or local configuration file.
  3. Set 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 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 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.

  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 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.

  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

    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.

    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.

    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.

  8. Restart the web server so the Web Agent uses the new trace configuration file.
Trace Log Components and Subcomponents

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:

AgentFramework

Records all Agent framework messages. (Applies only to framework agents.) The following subcomponents are available:

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:

SAMLAgent

Web Agent messages related to the SAML Affiliate Agent. (Applies only to framework agents.) The following subcomponent is available:

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:

Agent_Functions

Records all Agent API messages. The following subcomponents are available:

Agent_Con_Manager

Records messages related to internal processing of the Agent API. The following subcomponents are available:

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 SiteMinder® domain

Realm

Includes the CA SiteMinder® realm

AgentName

Includes the Agent name being used

TransactionID

Includes the transaction ID

DomainOID

Includes the CA SiteMinder® 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 SiteMinder® session spec

SessionID

Includes the CA SiteMinder® 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:

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:

Follow these steps:

  1. Open the WebAgentTrace.conf file.

    Note: 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: 
      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.

  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 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:

TraceFilesToKeep

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:

  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 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

  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.

    Note: For CA SiteMinder® 12.51, the BusyHandleCount and FreeHandleCount attributes are not used.