Federation Guides › Partnership Federation Guide › Log Files that Aid Troubleshooting

Log Files that Aid Troubleshooting

This section contains the following topics:

Federation Trace Logging

Transaction IDs to Aid Federation Troubleshooting

Federation Services Trace Logging (smtracedefault.log)

Federation Web Services Trace Logging (FWSTrace.log)

Federation Trace Logging

The Federation Web Services (FWS) trace logging facility and the Policy Server Profiler monitor the performance of the federation services. These logging mechanisms provide information about federated operation so you can analyze the system performance and can troubleshoot issues.

Enable trace logging where the Web Agent Option Pack and the Policy Server are installed to extract in-depth information about federation processes. For example, you can look at the FWSTrace.log to see the generated SAML assertion or collect the name of the current user.

Note: Trace messages are ordinarily turned off during normal operation because they can impact performance.

The collected trace messages are written to two trace logs:

• FWSTrace.log

  The FWSTrace.log is located in the /log directory of the web server or application server where the web agent option pack is installed or deployed.

  Web server:

  webagent/log

  webagent_optionpack/log

  Application server

  default_deployment_directory/log

  SPS federation gateway:

  sps_home/secure-proxy/proxy-engine/logs

• smtracedefault.log

  The smtracedefault.log is located in the directory siteminder_home/log.

  siteminder_home represents the installation directory of the product.

In the FWSTrace.log and the smtracedefault.log, there are checkpoint log messages that indicate what is happening during a transaction. For example:

[07/30/2013][11:34:44][4260][5824][1181adbb-993f775c-33ba08f3-76b52f3b-3d2280cd-4ae][SSO.java][processRequest][Reading SAML 2.0 SP Configuration [CHECKPOINT = SSOSAML2_SPCONFREAD_REQ]

You can search on these checkpoint messages to follow some of the processes occurring during a transaction.

In addition to the checkpoint messages, you can follow transaction IDs in the log to follow a transaction. If a transaction fails, the checkpoint messages and transaction IDs can help you determine the specific problem.

Transaction IDs to Aid Federation Troubleshooting

Troubleshooting a federated transaction is difficult when many transactions are logged in one file. To follow a single transaction in a trace log, use the SAML transaction ID. When a federation call occurs, the FWS application first generates a SAML Transaction ID. The SAML Transaction ID is generated only once. This unique SAML transaction ID can map to multiple transaction IDs

For example, you can see the following message in the fwstrace.log for a SAML 2.0 POST transaction. Note the line in bold that shows the mapping of the two transaction IDs.

[08/01/2013][17:33:54][2292][1884][1c2d7650-b006e46a-ed071f41-bbbede33-fe78e2dd-38d][SSO.java][processAuthentication][SAMLTransactionID 2aaf90ec-fdef4897-0ef49d91-63d4031d-f508a3e9-12 maps to TransactionID: 1c2d7650-b006e46a-ed071f41-bbbede33-fe78e2dd-38d.]

The CA SiteMinder® Federation system generates a new SAMLTransactionID only if it is acting as the asserting party. These specific activities are:

• When Federation Web Services redirects the browser to the authentication URL to establish a session.
• For the following HTTP-Artifact single sign-on transactions:
  • When the asserting party sends the artifact to the relying party.
  • When the asserting party resolves the artifact.
• When the user is redirected to the Identity Discovery profile URL.
• During single logout at the asserting party.

At the relying party, there exists a request ID, which can be traced easily through the log files. The request ID makes it unnecessary for the CA SiteMinder® Federation system to generate a SAMLTransactionID at the relying party.

For each unique SAML transaction ID, there can be multiple transaction IDs. When a new HTTP transaction occurs, a new transaction ID is generated. This transaction ID is mapped to the single SAML transaction ID. For example, in the trace log you can see the following entries:

SamlTransactionID ["xyz"] maps to TransationID["123"]
["123"] HTTP operation
["123"] HTTP operation

A new transaction ID "456" is generated:

SamlTransactionID["xyz"] Maps to Transactionid["456"]
["456"] <some operation>
["456"] <some operation>

Transaction IDs are placed in the fwstrace.log and the smtracedefault.log. The same set of transaction IDs for a single transaction is written to each of these logs. The trail of IDs in these logs enables you to follow a transaction. If there is a failure, the IDs help you determine which event failed for a transaction.

How To Follow a Single Transaction in a Log

To monitor a transaction, you can follow the two types of transaction IDs in the FWSTrace.log or smtracedefault.log. If there is a failure, looking at the IDs can help you determine the failure point.

To follow a transaction in a log, use one or more of the following methods:

• Open the trace file in a text editor and search on the string SAMLTransactionID (no spaces) or search for a sepcific SAMLTransactionID. This collection of entries in the log provides a view of the entire end-to-end transaction. You can see how far a transaction proceeded.
• Follow the transaction ID in the log file. The transaction ID represents HTTP transactions. Multiple transaction IDs can be associated with a single SAML Transaction ID. A failed transaction displays the transaction ID in the browser. To search the FWSTrace.log and smtracedefault log for the checkpoint error messages, use the displayed transaction ID.
• Parse the log files with a tool that searches files. On UNIX and Windows platforms, you can use a tool like the grep command. The grep command can stream through raw data, line by line, without your having to load a large text file into a text editor.

  Example:

  [usr@rhel632 etc]# more fwstrace.log| grep checkpoint
  [CHECKPOINT = SSOSAML2_SPCONFFROMPS_REQ]]
  [CHECKPOINT = SSOSAML2_SPCONFREAD_REQ]]
  [CHECKPOINT = SSOSAML2_SPCONFFROMCACHE_REQ]]
  [CHECKPOINT = SSOSAML2_SESSIONCOOKIEVALIDATE_REQ]]
  

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.

   Note: For more information about the settings and controls on this tab, click Help, Management Console Help.

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

