Tracing, Logging, and Debugging

This chapter discusses how to:

• Set up the PeopleCode Debugger.

• Enable PeopleCode tracing.

• Enable SQL tracing.

• Enable IDDA logging.

See Also

Trace Options

Specifying Trace Settings

Setting Up the PeopleCode Debugger

This section discusses how to:

• Debug for a two-tier connection.

• Debug for a three-tier connection.

• Use the PeopleCode Debugger.

Note. PeopleCode debugging is not supported on z/OS.

You can debug the PeopleCode program configurations of a two-tier connection to the database or a three-tier connection to the database.

Note. When you debug PeopleCode with an application server, Application Designer should be run in three-tier mode. PeopleCode debugging by using a two-tier PSIDE and an application server is not supported on multi-homed (multiple Internet Protocol address) workstations.

Debugging for a Two-Tier Connection

Debugging in two-tier connections involves connecting directly to the database, not through the application server. Use this method to debug two-tier Windows applications.

Note. By default, the port number that the PeopleCode debugger uses is 9500. Unless this port number is being used by another application, you do not need to alter any environment settings, and after you sign on to the database, you are able to debug PeopleCode.

If you need to change the PeopleCode Debugger port settings, complete the following procedure.

To change the default PSDBGSRV listener port number:

1. Open PeopleSoft Configuration Manager.

2. Select the Trace tab.

3. Locate the PeopleCode Debugger section, and make sure that the default value for the Local PSDBGSRV Listener Port is suitable for the system.

   For example, make sure that no other applications are configured to listen on the default port number (9500). If so, you must assign a port number that is not being used.

Note. If you're using a personal firewall, you must configure it to enable data packets to flow through the PSDBGSRV listener port. If you can't configure your firewall appropriately, you must shut it down while performing PeopleCode debugging.

Debugging for a Three-Tier Connection

Use three-tier debugging to debug three-tier Windows applications and PeopleSoft Internet Architecture (PIA) applications. For three-tier debugging, use PSADMIN to ensure that the following items are set:

• The appropriate PSDBGSRV listener port is specified in the PeopleCode Debugger section of PSADMIN.

• At least two PSAPPSRV processes are configured to boot in the domain with the service timeout parameter set to zero.

• Enter y for yes at the Enable PSDBGSRV Server Process prompt at the end of the PSADMIN interface.

Debugging on a Multi-Homed System

If you're debugging on a multi-homed (multiple IP address) system, you must explicitly specify an IP address in the Workstation Listener section of the PSADMIN configuration, rather than %PS_MACH%. The address you specify must be one by which the application server identifies the machine on which you're doing the debugging. This ensures that the workstation listener monitors requests from the correct location.

See Workstation Listener Options.

Setting the PSDBGSRV Listener Port

In the PeopleCode Debugger section of PSADMIN make sure that the value that is assigned to the PSDBGSRV listener port is not already in use by another application or listener on the application server. The default value is 9500. If the default is not acceptable, assign a suitable value to the parameter. If it is acceptable, no changes are required.

For example,

Values for config section - PeopleCode Debugger
    PSDBGSRV Listener Port=9500

Do you want to change any values (y/n)? [n]:

Consider the following when debugging PeopleCode:

• If multiple application server domains are running on a single, physical machine, each domain needs to use different debugging port numbers.

  Otherwise, there is contention for the PSDBGSRV listener port value. This is the same principle that requires each application server domain on a server to have unique workstation listener port numbers.

• When you are not debugging, turn off (set to 0) the Enable Debugging parameter.

  The debugging mode results in an unavoidable amount of overhead, which can degrade performance.

• Regarding performance, do not perform debugging on a production domain.

  Debugging should be performed on a designated testing domain only.

Enabling Multiple PSAPPSRV Server Processes

The minimum requirements for PeopleCode debugging are:

• Two PSAPPSRV server processes are configured to boot in the domain.

• The Service Timeout value in the PSAPPSRV configuration section must be set to 0.

