Federation Guides › Legacy Federation Guide › Legacy Federation Trace Logging

Legacy Federation Trace Logging

This section contains the following topics:

Trace Logging

Flush FWS Cache for Trace Logs

Log Messages for the Fed_Client Component

Log Messages for the Fed_Server Component

Update FWS Data in the Logs

Simplify Logging with Trace Configuration Templates

Trace Logging

The Web Agent trace logging facility and the Policy Server Profiler enable CA SiteMinder® to monitor the performance of the Web Agent and Policy Server. These logging mechanisms provide comprehensive information about CA SiteMinder® processes so you can analyze the performance and troubleshoot the issues.

For legacy federation, several logging components are available to collect trace messages about federated communication. Trace messages provide detailed information about program operation for tracing, debugging, or both. Trace messages are ordinarily turned off during normal operation. You can enable them to extract in-depth information in addition to the trace message itself. For example, you can look at the FWSTrace.log to see the SAML assertion that CA SiteMinder® generates or to collect the name of the current user.

The collected trace messages are written to a trace log. The FWSTrace.log is located in the directory web_agent_home/log.

Note: For Web Agents on IIS 6.0 servers, log files are created only after the first user request has been submitted. To verify your configuration in the log file, a user has to submit a request.

You can establish trace logs at the Web Agent and the Policy Server to monitor CA SiteMinder® operation.

Flush FWS Cache for Trace Logs

If you modify the federation configuration at the asserting or relying party, flush the Federation Web Services cache for the changes to appear in the trace logs. An example of modifying the configuration is to enable or disable a SAML binding.

To flush the cache

1. Log on to the Administrative UI.
2. Select Administration, Policy Server

   The Cache Management dialog opens.

3. Click Flush All in the All Caches section.
4. Click Close.

All caches are now cleared.

Log Messages for the Fed_Client Component

The Web Agent Option Pack installs the Federation Web Services (FWS) application. The FWS application represents the federation client. The component that controls the trace messages and monitors FWS activity is the Fed_Client component.

FWS uses the common tracing facility that the Web Agent uses to log trace messages. The following files set up trace logging:

trace configuration file

Specifies the configuration file that determines which components and events FWS monitors. The default file is fwstrace.conf.

trace log file

Specifies the output file for all the logged messages. You provide a name and the location for this file in the Web Agent configuration file.

Web Agent Configuration File or Agent Configuration Object

Contains the logging parameters that enable logging and format the log. This file does not define message content.

The Fed_Client component includes the following sub components:

single sign-on

Monitors single sign-on activity.

single logout

Monitors requests for single logout.

discovery profile

Monitors the identity provider discovery profile activity.

administration

Watches administration-related messages.

request

Monitors request and authentication activity.

general

Monitors activity that other subcomponents are not monitoring.

configuration

Monitors SAML 2.0 Service Provider configuration messages.

Configure FWS Trace Logging

To collect trace messages for the Federation Web Services application, configure the FWS trace logging.

Follow these steps:

1. Do one of the following tasks:
   • Make a copy of the default template, FWSTrace.conf and modify the file to include only the data you want to monitor.
   • Copy one of the preconfigured templates and assign a new name to it.

   Note: Do not edit the template directly.

2. Open the LoggerConfig.properties file in the directory web_agent_home/affwebservices/WEB-INF/classes, and set the following parameters:
   • Set TracingOn to Yes. This option instructs the trace facility to write messages to a file.
   • Set the TraceFileName parameter to the full path of the trace log file. The default location is in web_agent_home/config/FWSTrace.log.
   • Set the TraceConfigFile parameter to the full path of the trace configuration file, either the default template, FWSTrace.conf or another template. Templates can be found at web_agent_home/config.
3. Optionally, you can format the trace log file, the file that contains the log output. The following parameters are the Web Agent configuration parameters that dictate the format of the trace log file:
   • TraceRollover
   • TraceSize
   • TraceCount
   • TraceFormat
   • TraceDelim

   The LoggerConfig.properties file contains descriptions of all these settings.

Log Messages for the Fed_Server Component

The component that controls the trace messages for federation services at the Policy Server is the Fed_Server component. This component monitors activity for the assertion generator and the SAML authentication scheme. For example, you can view the generated assertion in the smtracedefault.log file.

To configure logging at the Policy Server, use the Policy Server Profiler. The Profiler lets you specify components for trace logging, which include.

For more information about using the profiler, see the CA SiteMinder® Policy Server Administration Guide.

Federation Services Trace Logging (smtracedefault.log)

The profiler is the Policy Server facility for logging. You can use the profiler to collect trace messages for federation services and write them to the smtracedefault.log file.

The component that controls the trace messages for federation services at the Policy Server is the Fed_Server component.

The Policy Server Profiler allows you to trace internal Policy Server diagnostics and processing functions.

Follow these steps:

1. Start the Policy Server Management Console.

   Important! If you are accessing this graphical user interface on Windows Server 2008, open the shortcut with Administrator permissions. Use Administrator permissions even if you are logged in to the system as an Administrator. For more information, see the release notes for your CA SiteMinder® component.

2. Click the Profiler tab.
3. Set the Enable Profiling option to enable profiling.
4. To select configuration settings for the Profiler, do one of the following:
   • Accept the Profiler settings specified by the default smtracedefault.txt file presented in the Configuration File drop-down list.
   • Select another configuration file that has already been selected during this management session from the Configuration File drop-down list.
   • Click the Browse button to select another configuration file.
