Policy Server Guides › Policy Server Administration Guide › Configuring the Policy Server Profiler

Configuring the Policy Server Profiler

This section contains the following topics:

Configure the Policy Server Profiler

Manually Roll Over the Profiler Trace Log File

Configure the Policy Server Profiler

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

To configure the profiler

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 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\Netegrity\SiteMinder\CurrentVersion\
LogConfig\TraceFilesToKeep

Change Profiler Settings

You can specify which components and data fields must be included in Policy Server tracing. You can then apply the filters to tracing output so that the profiler only captures specific values for a given component or data field.

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 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. Click the Configure Settings button.

   Note: This button is only active when you select the Enable Profiling check box.

   The Policy Server Profiler dialog opens.

4. Optionally, select a Profiler template file that contains a predefined set of components and data fields appropriate for a particular tracing task from the Template drop down list:

   general_trace.template

   Provides the options for general, broad scope tracing.

   authentication_trace.template

   Provides the options for tracing user authentications.

   authorization_trace.template

   Provides the options for tracing user authorizations.

   samlidp_trace.template

   Provides the options for tracing the SAML Identity Provider assertions.

   samlsp_trace.template

   Provides the options for tracing SAML Service Provider Authentication.

   You can use the Profiler templates as a starting point for the Profiler configuration. Once a template has been loaded, you can manually modify the components and data fields that it specifies and apply the data filters.

5. Review/configure trace options by doing one or more of the following:
   • Select Components--Specify which components--actions that are executed by the Policy Server--to trace on the Components tab.
   • Select Data Fields--Specify which data fields--actual pieces of data that is used by the Policy Server to complete its tasks--to trace on the Data tab.
   • Add Filters--Specify data filters that include or exclude information from the tracing process on the Filters tab.
6. To save your new settings, do one of the following:
   • To save the settings in the currently selected configuration file, click OK.
   • To save the settings to a new configuration file, select File, Save As and specify a new text file.
7. Select File, Close to close the profiler and return to the Policy Server Management Console.
8. Select the Browse button to the right of the Configuration File field.

Avoid Profiler Console Output Problems on Windows

On Windows Policy Servers, you should disable QuickEdit Mode and Insert Mode to avoid problems when you enable console debugging. QuickEdit Mode and Insert Mode are features that you can enable from a Windows command prompt window.

To Disable QuickEdit Mode and Insert Mode

1. Access the command prompt window.
2. Right click in the window's title bar to display the pull-down menu.
3. Select Properties.
4. If QuickEdit Mode and Insert Mode are checked, deselect them.
5. Click OK.

Configure Profiler Trace File Retention Policy

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 should be created in the following registry location:

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

Manually Roll Over the Profiler Trace Log File

The Policy Server allows you to manually rollover the Policy Server Profiler trace log file using the smpolicysrv command.

Important! Before running a SiteMinder utility or executable on Windows Server 2008, open the command line window with administrator permissions. Open the command line window this way, even if your account has administrator privileges.

To start trace logging to a file, run the following command:

smpolicysrv -starttrace

This command starts logging to a trace file and does not affect trace logging to the console. It issues an error if the Policy Server is not running.

If the Policy Server is already logging trace data, running the –starttrace command causes the Policy server to rename the current trace file with a time stamp appended to the name in the form: file_name.YYYYMMDD_HHmmss.extension and create a new trace file with the original name. For example, if the trace file name in Policy Server Management Console’s Profiler tab is C:\temp\smtrace.log, the Policy Server generates a new file and saves the old one as c:\temp\smtrace.20051007_121807.log. The time stamp indicates that the Policy Server created the file on October 7, 2005 at 12:18 pm.

If you have not enabled the tracing of a file feature using the Policy Server Management Console’s Profiler tab, running this command does not do anything.

To stop trace logging to a file, run the following command:

smpolicysrv -stoptrace

This command stops logging to a file and does not affect trace logging to the console. It issues an error if the Policy Server is not running.

Note: On Windows systems, do not run the smpolicysrv command from a remote desktop or Terminal Services window. The smpolicysrv command depends on inter-process communications that do not work if you run the smpolicysrv process from a remote desktop or Terminal Services window.

Dynamic Trace File Rollover at Specified Intervals

You can also write a script to cause a trace file to be rolled over at a specified time interval. For example, to create a new trace file every hour, write a script similar to the following:

smpolicysrv -starttrace
repeat forever
wait 1 hour
smpolicysrv -starttrace
end repeat

This is similar to the time-based rollover option on the Policy Server Management Console’s Logs tab.