For the debugger to work, it has to run in parallel with the application that it's debugging. Suppose that the domain has only one PSAPPSRV server process running. In this case, the PSAPPSRV can process the requests of only one component at a time, and therefore debugging is not possible. Debugging involves two items, the debugger (PSDBGSRV) and the PSAPPSRV server process that is running the application PeopleCode.

Provided that you have two PSAPPSRV server processes configured; one PSAPPSRV handles the debugger program, while the other handles the application that you're stepping through with the debugger. In this case, the two programs run in parallel, which enables interactive debugging.

The configuration templates that PeopleSoft delivers all have at least two PSAPPSRV processes. However, if you are using a custom template, make sure that you configure the domain to start two PSAPPSRV processes prior to debugging. To do this, in PSADMIN set the Min Instances parameter in the PSAPPSRV section to 2.

The following example shows a sample PSAPPSRV section properly configured for debugging PeopleCode:

Values for config section - PSAPPSRV
    Min Instances=2
    Max Instances=2
    Service Timeout=0
    Recycle Count=0
    Allowed Consec Service Failures=0
    Max Fetch Size=5000

Do you want to change any values (y/n)? [n]:

When configuring the PeopleCode debugger:

• PeopleSoft recommends using the Developer configuration template because this template, by default, provides two PSAPPSRV server processes and has service timeout set to zero.

• PeopleSoft recommends using a simple configuration where you are assured that the server that Application Designer connects to is the same server that the application you are debugging is running on.

Note. If you do not set the settings for PSAPPSRV correctly (at least two PSAPPSRV processes), PSADMIN automatically sets these values to comply with the minimum requirements when you enable PeopleCode Debugging (as discussed in the next section).

Note. When you enable the PeopleCode Debugger (PSDBGSRV), service timeout settings for server processes are set to zero (0) by the system, overriding any previous settings you may have made in PSADMIN. For example, if the service timeout settings for the PSAPPSRV service process are set to 300 prior to enabling the debugger, after you enable the debugger, the service timeout value will be zero (0). After using the debugger, you need to reset your service timeout settings to the desired values. Before enabling the debugger, it is recommended that you make a backup of your configuration file or make note of your service timeout settings.

Requesting a PSDBGSRV Server Process

After you specify the settings by using PSADMIN, the system prompts you with a series of options, such as setting up messaging server processes, enabling Jolt, and so on.

When you're prompted to enable the PSDBGSRV, enter y. Y appears in the Developer template by default.

Using the PeopleCode Debugger

After the system is configured properly, using the PeopleCode debugger is just a matter of signing on to the PeopleSoft system and entering the PeopleCode Debugger mode in Application Designer.

Note. You must use a unique user ID when you're performing PeopleCode debugging, as opposed to using a shared user ID, such as those that PeopleSoft delivers, for example QEDMO, PS, or VP1. Shared IDs are likely to be used by others that are connecting to the same test database, which can affect debugging.

Configuring PeopleCode Trace

Select PeopleTools, Utilities, Debug, Trace PeopleCode to access the Trace PeopleCode page.

You use this page to change the PeopleCode tracing options while online. This page does not affect trace options that are set in PeopleSoft Configuration Manager. Use Trace PeopleCode to create a file displaying information about PeopleCode programs processed from the time that you start the trace.

Note. The Trace PeopleCode Utility decreases system performance because of the overhead that occurs during the monitoring and recording of all PeopleCode actions.

The check boxes on this page correspond to the options on the Trace tab in Configuration Manager. However, the selections that appear on this page do not necessarily reflect those that are made in Configuration Manager. While the Configuration Manager settings are stored in the Windows registry and used at each signon, the settings in the Utilities page only apply to the current online session, and, once set, they override the Configuration Manager's settings.

The benefit of using this page to control PeopleCode tracing is that you can turn it on and off without having to restart PeopleTools, and without resetting the Configuration Manager settings. Keep in mind, though, your selections are not enabled until you save the page.

To enable/disable PeopleCode tracing while on line

1. Select PeopleTools, Utilities, Debug, Trace PeopleCode.

   The Trace PeopleCode page appears.

2. Select/deselect the desired Options.

