Trace and Diagnostic Utility

FFTRACE [dirname] [/Q=queuename]

The FFTRACE program collects trace and debug lines from all CopiaFacts utility programs (but the COPIAFACTS Server Engine also 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 uses Windows messages for communication, so only monitors programs running on the same machine and in the same Windows station.

For tracing CopiaFacts service applications and CopiaFacts driver interfaces, FFTRACE does not display the output, which instead will be written to a separate named file for each process.  But FFTRACE, when run elevated, can set the trace options for these processes as described below.

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.

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/StopChecking 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 LevelCheck 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.

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.

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 TimerWhen 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 TimerUses 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-scrollUncheck 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.

Trace output from Services and FFMERGE

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 and print drivers on and off.  For FFMERGE, print drivers (FFCVRT.FTx and FFSAVE.FTx), and 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 folder specified by environment variable GFAX (normally C:\FAXTEMP), if defined.

The defined Windows temp folder.

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.

For FFMERGE, and for services run in the Local System Account, FFTRACE must be 'run as administrator' (Vista/2008 and above) or with admin privileges (before Vista/2008).  Before version 8.2.0.70 this applied to other print drivers and to all service applications.

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:

HKCU\Software\Copia\FFTRACE\TraceError

HKLM\Software\Copia\FFTRACE\TraceError

HKLM\Software\Wow6432Mode\Copia\FFTRACE\TraceError     (on 64-bit systems)

Changing Trace File Encoding

If you want to change the setting of the Tracefile keyword on a $unicode command, you should take the following actions:

Shut down all CopiaFacts programs on the machine affected before making the $unicode change in FAXFACTS.CFG

Delete or rename "today's" tracefiles (.TRx and .FTx) where X is the day number (Sunday = 0).  Data already written to today's files will have the previous encoding.

Run FFTRACE, select File / Applications, and click OK.

Restart programs as needed, so that fresh tracefiles will be created with the specified encoding.

Note that only system default encoding and UTF-8 are valid choices for the trace file encoding.  You will need the latter if you wish to view Unicode data which is written to the trace file.  The special services and drivers trace files are always written in UTF-8 encoding and the $unicode keyword TraceFile is ignored for them.

Advanced use of FFTRACE

The use of MSMQ for trace messages is no longer required except for tracing CopiaFacts version 7 print drivers.  To set up FFTRACE for this purpose, use version 7 of FFTRACE and see the FFTRACE topic in the CopiaFacts version 7 help file.

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_CURRENT_USER/Software/Copia

If run with admin privilege (before Vista/2008) or elevated (Vista/2008 and above) settings are also saved in HKEY_LOCAL_MACHINE/Software/Copia (32-bit systems) or HKEY_LOCAL_MACHINE/Software/Wow6432Node/Copia (64-bit systems).

If run elevated on a 64-bit OS, settings are also saved in HKEY_LOCAL_MACHINE/Software/Copia.

Tracing 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.

Monitoring Memory Usage

You can check the Monitor Memory Usage option in the Options menu to cause FFTRACE to check memory usage in the COPIAFACTS graphical interface and most of the DLLs it uses.  In addition, setting USE_CF8MM to a non-empty value as a Windows system environment variable (and restarting COPIAFACTS) will enable the use of an instrumented memory manager by all the remaining engine DLLs so that usage summaries are reported for every COPIAFACTS module.

FFTRACE must be left running to collect this information, so memory monitoring must currently be done with desktop applications only.

The usage is reported only when the usage in a module changes, 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. The modules for which memory usage is reported are not affected by the settings in the File/Applications menu.