3 Tracing and Logging

You can enable tracing for the Mobile Server, the Mobile Client, or the Oracle Lite database on the client. In addition, you can view the log files from the underlying application server. The methods for enabling tracing for each component is described in the following sections:

3.1 Enable Tracing on the Mobile Server

For the Mobile Server, there are two main sections for tracing: the general tracing for Mobile Server components and specific tracing for data synchronization components. How to enable tracing for each part of the Mobile Server is described in the following sections:

3.1.1 General Tracing for the Mobile Server

To set general tracing for the Mobile Server, perform the following steps.

  1. From the Mobile Server page, select Administration.

  2. Select Trace Setting. This brings up the Trace Settings page, as shown in Figure 3-1, where you can choose to generate trace output, specify the trace output destination to the local console, file, or remote console (viewed by wsh). The Trace Settings page provides system filters to generate trace output to the required system level.

  3. Configure the type of tracing you want and click Apply.

Figure 3-1 General Trace Settings for Mobile Server

General trace settings
Description of "Figure 3-1 General Trace Settings for Mobile Server"

Table 3-1 Trace Settings Page Description

Field Description

Trace Output

To generate trace output, select Yes.

Console

You can print the messages to a console. You can ONLY choose the console if you are executing Mobile Server in standalone mode. If you are in an OracleAS environment, select File or Remote.

File

You can direct all messages to a local file. If you selected a file for trace output, then enter the name (including path), the maximum size of the file in MB, and the number of files allowed (pool size). For example, if you set the pool size to 10, then when a trace file hits the maximum size in MB, then a new file is opened and the trace output is written to the new file. This continues until all 10 files of the maximum size exist. At this point, the first file is deleted and a new file is started to contain the trace output. This enables you to manage the amount of disk space that the trace files can use.

To create a trace file for every user, select Yes for the Create Trace File for Every User box.

System Filter

  • HTTP Request—To generate HTTP output and Web-to-Go trace information as trace output, select this option. This includes general system information.

  • SQL Statements—To generate SQL queries as trace output, select this option.

  • Java Methods—To generate all system.out output from the Mobile Server and Data Synchronization Java methods, select this option.

    Note: The Mobile Server automatically filters exceptions and errors as trace output at the Mandatory level.

3.1.2 Data Synchronization Tracing

The administrator can turn on tracing for components involved in the synchronization phase, including MGP functions.

  1. From either the home page or the Administration page for the Mobile Server, select Data Synchronization in the Components section, as shown in Figure 3-2.

    Figure 3-2 Mobile Server Job Scheduler and Data Synchronization Components

    Mobile Server Components
    Description of "Figure 3-2 Mobile Server Job Scheduler and Data Synchronization Components"

  2. Select Administration off of the Data Synchronization home page.

  3. Select Trace Settings, which displays all five components for which you can enable tracing, as shown in Figure 3-3. For a description of each component, see Section 3.1.2.1, "Description of the Five Data Synchronization Components".

    Figure 3-3 The Trace Components for the Data Synchronization

    Data Synchronization components
    Description of "Figure 3-3 The Trace Components for the Data Synchronization"

  4. Select the component for which you want to enable tracing, which brings up the trace configuration screen, as shown in Figure 3-4.

    Figure 3-4 Data Synchronization Component Trace Configuration

    Configure Data Synchronization component tracing
    Description of "Figure 3-4 Data Synchronization Component Trace Configuration"

    • In the Filter section, select the required Level and Type. To specify a trace filter for users, enter comma separated user names in the Users field.

      Table 3-2 Data Synchronization Component Trace Level and Type

      Filter Description

      trace level, where each level includes the previous levels as well.

      OFF: no tracing enabled.

      MANDATORY: Mandatory messages only, such as program exceptions.

      WARNING: Warning messages.

      NORMAL: Normal messages of which the user must be informed.

      INFO: Informational messages, such as synchronization timing, MGP apply, MGP compose, and MGP status.

      CONFIG: Configuration messages, such as JDBC driver version.

      FINEST: Developer level of tracing.

      ALL: Logs messages for all trace levels.

      trace type

      SQL: SQL-related messages only, such as SQL statements.

      TIMING: Timing data only. Note: This option is trace level sensitive. For MGP Cycle time and Synchronization time, use the Trace Level INFO option with the TIMING option on the MGP and SYNC components respectively.

      DATA: Data only.

      RESUME: Logs messages with Reliable Transport.

      FUNCTION: Displays the program flow by logging methods such as Entry, Exit or Invoke. For Long methods, this option logs the method entry or exit; which is a simple invoke log.

      GENERAL: Logs messages that do not belong to any of the above listed trace types. Note: This type is trace level sensitive.

      ALL: This option generates logs of all trace types.

      Note:

      You can set these parameters within the webtogo.ora file in the CONSOLIDATOR section. See Section A.6, "[CONSOLIDATOR]" in the Oracle Database Lite Administration and Deployment Guide for more details on these parameters.

    • In the Destination section, select Local Console to receive the trace file to the same console as the General tracing is using. If the console is not open, then these messages are sent to the same place that the General tracing is directed. See what the Destination is configured to in Figure 3-1 to determine where these messages are directed.

      To send trace information to a file, select the File option. The file name is generated based upon the session id. You can configure the file size in MB and the files allowed (pool number). For example, if you set the pool size to 10, then when a trace file hits the maximum size in MB, then a new file is opened and the trace output is written to the new file. This continues until all 10 files of the maximum size exist. At this point, the first file is deleted and a new file is started to contain the trace output. This enables you to manage the amount of disk space that the trace files can use.

  5. To implement the modified values, click OK. To retain existing values, click Cancel.