3. Save the page.

   If you selected any of the check boxes, the system starts writing to the trace file.

See Also

Specifying Trace Settings

SetTracePC

Configuring SQL Trace

Select PeopleTools, Utilities, Debug, Trace SQL to access the Trace SQL page.

You use this page to change the SQL tracing options while you're online. Your Configuration Manager settings are not affected:

The check boxes on the Trace SQL page correspond to options on the Trace tab in the Configuration Manager. However, the selections that appear on this page do not necessarily reflect those that are made in the Configuration Manager. The displayed page selections are not enabled until you save the page.

To enable or disable SQL tracing while online:

1. Select or deselect the desired trace options.

2. Save the page.

   If you select any of the check boxes, the system starts writing to the trace file.

See Also

Specifying Trace Settings

SetTraceSQL

Enabling IDDA Logging

This section contains an overview and discusses how to:

• Enable IDDA logging.

• Work with IDDA functional categories.

• Configure logging options.

• Viewing log results.

Understanding IDDA Logging

System administrators typically use numerous monitoring and logging utilities to diagnose system issues and internet applications. Such logging utilities include:

• TCPMON

• ieHttpHeaders

• Access log

• Heap dump

• Thread dump

All of these utilities provide different information, but each helps an administrator gain insight and detailed information related to specific system behavior. PeopleSoft provides a variety of logging and tracing mechanisms as well, enabling you to gather vital information at various levels of the architecture, including database server, application server, web server, and so on.

The PeopleSoft Instrumented Development Diagnostic Aid (IDDA) logger, enables you to gather specific information about various areas within the PeopleSoft Internet Architecture and PeopleSoft Applications Portal, including:

• PeopleSoft Internet Architecture processing.

• Integration Broker.

• Reporting, Report Repository.

• Portal.

• Caching.

• File processing.

• Security, authentication.

• Performance Monitor.

• WSRP.

• Jolt.

Typically, administrators only run IDDA traces when instructed to do so by Oracle support contacts, looking for specific information. However, it can also be a useful troubleshooting tool.

Note. When ever tracing or logging is enabled, you should always expect a certain degree of performance degradation as the system incorporates the overhead involved with logging. Disable logging when you finish troubleshooting.

Enabling IDDA Logging

To enable IDDA logging:

1. Select PeopleTools, Web Profile, Web Profile Configuration, and open the current web profile.

2. Select the Custom Properties page.

3. Add a new row, and enter these values:

   Column	Value
   Property Name	IDDA
   Validation Type	Number
   Property Value	The sum of the bit values of the functional area(s) you want to log. For example, if you wanted to log PIA (1) and Portal (8), you enter 9.

4. Click Save.

5. Restart the PeopleSoft site.

Working with IDDA Functional Categories

The IDDA logger, gathers information for a wide range of technology within the PeopleSoft Internet Architecture. Depending on the needs of your troubleshooting, you can select different areas to log.

The different areas of technology are referred to as functional categories in the context of the IDDA logger. Each functional category is assigned a bit value (in a 32-bit space). When you enable IDDA logging, you enter specific bit values or the sum of the bit values of different areas.

The IDDA functional categories are:

The type of information included in the log message differs per category. The log message is free format and can display any information that helps troubleshooting for that particular area, such as error codes, exception messages, and so on.

Configuring Logging Options

Once you’ve enabled IDDA logging, you can modify configuration options in the logging.properties file, which you can find in these locations:

The relevant configuration properties are:

Viewing IDDA Logging Output

The output log files contain:

• Machine header information

• Log message information

Working with Machine Header Information

Each log file displays the following machine environment information at the top of each log file.

Working with Log Message Information

Each entry in the log file contains this information.

Viewing Log Contents

The log file is a tab-delimited text file and can be opened in any standard text editor, such as Notepad or Textpad. Because the output is tab-delimited, you can also use a spreadsheet application, such as Microsoft Excel, for more efficient analysis. For example, viewing the output within a spreadsheet enables you to apply filters to columns and only view specific log messages, which can be helpful with large files.