|
FFTRACE |
  
|
| Show/Hide Hidden Text |
|
FFTRACE |
|
| Show/Hide Hidden Text |
Trace and Diagnostic Utility
FFTRACE [dirname] [/Q=queuename]
The FFTRACE program collects trace and debug lines from CopiaFacts utility programs other than the COPIAFACTS Server Engine (which has its own trace and debug capability). Using FFTRACE you can set what level of information you require from each program and whether the trace information displayed on the screen should also be written to a log file. FFTRACE normally uses Windows messages for communication, so only monitors programs running on the same machine and in the same Windows station; but an option is available to use a message queue which can be accessed from elsewhere.
FFTRACE controls the level of tracing information that each application is requested to provide. It therefore allows you to monitor progress or obtain diagnostic information without having to restart the application in trace or debug mode. Each supported CopiaFacts application will monitor the options set by FFTRACE at regular intervals and respond accordingly.
The trace settings for each program are stored in the Windows registry. If you are a user with Admin privileges, the key used is HKLM/Software/Copia/FFTRACE. Otherwise the key used is HKCU/Software/Copia/FFTRACE.
If the program is able to determine from a local COPIAFACTS.INI file the base directory of your CopiaFacts installation, trace log files will be written there. If not, trace files will be written in a directory C:\FFTRACE, which will be created if it does not exist. You can override the directory name for trace log files by specifying a valid directory name on the command-line or icon used to start FFTRACE.
It is suggested that you place a shortcut to FFTRACE in Start | Programs | Startup so that it will be run automatically when you start the system. You can set the shortcut options to run the program minimized. If you subsequently start FFTRACE from its own icon, this will activate the existing instance of the program.
Selecting a Node Name
You must specify a node name the first time you run FFTRACE unless one has already been registered in your local COPIAFACTS.INI file by the COPIAFACTS Server program. If the machine running FFTRACE is also running the COPIAFACTS Server Engine, you must keep the same node name.
Trace log files use the node name as the filename part of their pathname. The extension is .FTx where x is the day-of-week code (Sunday=0). So for node M1 the FFTRACE trace log file is named M1.FT1 on Monday (and the COPIAFACTS Server Engine trace log file is M1.TR1).
You can use the File | Node Name menu dialog to set or change the node name, but this is not normally necessary after first installation on a machine. If you accidentally use the same node name and network directory from more than one machine running FFTRACE, it is likely that sharing violations will occur: FFTRACE detects this and disables writing to the trace file on all except one of the duplicates.
Selecting Applications to Trace
The menu item File | Applications must be used to select which applications to trace. If no applications have been set up when you first select this option, an initial set of default application names and options is installed.
For each application, you may set the following options:
| Start/Stop | Checking the box requests the application to output summary information only. |
| Information | Checking this box requests the application to output information messages about normal actions. |
| Debug | Checking this box requests the application to provide diagnostic information for use when problems have occurred. |
| Low Level | Check this box only when requested to do so by Copia support staff. For some applications, it may produce large amounts of output. |
| Log File | This box causes FFTRACE to save each displayed message for the application in the trace log file. |
Note that the first four options only indicate to the application which type of tracing you wish to see. The actual level of displayed messages will vary from application to application as appropriate.
Setting the Debug and Low-level messages options may produce a large volume of output for some programs. In general these selections should only be made when requested by Copia for problem determination. The .FTx daily trace files created by FFTRACE may be viewed using TRCVIEW, which can separate out the traces for different applications that may have been combined in the same trace.
FFTRACE Actions and Options
The following actions are possible with FFTRACE:
| Save Trace | This menu item saves the entire scrollable trace window contents into a file. This may be useful when trace messages are displayed for applications which do not have the log file option set. If you have annotated the trace window it also allows you to save your annotations. |
| Clear Trace | You can clear the trace display, the trace log file, or both at any time. Clearing the trace log file erases it and starts a new file with the same name. |
| Reset Timer | When the high-resolution timer is enabled, resets the timer origin and logs the clock time at which it was reset. |
The following options can be set:
| Confirm Clear | Prompts you for confirmation before clearing the trace window and erasing the log file. |
| Read Only | Prevents you from adding notes to the trace window and from editing displayed lines. |
| Always on Top | Forces the trace window to be visible on top of other application windows. |
| High-Res Timer | Uses a high-resolution timer to display more accurate times. The resolution depends on the CPU in use but is normally of the order of a microsecond. |
Update Display when minimized When checked (which is the default) the display will continue to update while FFTRACE is minimized, so that you can see the full trace when you restore the FFTRACE display. If unchecked, trace lines will not be added to the display while minimized, but will be written to file if this option is selected for the application. In this case you would therefore need to use TRCVIEW to display trace lines for the period while FFTRACE was minimized.
FFTRACE also has a search facility which operates on the contents of the scrollable trace window.
Reducing FFTRACE's impact
FFTRACE is designed to be as efficient as possible but tracing does have some effect on performance. To minimize this, you should consider always locating the trace file on a local filesystem, and also running with FFTRACE minimized.
Advanced use of FFTRACE
When a private MSMQ queue name is specified on the command line, FFTRACE accepts trace records from the queue in addition to Windows messages. This allows FFTRACE to receive messages from applications running as services or as web applications. This feature may require special versions of CopiaFacts executables and libraries which write trace and debug messages to the queue; please contact Copia support if you feel you need this capability.
Under Windows Server 2008, in some circumstances, you may need to run FFTRACE 'as adminstrator' to capture trace output from a CopiaFacts application being run 'as administrator'.
For Vista and later, Microsoft prevents printer drivers from communicating with applications such as FFTRACE using Windows messages. It is therefore necessary to use the MSMQ interface.
Set up FFTRACE for MSMQ interface:
"C:\Program Files\Copia\FFTRACE.EXE" /Q=.\private$\traceq
|
Tracing Configuration Operations
The 'application name' of CFREG is treated specially. If CFREG has been enabled in FFTRACE, then application settings, trace and debug messages are written to the CopiaFacts Windows Event Log, not to the FFTRACE display. The FFTRACE program does not have to be left running to see these messages. This feature permits investigation of configuration issues even if they affect the writing of trace and debug messages.
Topic url: http://www.copia.com/support/refmanual/index.html?fftrace.htm
