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.
wasTraceMessageTitle Title of the trace message that is displayed in the WebSphere(R) Application Server console. It helps you identify where the message is from. You can use the server name or the component name as the message title, for example, CHA Server.

This title is displayed at the fifth column of each trace record.
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
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(TM) 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
  • traceTypes - Which trace types are to be enabled for this component. The following are the possible trace types:
    • P - Display
    • I - Information
    • W - Warning
    • E - Error
    • S - Severe error
    • D - Debug
    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.
  • traceLevels - Which trace levels are to be enabled for this component. The following are the possible trace levels:
    • H - High
    • M - Medium
    • L - Low
traceTypes Indicates which trace types are to be enabled for reporting. This value contains global values applicable to all the components. The possible trace types are:
  • P - Display
  • I - Information
  • W - Warning
  • E - Error
  • S - Severe error
  • D - Debug
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 PIWESD (all types are reported).
traceLevels Indicates which trace levels are enabled for reporting. This keyword contains global values applicable to all the components. The possible trace levels are:
  • H - High
  • M - Medium
  • L - Low
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 HML (all levels are reported).

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="traceToWAS" value="yes" />
	<field id="wasTraceMessageTitle" value="CHA Server"/>
  <field id="traceToFile" value="yes" />
  <field id="traceToDisplay" value="yes" />
  <field id="traceFileName" value="c:\dse\logs\dse-%date-%order.log" />
  <field id="traceMaxLogFiles" value="5" />
  <field id="createBackup" value="yes" />
  <field id="fileNumberOfLines" value="4000" />
  <field id="displayNumberOfLines" value="200" />
  <field id="linesOfBuffer" value="700" />
  <field id="lineLength" value="128" />
  <field id="showOriginator" value="yes" />
  <field id="useServletsEngineLog" value="no" />
  <field id="servletsEngineLogPort" value="80" />
  <field id="showWarningMessage" value="yes" />
  <field id="traceWindowTitle" value="Server trace" />
  <field id="font" value="monospaced" />
  <field id="traceTypes" value="IPEWS" />
  <field id="traceLevels" value="HML" />
    <kColl id="requestersComponents">
      <traceRequester id= "#LU0" trace="no" Types="DIPEWS" 
              traceLevels="HML" />
      <traceRequester id= "#LU62" trace="yes" traceTypes="DWS" 
              traceLevels="HL" />
      <traceRequester id="unAssigned" trace="yes" traceTypes="IPEWS" 
              traceLevels="HML" />
 </kColl>
</kColl>

These settings have the following effects:

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