To view trace files, navigate to the Data Synchronization page. Select Administration. Select Trace Files and the Trace Files screen appears, as shown in Figure 3-5.

Figure 3-5 Viewing Data Synchronization Trace Files

View Data Synchronization trace files
Description of "Figure 3-5 Viewing Data Synchronization Trace Files"

  • To view a trace file, select the trace file name or click the Select button next to the trace file name and click View.

    Note:

    When you view the trace file online, it truncates the file to 10,000 lines. To view the whole trace file, download the file and view it using any text editor.

  • To download or delete a trace file, click the Select button next to the trace file name and click either Download or Delete.

  • If there are too many files to view on a page, you can search by entering the name of the trace file in the Search field and clicking Go.

3.1.2.1 Description of the Five Data Synchronization Components

There are five components that you can turn on to describe what is happening in the synchronization process, as described in the following sections:

3.1.2.1.1 MGP

You can trace the MGP process. However, if an MGP Cycle ID is not yet available, then tracing is enabled by the configuration of the GLOBAL component. If the trace destination is to be written to a file, then all of the generated logs are recorded in a log file named MGP_<cycle_id>.log.

3.1.2.1.2 MGPAPPLY

This refers to the APPLY phase in the MGP process. However, between the beginning of the APPLY phase till the availability of the MGP Client ID, tracing is enabled by the configuration of the component MGP. If tracing is sent to a file, then all messages are written to a file named MGPAPPLY_<client_id>_<cycle_id>.log.

3.1.2.1.3 MGPCOMPOSE

This refers to the COMPOSE phase in the MGP process. Similar to the MGPAPPLY phase where the Client ID is not yet available, tracing is enabled by the configuration of the component MGP. If tracing is sent to a file, then all messages are written to a file named MGPCOMPOSE_<client_id>_<cycle_id>.log.

3.1.2.1.4 SYNC

This refers to the server-side synchronization process. When a Sync session ID is not yet available, tracing is enabled by the configuration of the GLOBAL component. If the trace destination is set to file, then the messages are written to a file named SYNC_<cycle_id>.log. When the Client ID becomes available, the file is renamed to SYNC_<client_id>_<cycle_id>.log.

3.1.2.1.5 GLOBAL

This component logs tracing messages that are not specific to any of the above listed components. This component also includes logs that are generated during the execution of the ConsolidatorManager APIs. If the trace destination is set to file, then the messages are written to a file named GLOBAL_<file_number>.log.

3.2 Enable Tracing on Mobile Clients

You can also enable tracing on your Mobile client through one of the following methods:

3.2.1 Turn on Tracing using the Mobile Client WEBTOGO.ORA File

You can enable tracing through the DEBUG section in the webtogo.ora file on your Mobile Client. This is only valid for Mobile Client for the Web (Web-to-Go), Branch Office, andBC4J clients. Restart your Mobile client after modifying the webtogo.ora file to enable tracing.

See Section A.3, "[DEBUG]" in the Oracle Database Lite Administration and Deployment Guide for a full description of the trace parameters. Each trace parameter matches the fields displayed on the General trace settings screen for the Mobile Server, as shown in Figure 3-1.

3.2.2 Turn on Tracing using the -d0 Option for Web-to-Go Clients With the WEBTOGO Executable

If you want to enable tracing quickly to a console window on the Web-to-Go Mobile client, execute the Mobile client webtogo command with the -d0 option. With the -d0 option, tracing is enabled and printed to a console window. The level of tracing shown is indicated by the TRACE_LEVEL parameter in the DEBUG section of the webtogo.ora file. All other DEBUG parameters are ignored in this situation. In order to start the Mobile client with the -d0 option, you must first stop your existing client.

You can only use this type of tracing for Mobile Client for the Web, Branch Office, and BC4J.

