test

Oracle Waveset 8.1.1 System Administrator's Guide

How To Configure Tracing

This section describes how to enable and configure tracing from several locations within Waveset. Instructions are organized as follows:

ProcedureTo Enable Tracing from the System Settings Page

The System Settings page is the primary Waveset Debug page.

From this page, you can

Use the following steps to enable tracing from the Waveset System Settings page:

  1. Open a browser and log in to the Waveset Administrative interface.

  2. Type the following URL:

    http://hostport/idm/debug

    where:

    • host is the local server on which you are running Waveset.

    • port is the number of the TCP port on which the server is listening.

  3. When the System Settings page displays, click Show Trace (located near the bottom of the page) to manage a single trace configuration, where you can create, modify, or delete up to ten trace settings.

    Note –

    The remaining instructions assume you have only one trace configuration.

    To manage multiple trace configurations, click the Show Trace List button instead. When the Trace Configuration page displays, click the configuration name to edit the current settings.

    Waveset supplies one configuration, called Global, by default. However, if you have multiple servers in an Waveset instance, defining different configurations for particular servers might be useful. If the name of a trace configuration matches the name of the current host, the host configuration overrides the Global configuration.

Next Steps

After you configure tracing, you can view and edit the default global trace configuration object or create a new configuration object as described in the following sections:

ProcedureTo Edit the Default Configuration Object

  1. From the Edit Trace Configuration page, click the Trace Enabled box to enable tracing.

    Note –

    Deselecting this box stops tracing, but keeps your configuration. You can turn tracing on and off without having to remember and retype the classes you were tracing.

  2. Specify which classes, packages, or methods to trace by typing their names into the table.

    For example:

    • To trace all classes in the waveset.repository package, enter com.waveset.repository.

    • To trace the AbstractDataStore class in the waveset.repository package, enter com.waveset.repository.AbstractDataStore.

    • To trace the list method in the AbstractDataStore class in the waveset package, enter com.waveset.repository.AbstractDataStore#list.

    Do not enable trace for the com.waveset class. The com.waveset class is verbose and has many classes, so tracing this class might cause your server to hang.

  3. In the same table, choose a Method/Class tracing level from the Level menu.

    Each level captures different types of information, as described in the following table:

    Trace Level 

    Description 

    0 

    Minimum debugging output, traces exceptions and error information only 

    1 

    Trace Level 0 events, plus entries and exits for public methods 

    2 

    Trace Level 1 events, plus entries and exits for non-public methods 

    3 

    Trace Level 2 events, plus decision points and significant variables 

    4 

    Maximum debugging output 

    Note –

    Method/Class tracing produces a predictable, but possibly very large volume of trace output. Try to be as specific as possible when specifying methods and classes to trace.

  4. (Optional) To enable subcall tracing, choose a level from the Subcall Trace menu. This menu uses the same trace numbering scale described in the previous table.

    Note –

    • The default Subcall Tracing level is none, which disables subcall tracing on a per-method or per-class basis.

    • Subcall Tracing levels are independent of the Method/Class tracing levels you specified in the previous step.

    When you enable Subcall Tracing for a particular method that supports subcall tracing, you are automatically setting the tracing level for methods that are called by this method. Subcall Tracing enables you to produce a short, but detailed burst of trace output that is triggered by the entry into a specified method and terminated by the method’s exit.

    For example, assume you created a trace configuration setting for the com.waveset.adapter.NewRes#init method, set Method/Class tracing to level one and set Subcall tracing to level three.

    Also, assume that the init method calls two other methods:

    • NewRes#subcallA

    • NewRes#subcallB

      When the init method runs, the com.waveset.adapter.NewRes#init method produces trace output at level one until reaching subcallA. When subcallA begins executing, the trace level changes to three and continues at that level until subcallA exits. The com.waveset.adapter.NewRes#init method returns to the init method and restores the trace level to one. Later, when init calls subcallB, there is another burst of level three trace detail that lasts until subcallB exits. Finally, when init exits, level one tracing stops.

  5. Send the trace results to a specified file location or to stdout.

    If you choose output to a file, the Trace File field displays. Use this field to specify an alternate location and file name for trace output files. The default location and file name is


    path_to_idm_install\export\pipeline\config\WSTrace.log

  6. Specify the maximum number of trace files to store (default is 2).

  7. Specify the maximum size for each file (default is 512K).

  8. Specify whether to write the trace output file as generated (synchronously) or to queue the data and then write it to the trace file (asynchronously).

  9. Save your changes.

ProcedureTo Create a New Trace Configuration Object

Use the following steps to create a new trace configuration object:

  1. Decide which package or method you want to trace.

    Generally, you specify a resource adapter name or use information that was revealed in an error message.

  2. Log in to the Waveset Administrator interface and open the System Settings page as described in To Enable Tracing from the System Settings Page.

  3. On the Systems Setting page, click Show Trace List.

  4. When the Waveset Trace Configuration page displays, click New.

  5. Enable tracing from the Edit Trace Configuration page.

    Choose one of the following options from the Trace Configuration menu:

    • Global. Select to enable tracing for all servers.

    • Server_name. Select a server name to enable tracing for a particular server.

  6. Select the Trace Enabled box to enable tracing for this object and configure the remaining parameters on this page as described in To Edit the Default Configuration Object.

  7. Save your changes.

ProcedureTo Configure Tracing From Individual Debug Pages

This section describes how to enable tracing from an Waveset Debug page.

  1. Open a browser and log in to the Waveset Administrative interface.

  2. Type the following URL:

    http:// host:port /idm/debug/pageName.jsp

    where:

    • host is the local server on which you are running Waveset.

    • port is the number of the TCP port on which the server is listening.

    • pageName.jsp is the particular Debug page you want to open.

      For example, to trace adapter classes and methods for a custom adapter, you can open the Edit Trace Configuration page by typing the following URL:

      http://host :port/idm/debug/Show_Trace.jsp

ProcedureTo Enable Tracing From the Waveset Console

This section explains how to enable tracing from the Waveset console.

  1. Set $WSHOME.

    For example, to set the variable to the default installation directory:


    set WSHOME=C:\Program Files\tomcat\webapps\idm

  2. Type lh console to open the Waveset console from the bin directory.

  3. From the console, type trace to see a detailed summary of available trace options, including enable and disable.

    The syntax for this command is:

    trace [ -s server ] $subcommand

ProcedureTo View Sensitive Data in the Trace Output

By default, Waveset “sanitizes” trace information by replacing each occurrence of sensitive data with a single asterisk. Sensitive data includes any data that is inbound to encryption methods, outbound from decryption methods, and cipher-related metadata such as data lengths, padding lengths, and so forth. However, you can configure a property in the Waveset.properties file to include this information in your trace output for debugging purposes.

Use the following steps to enable sensitive cipher data in your trace logs:

  1. From a command line, open the Waveset.properties file.

  2. Locate the cipher.data.trace property file comments, and uncomment the following line:


    cipher.data.trace=true

  3. Restart your server for this change to take effect.