Trace Migration

This topic introduces how you can migrate BTT version 5.2 trace to BTT version 6.1.2 trace.

The original trace API of BTT version 5.2 can be still used in BTT version 6.1.2. BTT version 6.1.2 trace facility can automatically map the old API to the new API of BTT version 6.1.2 trace facility. BTT version 6.1.2 traces by package, but the original trace is by the Component ID in BTT version 5.2. BTT version 5.2 trace can trace to multiple targets at the same time, but BTT version 6.1.2 supports tracing to one target at the same time only when the BTTLogFactoryImplementClass 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 BTT version 6.1.2. The original function and implementation of trace to Display is kept in BTT version 6.1.2, so the parameter for trace to Display is still supported.

The original HML trace level is not supported in BTT version 6.1.2. The original trace type is mapped to a new trace level. See the following table.
Table 1. Trace level map
BTT 6.1.2 trace level BTT 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
An example of migrating BTT version 5.2 trace to BTT version 6.1.2 trace is as follows:
BTT version 5.2 trace configuration
<kColl id="traces">
    <field id="initializer" value="com.ibm.btt.base.TraceInitializer" />
    <field id="traceToFile" value="yes" />
    <field id="traceToDisplay" value="yes" />
    <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="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="200" />

    <kColl id="requestersComponents">
      <traceRequester id="#CHA" trace="yes" traceLevels="HML" traceTypes="FATAL" />
      <traceRequester id="#CS" trace="yes" traceLevels="HML" traceTypes="DEBUG" />
    </kColl>
</kColl>
BTT version 6.1.2 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>
BTT 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 .........");
BTT version 6.1.2 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

BTT version 6.1.2 supports 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 BTT version 6.1.2. 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:
    BTT version 6.1.2 supports trace to WAS and common logging. BTT trace maps the BTT 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 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 BTT trace API. You can input component ID and trace level as parameters.
      4. BTT trace facility calls the corresponding java.util.logging API, if you enable the component and BTT trace level. The BTT trace level is converted to WAS trace level.
      5. After BTT 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 exmaple Log4J.
      4. Trace application code calls the corresponding common logging API. You can input component ID and trace level as parameters.
      5. BTT trace facility calls the corresponding common-logging API, if you enable the component and the BTT trace level. The BTT trace level is converted to common logging trace level.
      6. BTT 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 need to migrate the TraceConfigServlet class too.

        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.