Trace and Diagnostic Utility
The FFTRACE program controls trace and debug output from all CopiaFacts components, and in most cases also runs on the same machine and displays the trace output as it is written. The main COPIAFACTS Server Engine has its own separate trace file but can also write some trace information to FFTRACE.
When tracing CopiaFacts service applications and CopiaFacts FFMERGE, FFTRACE does not display the output, which instead will be written to a separate named file for each process. But FFTRACE must still be used to set the trace options for these processes as described below, and then need not be left running if only services are to be traced.
FFTRACE allows setting the 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 uses Windows messages for communication, so only monitors programs running on the same machine and in the same Windows station.
FFTRACE runs elevated and requires administrator credentials. It will show the Windows UAC prompt if started from a normal login.
Because FFTRACE controls the level of tracing information that each application is requested to provide, it 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.
FFTRACE writes its trace files by default to the FAXFACTS folder in the COPIA share. You can override the location by specifying a folder path either on an FFTRC environment variable or on a $environment command for FFTRC. The latter override allows a different path name to be specified on different machines. Writing trace files to a local folder may improve performance when a high level of tracing is enabled, and also allows the trace to survive server or network failure.
Selecting a Node Name
The base file name of the trace file is set to be the most recent COPIAFACTS node name used on the same machine. If you run FFTRACE alongside multiple desktop instances of COPIAFACTS with different node names, the output will all be written to the same trace file.
You will be prompted for a folder and a node name the first time you run FFTRACE unless one has already been registered in the registry by the COPIAFACTS Server program. If the machine running FFTRACE is also running the COPIAFACTS Server Engine, the name of its node will be the default.
Trace log files use the node name as the file name part of their pathname. The extension is .FTx where x is the day-of-week code (Sunday=0). So for node M1_1234 the FFTRACE trace log file is named M1_1234.FT1 on Monday (and the COPIAFACTS Server Engine trace log file is M1_1234.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, and might also reveal passwords or other confidential material embedded in the displayed data.|
|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.
The entries in the applications list are of several types (all omit file extensions):
|Programs||Any of the programs in the Program Files folders for COPIA may write to FFTRACE.|
|DLLs||Any of the CF8 dynamic link libraries in the same folder may write to FFTRACE.|
|COPIAFACTS special||The names CF8VOIP and CF8DTMF may be used to obtain information about Copia VoIP Ports. No DLLs exist with these names, however.|
|FFEXTERN special||The names FXXMSSCAN, FXFDL2FS, FXPDF2FS, FXRF2FS, FXTXTSCAN, and FXPDFSCAN may be used to obtain information about FFEXTERN 'special process' operations. Other FFEXTERN processes use the FFEXTERN name. In addition the name BMP2TIF may be used for information about trying multiple image option sets in sequence.|
|CFUTIL/CFUTILITY||The items marked in the alphabetic list of actions with an asterisk can also be entered for specific trace output.|
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 file.
Changing the application settings, or stopping and starting FFTRACE may not be immediately reflected in the output of a trace file written from FFTRACE. It is dependent on the program being traced to check the trace settings, either on a regular time schedule or on the start of a new transaction.
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:
|Prompt on 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 not the default in CopiaFacts version 8, but was in earlier releases) 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, the display window will be cleared and 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 earlier trace lines.
|Monitor Memory Usage||See below.|
|Auto-scroll||Uncheck this option temporarily to prevent the display from scrolling while you are reading it. For maximum efficiency when you do not want to see an updated display, minimize the FFTRACE window rather than using this option.|
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. To locate the trace on a local drive, use the FFTRC environment variable to specify a local path.
On Windows Vista, Windows 7 or 8.x, Windows 10, or Windows Server 2008 or 2012, CopiaFacts services, applications run in service mode, and the FFMERGE print driver cannot use Windows messages to send trace output to FFTRACE. Instead the files are written to a file named for the application with FTx extension. The File/Applications menu in FFTRACE is still used to turn tracing for services on and off.
|FFTRACE need not be left running to view these special files. They can be viewed in TRCVIEW as usual. But you can open FFTRACE to change the trace settings for these files. FFMERGE trace files are written to FFMERGE.FTx in the FFMERGE output folder.|
For CopiaFacts services, the files are written to the first found of:
•The folder specified by environment variable FFTRC, if defined.
•The folder C:\FAXTEMP if it already exists
•The defined Windows temp folder.
If you encounter problems with direct-write trace files from driver and service applications, look in one of the following registry keys for an error message:
•HKLM\Software\Wow6432Mode\Copia\FFTRACE\TraceError (on 64-bit systems)
Registry Usage by FFTRACE
If you use FFTRACE from accounts with different privilege settings it may be helpful to know how the settings are saved by FFTRACE (and then used by applications):
•Settings are always saved in HKEY_LOCAL_MACHINE/Software/Copia/FFTRACE (64 bit) and HKEY_LOCAL_MACHINE/Software/Wow6432Node/Copia/FFTRACE (32 bit).
•FFTRACE sets Windows message filters to allow lower privilege applications to send Windows messages to it.
•Trace settings are no longer saved in HKEY_CURRENT_USER, although they will be read from there on upgrade to CopiaFacts 8.3 if FFTRACE has not previously been run elevated.
Tracing Initial Configuration Operations
The 'application name' of CF8REG is treated specially. If CF8REG has been enabled in FFTRACE, then application settings, trace and debug messages from CF8REG.DLL 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.
You can check the Monitor Memory Usage option in the Options menu to cause FFTRACE to report allocated memory usage for all active COPIAFACTS processes. FFTRACE must be left running to collect this information, so memory monitoring must currently be done with desktop and command-line applications only.
The usage is reported at intervals and only when the usage in a module has changed, and also after the option is (re-)enabled or FFTRACE is (re-)started. Only dynamically allocated memory is shown, so the total reported will not match the process memory reported by Task Manager or Process Explorer.
This option should not affect performance noticeably, but it can also be turned on and off at intervals for comparison purposes. Memory usage is reported even for active processes which do not have checks in the File/Applications menu.