Migrating trace

This topic describes how to migrate the IBM® WebSphere® Multichannel Bank Transformation Toolkit version 5.2 trace to the WebSphere Multichannel Bank Transformation Toolkit version 8.0 trace.

About this task

The original trace API of WebSphere Multichannel Bank Transformation Toolkit version 5.2 can be still used in WebSphere Multichannel Bank Transformation Toolkit version 8.0. The WebSphere Multichannel Bank Transformation Toolkit version 8.0 trace facility can automatically map the old API to theAPI of the WebSphere Multichannel Bank Transformation Toolkit version 8.0 trace facility. WebSphere Multichannel Bank Transformation Toolkit version 8.0 traces by package, but the original trace is by the Component ID in WebSphere Multichannel Bank Transformation Toolkit version 5.2. The WebSphere Multichannel Bank Transformation Toolkit version 5.2 trace can trace to multiple targets at the same time, but WebSphere Multichannel Bank Transformation Toolkit version 8.0 supports tracing to one target at the same time only when the BTTLogFactoryImplementClass class is set.

The implementation of trace to File is changed to using Java util API, so the original parameter of trace to File is not supported in WebSphere Multichannel Bank Transformation Toolkit version 8.0. The original function and implementation of trace to Display is kept in WebSphere Multichannel Bank Transformation Toolkit version 8.0, so the parameter for trace to Display is still supported.

The original HML trace level is not supported in WebSphere Multichannel Bank Transformation Toolkit version 8.0. The original trace type is mapped to a new trace level. See the following table.
Table 1. Trace level map
WebSphere Multichannel Bank Transformation Toolkit version 8.0 trace level WebSphere Multichannel Bank Transformation Toolkit version 5.2 trace type WAS trace level Common logging Log4J
FATAL Severe Fatal Fatal Fatal
ERROR Error Severe Error Error
WARN Warning Warning Warn Warn
INFO Information Display Info Info Info
DEBUG Debug AllTypes Detail* Debug Debug

Example

An example of migrating WebSphere Multichannel Bank Transformation Toolkit version 5.2 trace to WebSphere Multichannel Bank Transformation Toolkit version 8.0 trace is as follows:
WebSphere Multichannel Bank Transformation Toolkit version 5.2 trace configuration
<kColl id="traces">
    <field id="initializer" value="com.ibm.btt.base.TraceInitializer" />
    <field id="traceToFile" value="yes" />
    <field id="traceFileName" value="c:\btt\log\btt.log" />
    <field id="traceToDisplay" value="no" />
    <field id="traceToWAS" value="yes" />
    <field id="traceWindowTitle" value="Server Trace" />
    <field id="showOriginator" value="yes" />
    <field id="showWarningMessage" value="no" />
    <field id="traceLevels" value="debug" />
    <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="200" />

    <kColl id="requestersComponents">
      <traceRequester id="#CHA" trace="yes" traceLevels="HML" traceTypes="FATAL" />
      <traceRequester id="#CS" trace="yes" traceLevels="HML" traceTypes="DEBUG" />
    </kColl>
</kColl>
WebSphere Multichannel Bank Transformation Toolkit version 8.0 trace configuration after migration
<kColl id="traces">
    <field id="initializer" value="com.ibm.btt.base.TraceInitializer" />
    <field id="traceTargetFactoryImplClass" 
		value="com.ibm.btt.base.BTTLogFactoryToDisplayImp" />
    <field id="displayNumberOfLines" value="2000" />
    <kColl id="requestersComponents">
      <traceRequester id="com.ibm.btt.base.*" trace="yes" traceLevels="FATAL" />
      <traceRequester id="com.ibm.btt.channel.*" trace="yes" traceLevels="DEBUG" />
    </kColl>
</kColl>
WebSphere Multichannel Bank Transformation Toolkit version 5.2 trace application code
if (Trace.doTrace(Constants.CHACOMPID,Trace.High,Trace.Debug))
    Trace.trace(Constants.CHACOMPID,Trace.High,Trace.Debug,Settings.getTID(),
                " CHA Debug .........");
if (Trace.doTrace(Constants.CHACOMPID,Trace.High,Trace.Information))
    Trace.trace(Constants.CHACOMPID,Trace.High,Trace.Information,Settings.getTID(),
               "CHA info .........");
WebSphere Multichannel Bank Transformation Toolkit version 8.0 trace application code after migration
BTTLog   log=BTTLogFactory.getLog(“com.ibm.btt.base.LocalContextImp”);
If (log.doDebug())
  log.debug(“CHA Debug……”);
If (log.doInfo())
  log.info(“CHA info……”);