Federation Web Services Trace Logging (FWSTrace.log)

To simplify the task of collecting tracing data simpler, a series of preconfigured templates are installed with the Web Agent Option Pack. You can use these templates instead of creating your own trace configuration file to collect the data.

The following templates are available:

All the FWS templates include the Fed_Client component and subcomponents for the specific data being tracked. To see the exact contents, open each template.

Follow these steps:

1. Navigate to the template directory in web_agent or web_agent_option_pack_home/config.
2. Make a copy of the template, rename it.
3. (Optional) Modify the template so it includes only the data you want to monitor.

   Note: Do not edit the template directly.

4. Save the new template.

The templates determine the federation components that the federation system monitors. To enable trace logging and format how the data appears in the log file, modify the Logger.Config properties file.

Follow these steps:

1. Navigate to web_agent or webagent_optionpack_home/affwebservices/WEB-INF/classes.
2. Open the LoggerConfig.properties file. The LoggerConfig.properties file contains descriptions of all the settings.
3. Set the TracingOn setting to Yes. This option instructs the trace facility to write messages to the log file.
4. Set the TraceFileName setting to the full path of the log file. The default location is in web_agent or webagent_optionpack_home/config/FWSTrace.log.

   Note: You can rename the log file. FWSTrace.log is the default name.

5. Set the TraceConfigFile setting to the full path of the trace configuration file. This file can be the default template, one of the other preconfigured templates, or your own configuration file. Regardless of which template you specify, all output is written to the log file you specify in the TraceFileName setting.

   Specify only one template. All the templates reside in the directory web_agent or web_agent_option_pack_home/config.

6. Optionally, modify how the information in the trace log output file is displayed. The following settings dictate the format of the log file:
   • TraceRollover
   • TraceSize
   • TraceCount
   • TraceFormat
   • TraceDelim

FWS Template Sample(shared)

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