For more information on configuring the TRACE_LEVEL parameter in the webtogo.ora file, see Section A.3, "[DEBUG]" in the Oracle Database Lite Administration and Deployment Guide.

3.2.3 View Device Logs

Each Mobile device maintains a log of the activity that it generates. See Section 8.4.7, "Viewing Device Logs" in the Oracle Database Lite Administration and Deployment Guide for more information.

3.3 Enabling Tracing in the Client-Side Oracle Lite Database

The Oracle Lite database is used in conjunction with other products such as Oracle forms, SQLJ, Web Servers, and OC4J. When an unexpected error is reported by the software system, users need to identify the location and cause of the error. Errors can be caused due to problems in the application code, Oracle tools—such as forms, SQLJ, OC4J—or in the Oracle Lite database. Errors also occur in simple environments where a user application talks directly to the Oracle Lite database through JDBC or ODBC drivers. It may not be obvious which component is at fault—whether it is the user application, JDBC or ODBC drivers, or the core database runtime system.

If the optimizer spends too much time evaluating alternative plans or collecting index statistics, a query may take a long time for compilation. If the execution plan selected by the optimizer is not optimal, the query may also take a long time during execution. Based on these criteria, the tracing facility provides the compilation time and the execution plan.

The following sections describe how to set and use tracing.

3.3.1 Enabling Trace Output

To enable Trace output, include the following line in the POLITE.INI configuration file:

OLITE_SQL_TRACE= yes

Note:

Any value other than "yes" disables the tracing feature. The parameter value is checked once during database startup. Hence, users must set this value before connecting to the database.

When you enable tracing, the trace information is dumped to a file named oldb_trc.txt in the current working directory of the database process. If the file already exists, then the trace output is appended to the end. If it does not exist, then a new file is automatically created. For a database service on Windows or the Oracle Lite database daemon for a Linux platform, the current working directory is specified by the wdir parameter during startup of the database service or daemon.

Note:

To implement the tracing feature, the database process must contain permissions to create the trace file in the current working directory.

3.3.2 Description of Trace Information

The following trace information is provided:

Table 3-3 Trace Output

Trace Output Description

Statement Text

Each time a SQL statement is prepared, its text is dumped into the trace file. The SQL statement itself is output without any formatting. If a SQL statement contains a new line character, it is also included in the SQL statement output.

Compilation Time

After the SQL statement is compiled, the compilation time is printed.

Execution Plan

If there are no errors, the execution plan is printed when available. Only statements that contain a WHERE clause generate an execution plan. The printed plan contains the execution order of tables for each sub-select.

Bind Value

If a SQL statement contains markers, then the bind value is printed for every line. Each value for the marker or bind variable is printed on a separate line in the following format.

Marker [<number>]: <Value>

Where, <number> is the number of the marker and <value> denotes the value of the marker before execution.

Temporary Table Created

Each time a temporary table is created, its name is dumped into the trace file.

Table Access

Each time a table is accessed, the following information is dumped into the trace file:

  • Table Name: The name of the table been accessed is dumped into the trace file.

  • Access Method: The access method used by the database is dumped into the trace file.

For a description of how this information is presented, see Section 3.3.2.1, "Table Name Output".

Temporary Table Sorted

Each time a temporary table is sorted, its name and sorting time (in milliseconds) are dumped into the trace file.

First Fetch Time

If the SQL statement is a SELECT statement, the time spent on fetching the first row is dumped into the trace file.

Tid

The thread ID is dumped into the trace file in front of some of the dumped information. The thread is displayed in the following format:

Tid: <thread id>

3.3.2.1 Table Name Output

The name of the table that is currently being accessed and the method used to access the table are printed in the following formats.

  • If the table is accessed sequentially, the format is:

    Table Name: <table name>

    Access Method: Sequential

    Where <table name> is the name of the table being accessed.

  • If indices are used, the format is:

    Table Name: <table name>

    Access Method: Term[<number>], Index No: <index number>, IndexName: <index name>

    <table name> is the name of the table being accessed.

    Term[<number>] is the internal representation of the conjunct search conditions in the WHERE clause.

    <index number> is the index number. Each index has an unique number in the database.

    <index name> is the name of the index if any.

3.4 Viewing the Log Files From the Application Server

Since Mobile Server uses OC4J as its application server, you can view the following log files to debug problems.

  • Viewing OC4J server level output messages.

    <OC4J_HOME>\log\server.log

  • Viewing HTTP requests handled by the server.

    <OC4J_HOME>\log\http-web-access.log

  • Viewing exceptions or errors that are handled by OC4J.

    <OC4J_HOME>\application-deployments\webtogo\application.log

  • Viewing the file trace_sys1.log and other log files that are generated by the Mobile Server in the same directory.

    <OC4J_HOME>\application-deployments\webtogo\trace_sys1.log