Four trace types

WebSphere Multichannel Bank Transformation Toolkit version 8.0 supports the following four trace target types:
  • Trace to window
  • Trace to self define file
  • Trace to WAS file
  • Trace to common-logging
  • Trace to window and self-defined file:

    Trace to window and trace to self-defined file functions are kept for migration consideration.

    Trace to window function can be used at client side.

    Most of the functions of trace to file are not supported in WebSphere Multichannel Bank Transformation Toolkit version 8.0. For example, the following is not supported:
    <field id="traceMaxLogFiles" value="5"/>
    <field id="fileNumberOfLines" value="4000"/>
    <field id="displayNumberOfLines" value="200"/>
    <field id="linesOfBuffer" value="700"/>
    <field id="lineLength" value="128"/>

    As a result, you can use trace to common logging or trace to WAS instead.

  • Trace to WAS and common logging:
    WebSphere Multichannel Bank Transformation Toolkit version 8.0 supports trace to WAS and common logging. WebSphere Multichannel Bank Transformation Toolkit trace maps the WebSphere Multichannel Bank Transformation Toolkit trace API to the corresponding trace API of common logging and WAS java.util.logging.
    Note: Common logging only provides the API standard, and the logging implementation is provided by other logging facilities for example Log4J. The trace level is also converted.
    1. Trace to WAS:
      1. Change the dse.ini file, and enable traceToWAS. You can enable and disable trace switch and set trace level for each component.
      2. You can enable and change the trace level dynamically in WAS console.
      3. Trace application code calls the WebSphere Multichannel Bank Transformation Toolkit trace API. You can enter component ID and trace level as parameters.
      4. The WebSphere Multichannel Bank Transformation Toolkit trace facility calls the corresponding java.util.logging API, if you enable the component and WebSphere Multichannel Bank Transformation Toolkit trace level. The WebSphere Multichannel Bank Transformation Toolkit trace level is converted to WAS trace level.
      5. After WebSphere Multichannel Bank Transformation Toolkit trace calls the WAS trace API, and if the input trace level is enabled in the trace configuration of WAS console, the trace content is recorded to WAS trace file.
    2. Trace to common logging:
      1. Change the dse.ini file and enable traceToCommonLogging.
      2. You can enable or disable the trace switch and set the trace level for each component.
      3. Set the common logging property file and specify the implementation of common logging, for example Log4J.
      4. Trace application code calls the corresponding common logging API. You can enter component ID and trace level as parameters.
      5. WebSphere Multichannel Bank Transformation Toolkit trace facility calls the corresponding common-logging API, if you enable the component and the WebSphere Multichannel Bank Transformation Toolkit trace level. The WebSphere Multichannel Bank Transformation Toolkit trace level is converted to common logging trace level.
      6. WebSphere Multichannel Bank Transformation Toolkit trace calls the common logging API. Whether the trace content is recorded into the trace file depends on the trace level setting of the common logging implementation.
    3. Migrating code:
      • Migrating XML definition files.
        Before migration, the code for XML definition file is as follows:
        <kColl id="traces">
          <field id="traceToFile" value="yes"/>
          <field id="traceToDisplay" value="yes"/>
          <field id="traceFileName" value="c:\dse\log\btt.log"/>
          <field id="traceMaxLogFiles" value="100"/>
          <field id="font" value="monospaced"/>
          <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="PSP6 Server Trace"/>
          <field id="traceTypes" value="DIPEWSV"/>
          <field id="traceLevels" value="HML"/>
          <field id="showContextDump" value="yes"/>
          <kColl id="requestersComponents">
          ....
          </kColl>
        </kColl>
        After migration, the code is as follows:
        <kColl id="traces">
          <field id="initializer" value="com.ibm.btt.base.TraceInitializer"/>
          <field id="traceTargetFactoryImplClass" 
           value="com.ibm.btt.base.BTTLogFactoryToCommonLoggingImp" />
          <field id="showContextDump" value="yes"/>
          ....
        </kColl>

        In the XML trace definition migration, <requestersComponents> definition is not used for common logging. You need to configure initializer and traceTargetFactoryImplClass. You can leave the other configuration as it is.

        If you choose common logging trace, you must also migrate the TraceConfigServlet class.

        If you choose WAS trace, WAS console has similar functions.

      • Some trace APIs do not need migration, for example:
        Trace.trace(CommonsConstants.COMPID, Trace.Low, 
        Trace.Information, Settings.getTID(), msg); 
        Trace level=Trace.Low, Setting.getTID() will not use, 
        BTT trace will map the other three parameter to commond-logging.