Chapter 8: Configuring the Policy Server Profiler
This section contains the following topics:
Profiler Overview (see page 75)
Configure the Policy Server Profiler (see page 75)
Manually Roll Over the Profiler Trace Log File (see page 79)
Profiler Overview
The Policy Server Profiler allows you to trace internal Policy Server diagnostics and processing functions.
You configure the Policy Server Profiler from the Management Console Profiler tab.
More information:
Management Console--Profiler Tab Fields and Controls (see page 172)
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, even if you are logged into 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.
Configure the Policy Server Profiler
76 Policy Server Management Guide
■ 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
More information:
Management Console--Profiler Tab Fields and Controls (see page 172)
Change Profiler Settings
You can specify which components and data fields will be included in Policy Server tracing, and you can apply filters to tracing output so that the profiler only captures specific values for a given component or data field.
Configure the Policy Server Profiler
Chapter 8: Configuring the Policy Server Profiler 77 To configure profiler settings
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, even if you are logged into 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, choose 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 options for general, broad scope tracing.
authentication_trace.template
Provides options for tracing user authentications.
authorization_trace.template.txt
Provides options for tracing user authorizations.
You can use Profiler templates as a starting point for Profiler configuration. Once a template has been loaded, you can manually modify the components and data fields that it specifies as well as apply data filters.
5. Review/configure trace options by doing one or more of the following:
■ Select Components--Specify which components--actions executed by the Policy Server--to trace on the Components tab.
■ Select Data Fields--Specify which data fields--actual pieces of data used by the Policy Server to complete its tasks--to trace on the Data tab.
■ Add Filters--Specify data filters that will 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.
Configure the Policy Server Profiler
78 Policy Server Management Guide
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.
More information:
Policy Server Profiler Dialog Box (see page 175) Policy Server Profiler--Components Tab (see page 177) Policy Server Profiler--Data Tab (see page 177) Policy Server Profiler Dialog--Filters Tab (see page 181)
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
Chapter 8: Configuring the Policy Server Profiler 79
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. For more information, see the release notes for your SiteMinder component.
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.
Manually Roll Over the Profiler Trace Log File
80 Policy Server Management Guide
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.