Contents
Forefront UAG Tracing .................................................................................................................... 2
Server and client-side tracing....................................................................................................... 2
Configuring and running tracing ................................................................................................... 2
Obtaining trace symbols ........................................................................................................... 3
Configuring trace settings ......................................................................................................... 3
To configure trace settings from the command line .............................................................. 3
Command line examples ....................................................................................................... 4
To configure trace settings from the tracing console ............................................................ 4
To configure additional Forefront UAG settings for specific components ............................. 8
Running tracing ......................................................................................................................... 8
To run tracing from the command line................................................................................... 8
Command line examples ..................................................................................................... 10
To run tracing from the tracing console ............................................................................... 10
Converting the binary trace files ............................................................................................. 10
To convert trace files to text format from the command line ............................................... 10
To convert trace files to text format using the trace console ............................................... 11
Forefront UAG Tracing
Forefront UAG 2010 includes a trace mechanism that is based on Event Tracing for Windows
(ETW); a high-performance, low overhead, scalable tracing mechanism that is provided by the
Windows operating system. For more information, see Improve Debugging and Performance
Tuning with ETW (http://msdn.microsoft.com/en-us/magazine/cc163437.aspx).
Forefront UAG tracing provides detailed failure and debugging information in a binary format. This
binary information can be converted into a readable text format. For troubleshooting complex
issues, you can use tracing together with Microsoft’s Customer and Support Services (CSS).
Server and client-side tracing
Forefront UAG provides tracing on both the Forefront UAG server, and on endpoint devices
connecting to resources published via Forefront UAG, as follows:


On the Forefront UAG server, tracing is available by default following installation.
When endpoint devices connect to a Forefront UAG site or portal, Forefront UAG enables
client-side tracing by installing the Forefront UAG Client Trace component. The
component is installed under the following conditions:
o The user agrees to install Forefront UAG client components.
o The user is logged on to the endpoint device with permissions that allow the
installation of client components.
o Browser settings allow the installation of client components.
Both server-side and client-side tracing can be configured and run via the command line, or using
a user interface tool.
Default trace settings are as follows:
1. Tracing level is enabled for all components, and set to a verbosity level of “Error”.
2. By default, trace results are saved to a binary file located in
%WINDIR%\debug\Forefront_UAG.bin.
3. The binary output file has a size limit of 400 MB. When the size limit is reached, older trace
messages are deleted, so that new trace messages can be added.
4. You cannot create more than one trace file simultaneously.
Configuring and running tracing
Configuring and running tracing consists of the following steps:
1. Obtaining trace symbols—In order to convert binary trace files to a readable format, you must
obtain the tracing symbols (.tmf files). If you want to send the trace file in a binary format to
CSS, the tracing symbols are not required.
2
2. Configuring trace settings—You can configure trace settings from the command line, or using
the tracing graphical user interface.
3. Running tracing—You start tracing from the command line or tracing console. After
reproducing the required scenario, you stop tracing.
4. Converting the binary trace files—If you want to analyze the traces yourself instead of
sending to CSS, convert the binary files to readable format using the tracing symbols.
Obtaining trace symbols
The tracing symbols are available from the Microsoft Download Center
(http://go.microsoft.com/fwlink/?LinkId=190991).
Configuring trace settings
To configure trace settings from the command line
1. To configure trace settings from the command line, do the following:
a. To configure tracing on the Forefront UAG server, open an elevated command
prompt. Then navigate to the \common\bin\tracing folder (under the Forefront
UAG installation folder).
b. To configure tracing on a client endpoint device, open an elevated command
prompt on the endpoint device. Then navigate to the \Program Files\Microsoft
Forefront UAG\Endpoint Components\3.1.0 folder.
2. At the command prompt, configure trace settings with the commands summarized in the
following table.
Command
Parameters
Details
Trace.cmd /?
None
Provides a full list of commands and
parameters.
Trace.cmd -path
<TraceFormat folder>
Sets an environment variable for the
TraceFormat folder
(%windir%\debug\Forefront_UAG.bin).
This is necessary if you want to use the –
rt or –format command. It must be set
once.
Trace.cmd -change
<module>
Change the trace level per module.
Trace.com -update
[<rt>]
Specifies that the trace level should be
updated for all modules. <rt> specifies
that tracing is in real-time mode. <Level>
<Level>
3
Command
Parameters
Details
specifies the tracing level that you want
to apply.
Command line examples
1. Trace.cmd –path. X:\Sym\TraceFormat. Create an environment variable for the
X:\Sym\TraceFormat folder, in which the tracing symbols are located.
2. Trace.cmd – change ENG warning. Set the ENG component to logging at warning
level.
3. Trace.cmd – update –rt –info. Update real-time logging for all components to info level
To configure trace settings from the tracing console
1. To configure trace settings using the tracing console, do the following:
a. To run tracing on the Forefront UAG server, navigate to \common\bin\tracing
folder (under the Forefront UAG installation folder). Then double-click the
LaunchHTA.vbs file to open the tracing console.
b. To run tracing on an endpoint device, navigate to the Program Files\Microsoft
Forefront UAG\Endpoint Components\3.1.0 folder on the device, and then
double-click the LaunchHTA.vbs file to open the tracing console.
The console appears as follows:
4
5
6
2. In the component Group list, select the required tracing levels for each component.
The components you enable will depend upon where you estimate is the problem .
Note the following:
a. You can select a trace level rather than a component. For example, selecting the
Error column turns on error-level tracing for all components.
b. Selecting a main tracing component automatically selects all sub-components.
c.
It is recommended to enable error level tracing for all components, and warning
and info level tracing for the specific components that you want to investigate.
3. In Trace format search path, specify the location of the path to which you saved the
symbols that you downloaded.
4. In Tracing configuration file, type the name and location to which you want to save
the readable text file. Click Browse to locate an existing file, and then click Load.
5. In RT console colors, specify the text and background colors for real-time tracing
output.
6. In Circular log file, specify the tracing file size limit or disable the circular log file
option. Using the circular log file option, by default the output file size is limited to 400
7
MB. When this limit is reached and new traces need to be added, the circular log file
discards the oldest traces. Usually, you should not need to disable the circular log file
option; if you do, the log file will be set as a sequential file with no size limit.
7. Click Auto enabling tracing on startup to start tracing after a server restart. This is
useful if you want to troubleshoot Forefront UAG services start up, or if you need to
permanently enable tracing.
8. If you have selected Auto enabling tracing on startup, select Backup trace file on
startup if you want to back up the collection of previous traces when the server
restarts. Select Use default file to backup traces to the default location, or select
Use this file and specify an alternate location.
To configure additional Forefront UAG settings for specific components
For server-side tracing, some trace components require you to configure tracing files in Forefront
UAG, before running tracing. These changes are summarized in the following table. After making
the changes, save each file.
Component
File
Line to modify
Internal site
Internalsite\inc\trace.inc
Change trace_on=false to
trace_on=true
Web Monitor
monitor\inc\trace.inc
Change trace_on=false to
trace_on=true
Certified endpoint
enrolment
whalesep\inc\trace.inc
Change trace_on=false to
trace_on=true
Portal
common\conf\trace.ini
At the last line of the file, add the
following lines:
1. [trace\portalwebsite\portalhomepage]
2. *=XHeavy
Running tracing
To run tracing from the command line
1. To run command line tracing, do the following:
a. To run tracing on the Forefront UAG server, open an elevated command prompt, and
navigate to \common\bin\tracing folder (under the Forefront UAG installation folder).
b. To run tracing on an endpoint device, open an elevated command prompt on the
8
endpoint. Then navigate to the Program Files\Microsoft Forefront UAG\Endpoint
Components\3.1.0 folder.
2. At the command prompt, type trace.cmd -start to begin tracing. To start tracing in realtime mode, type trace.cmd –rt.
3. Reproduce the Forefront UAG scenario that you want to troubleshoot.
4. After completing the scenario, type trace.cmd –stop to end tracing.
The following table summarizes the options that can be used when running tracing.
Command
Parameters
Details
Trace.cmd /?
None
Provides a full list of commands and
parameters.
Trace.cmd -start
<Level>
Begin tracing. By default the tracing level
is set to Error. Specify the <Level>
parameter if you want to change the
default setting, as follows:
1. Error (default)—Trace error
messages only.
2. Warning—Trace warning and error
messages (it is recommended to turn
this level on for specific modules).
3. Info—Trace information, warning,
and error messages (it is
recommended to turn this level on for
specific modules).
4. Func—Trace function entries and
exits; information, warning, and error
messages (this level is very verbose
and is not usually required).
5. Func_error—Trace function entry
and exit; and function error
messages (this level is very verbose
and is not usually required).
6. Trace—Trace noise, function entry
and exit; function error, information,
warning, and error messages (this
level is very verbose and is not
usually required).
Trace.cmd -stop
None
End tracing
9
Command
Parameters
Details
Trace.cmd –rt
[<Action>]
Starts tracing in real-time mode. Trace
results are output to a console window.
You do not need to click Stop to flush
trace contents. The –path parameter
must be set first.
[<Level>]
<Action>—Specifies an optional trace
action, including –start to begin tracing
and -stop to end tracing.
<Level>—Specifies the tracing level for
the real-time trace.
Command line examples
1. 2. Trace.cmd –rt –info. Start real-time logging at info level.
3. 4. Trace.cmd – update –rt –info. Update real-time logging for all components to info level.
5. 6. Trace.cmd –stop. End tracing.
To run tracing from the tracing console
1. To run the tracing console tool, do the following:
a. To run tracing on an endpoint device, open an elevated command prompt on the
endpoint. Then navigate to the Program Files\Microsoft Forefront UAG\Endpoint
Components\3.1.0 folder.
b. To run tracing on the Forefront UAG server, open an elevated command prompt on
the server. Then navigate to \common\bin\tracing folder (under the Forefront UAG
installation folder).
2. Type LaunchHTA.vbs to open the tracing console.
5. To start tracing with output collected to the binary file, click Go. To start tracing in realtime mode with output to a console window, click Go RT.
6. Reproduce the scenario that you want to troubleshoot.
7. Click Stop to end tracing.
Converting the binary trace files
To convert trace files to text format from the command line
1. To convert trace files from the command line, do the following:
10
a. To convert files on the Forefront UAG server, open an elevated command prompt,
and navigate to \common\bin\tracing folder (under the Forefront UAG installation
folder).
b. To convert files on an endpoint device, open an elevated command prompt on the
endpoint. Then navigate to the Program Files\Microsoft Forefront UAG\Endpoint
Components\3.1.0 folder.
2. At the command prompt, type Trace.cmd –format. Note the following:
a. The –path parameter must be set before running this command.
b. The default binary file is located at %windir%\debug\Forefront_UAG.bin.
c.
To change the location of the binary file, specify the <binary_log_file> parameter.
Example:
Trace.cmd –format. Format the default %windir%\debug\Forefront_UAG.bin tracing file to the
default %windir%\debug\Forefront_UAG.txt text file.
To convert trace files to text format using the trace console
1. In Trace file to format, Use current displays the name and location of the binary that should
be converted to readable text. To specify a different location, select Use this file, and click
Browse to select the binary file.
2. On the Forefront UAG server or client endpoint devices, click Text to convert the binary file to
.txt format. This launches Notepad.exe, and displays the converted binary traces. Note that
the text file is not saved by default. Save the file if required.
3. On the Forefront UAG server, to view the trace in the TraceView.exe application, click
Viewer.
11