5. To change the Profiler settings stored in a Profiler configuration file and save them in the same or a new file, click the Configure Settings button to open the Policy Server Profiler dialog.
6. Adjust the settings presented in the Output group box to specify the output format for information generated by the Policy Server Profiler.
7. Click Apply to save your changes.

Notes:

Changes to the Profiler settings take effect automatically. However, if you restart the Policy Server, a new output file (if the Profiler is configured for file output) is created. The existing Profiler output file is automatically saved with a version number. For example:

smtracedefault.log.1

If changes to the Logging or Tracing facility settings are not related to the Profiler output file, for example, enabling/disabling the console logging on Windows, the existing file is appended with new output without saving a version of the file.

By default The Policy Server retains up to ten output files (the current file and nine backup files). Older files are replaced automatically with newer files when the ten file limit is reached. You can change the number of files to retain by configuring the TraceFilesToKeep DWORD registry setting to the required decimal value. The TraceFilesToKeep registry setting must be created in the following registry location:

HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Netegrity\SiteMinder\CurrentVersion\
LogConfig\TraceFilesToKeep

The Profiler tab has a "Buffered Tracing" option, which is set by default to improve Policy Server performance. This option is on Solaris systems only.

Update FWS Data in the Logs

If you modify any part of the federation configuration, flush the Federation Web Services cache for the changes to appear in the trace logs.

Note: A brief delay can occur from when the changes are made and when Federation Web Services receives the information.

To flush the cache

1. Log in to the Administrative UI.
2. Select Administration, Policy Server, Cache Management.

   The Cache Management page displays.

3. Click Flush All in the All Caches section of the page.
4. Click Close

Simplify Logging with Trace Configuration Templates

To make the task of collecting tracing data simpler, a series of preconfigured templates are installed with the Policy Server and the Web Agent Option Pack. You can use these templates instead of creating your own trace configuration file to collect the data that gets written to a trace log.

Trace Logging Templates for FWS

The following templates are available for Federation Web Services:

All these templates include the Fed_Client component and subcomponents for the specific data being tracked. Look at each template to see the exact contents. The templates are located in web_agent_home/config.

To use a template for trace logging

1. Make a copy of the template you want to use and rename the copy.

   Note: Do not edit the template directly.

2. Open the Agent configuration file or Agent configuration Object.
3. Set the TraceFile parameter to Yes.
4. Set the TraceFileName parameter to the full path to the trace log file. This file contains the log output.
5. Set the TraceConfigFile parameter to the full path to the newly named template file.
6. Format the trace log file. The following parameters are the Web Agent configuration parameters that dictate the format of the trace log file:
   • TraceAppend
   • TraceFormat
   • TraceDelimiter
   • TraceFileSize
   • LogLocalTime

   For descriptions of each logging parameter, see the Web Agent Configuration Guide.

Note: Web Agents on IIS 6.0 and Apache 2.0 servers do not support dynamic configuration of log parameters that are set locally in the Agent configuration file. Consequently, when you modify a parameter, the change takes effect only after the Agent is restarted. If you configure the log parameters in an Agent configuration object, these log settings can be stored and updated dynamically.

FWS Template Sample

The following text is an excerpt from the FWS_SLOTrace.conf template. Most of the file contains comments and instructions on how to use the file, the command syntax, and the available subcomponents for the Fed_Client component.

The excerpt shows the component, Fed_Client and the subcomponents (Single_Logout and Configuration) that are monitored. The excerpt also shows the specific data fields that indicate the required contents of each message (Date, Time, Pid, Tid, TransactionId, SrcFile, Function, Message).

components: Fed_Client/Single_Logout, Fed_Client/Configuration
data: Date, Time, Pid, Tid, TransactionID, SrcFile, Function, Message

Trace Logging Templates for the IdP and SP

To make the task of collecting tracing data simpler, a series of preconfigured templates are installed with the Policy Server. You can use these templates instead of creating your own trace configuration file to collect the data that gets written to a trace log.

The following templates are available for trace logging related to the Identity Provider and the Service Provider, such as assertion generation or SAML authentication.

Look at each template to see the exact contents. The templates are located in siteminder_home/config/profiler_templates.

Service Provider Template Sample

The following text is the samlsp_trace.template file.

components: Server/Policy_Server_General, IsProtected/Resource_Protection, Login_Logout/Authentication, Login_Logout/Policy_Evaluation, Login_Logout/Active_Expression, Login_Logout/Session_Management, IsAuthorized/Policy_Evaluation, JavaAPI, Fed_Server/Auth_Scheme, Fed_Server/Configuration
data: Date, Time, Tid, TransactionID, SrcFile, Function, Domain, Resource, Action, User, Message

For legacy federation, it includes the Fed_Server component along with the subcomponents Auth_Scheme and Configuration.

The data fields that indicate the required contents of each message are:

Date, Time, Tid, TransactionId, SrcFile, Function, Domain, Resource, Action User, and Message.

Identity Provider Profiler Sample

At the Identity Provider, the Profiler tab of the Policy Server Management Console specifies a template in the Configuration File field. The following text is a sample entry for the Configuration File field:

c:\program files\ca\siteminder\config\profile_templates\samlidp_template.trace

For more information about using the Profiler, see the Policy Server Administration Guide.