Configuring the Trace Facility

To configure the Trace Facility, you can specify initial values in the toolkit configuration file (dse.ini) that will be used when the facility is initialized. The trace component's public API can later be used to dynamically change the initial configuration. The dse.ini file contains a traces keyed collection, where you can specify the following elements:
Table 1. Trace Facility configuration
Element ID Description of value
traceToFile Whether the trace-to-file facility is required. The following are the possible values:
  • yes
  • no (default)
This setting can be changed dynamically at run time.
traceToDisplay Whether the trace-to-display facility is required. The following are the possible values:
  • yes
  • no (default)
This setting can be changed dynamically at run time.
traceToWAS Whether the trace-to-WAS facility is required. The following are the possible values:
  • yes (default)
  • no
This setting can be changed dynamically at run time.
traceToCommonLogging Whether the traceToCommonLogging facility is required. The following are the possible values:
  • yes (default)
  • no
This setting can be changed dynamically at run time.
traceFileName Path and file name of the trace file. The file name can contain the %date and the %order parameters. For example: c:\dse\logs\dse-%date-%order.log
wasTraceCatalog How the BTT trace request is cataloged in WAS trace level configuration page. BTT trace can be cataloged by Component name or PackageClass Name.
The following are the possible values:
  • ByComponent
  • ByPackageClass (default)
traceMaxLogFiles Maximum number of trace files stored for the day (maximum value that the %order parameter will contain). The default is 10, and the maximum value is 99.
createBackup Whether a backup of a trace file will be created before that file is overwritten because a file with the same filename is going to be created.  The following are the possible values:
  • yes (default)
  • no
fileNumberOfLines Maximum number of lines in the trace file. The default is 8000.
displayNumberOfLines Maximum number of lines to be displayed in the trace window. The default is 8000.
defaultCP Code page for trace file. The default is the value returned by the System.getProperty("file.encoding"). If the file.encoding property is not available, the default value is 8859_1.
linesOfBuffer Number of trace entries that can be kept in an intermediate buffer. The default is 250. See Using a buffer to improve performance.
lineLength Maximum line length of a trace record in the trace file and in the display. When this value is reached, the remaining information will be written on the next line. The default is 128 bytes, and the maximum is 512 bytes.
showOriginator Whether the class and method name of the trace record originator are to be included in the trace record report. The following are the possible values:
  • yes
  • no (default)
This setting can be changed dynamically at run time.
useServletsEngineLog Whether the Web server log facilities will be used instead of the toolkit Trace Facility. This is only applicable to the server side toolkit/application. The following are the possible values:
  • yes
  • no (default)
servletsEngineLogPort The port to use when useServletsEngineLog is set to true. The default is 80.
showWarningMessage Whether a warning message will be displayed when the trace facilities cannot proceed as expected because of an error condition. The following are the possible values:
  • yes
  • no (default)
By default, the warning message is redirected to the standard output. This is the recommended value on the server workstation, because some Web servers do not correctly handle Java™ AWT classes.
traceWindowTitle Title to be shown in the trace window. If this setting is not specified, then the default value will be the path of the configuration file.

This setting enables you to differentiate between the trace window belonging to the client side and the one belonging to the server side of the toolkit/application when both are running on the same workstation.
font Name of the font that is used to display the trace information in the viewer tool window. The default value is the default system font.
requesterComponents A collection of data where each element specifies the settings for each component. These component settings can be specified in any order, and can be changed dynamically at run time. The purpose of this setting is to improve performance by allowing an application to determine which trace types are enabled for reporting before invoking the trace. Note however that a trace call can specify a disabled trace type and it will be reported.

The default configuration file contains the complete list of components available in the toolkit.

If the Trace Facility does not find the identifier for a given component, it uses the values specified in the unAssigned entry.

The element identifier is traceRequester and has the following attributes:
  • id - The component identifier.
  • trace - Whether the trace for this component is enabled. The following are the possible values:
    • yes (default)
    • no
       
  • traceLevels - Which trace levels are to be enabled for this component. The following are the possible trace levels:
    • DEBUG
    • INFO
    • WARN
    • ERROR
    • FATAL
    • NONE
    The default value is DEBUG.
    Note: If the specified trace level is unknown or using the old BTT trace level (HML or DIPEWS), the default trace level DEBUG is used.
traceLevels Indicates which trace levels are enabled for reporting. This keyword contains global values applicable to all the components. The possible trace levels are:
  • DEBUG
  • INFO
  • WARN
  • ERROR
  • FATAL
  • NONE
These can be specified in any order, and can be changed dynamically at run time. The purpose of this setting is to improve performance by allowing an application to determine which trace types are enabled for reporting before invoking the trace. Note however that a trace call can specify a disabled trace type and it will be reported.

The default is DEBUG (all levels are reported).
Note: The requested trace level is validated by both the global trace level and the component trace level. For example, if global trace level is FATAL, trace level configuration of component CHA is set to DEBUT, then only FATAL trace request of CHA component can be recoreded.
Note: The global trace level is used when the requested component ID is unknown (not defined in btt.xml trace setting).

The following example of a traces keyed collection definition uses all the possible keys. The settings are described in detail below.

<kColl id="traces"> 
  <field id="traceToFile" value="yes" />
  <field id="traceToDisplay" value="yes" />
  <field id="traceToWAS" value="yes" />
  <field id="traceToCommonLogging" value="yes" />
  <field id="traceWindowTitle" value="Server trace" />
  <field id="showOriginator" value="yes" />
  <field id="showWarningMessage" value="yes" />
  <field id="traceLevels" value="DEBUG" />
  <field id="wasTraceCatalog" value="byComponent" />
  <field id="traceFileName" value="C:\dse\dselog.txt"/>
  <field id="traceMaxLogFiles" value="5" />
  <field id="font" value="monospaced"/>
  <field id="createBackup" value="yes"/>
  <field id="fileNumberOfLines" value="4000" />
  <field id="displayNumberOfLines" value="2000" />
  <field id="linesOfBuffer" value="7000" />
  <field id="lineLength" value="128" />
  
  <kColl id="requestersComponents">
    <!-- CHA components -->
    <traceRequester id="#CHA" trace="yes"  traceLevel="DEBUG"/>
    <!-- Core components -->
    <traceRequester id="#CORE" trace="yes" traceLevel="INFO"/>
    <!-- Client/server -->
    <traceRequester id="#CS" trace="no"  traceLevel="INFO"/>
</kColl id="traces">

These settings have the following effects:

Related concepts
Trace-to-WAS reporting
Related tasks
Using a buffer to improve performance