Productivity Tools and Services

PSTrace Viewer (PSTV) 1.004

April 2005
PSTrace Viewer (PSTV) 1.004

PeopleBooks Contributors: Teams from PeopleSoft Product Documentation and Development.

Copyright © 2005 PeopleSoft, Inc. All rights reserved.

All material contained in this documentation is proprietary and confidential to PeopleSoft, Inc. (“PeopleSoft”), protected by copyright laws and
subject to the nondisclosure provisions of the applicable PeopleSoft agreement. No part of this documentation may be reproduced, stored in a
retrieval system, or transmitted in any form or by any means, including, but not limited to, electronic, graphic, mechanical, photocopying,
recording, or otherwise without the prior written permission of PeopleSoft.
This documentation is subject to change without notice, and PeopleSoft does not warrant that the material contained in this documentation is
free of errors. Any errors found in this document should be reported to PeopleSoft in writing.
The copyrighted software that accompanies this document is licensed for use only in strict accordance with the applicable license agreement
which should be read carefully as it governs the terms of use of the software and this document, including the disclosure thereof.
PeopleSoft, PeopleTools, PS/nVision, PeopleCode, PeopleBooks, PeopleTalk, and Vantive are registered trademarks, and Pure Internet
Architecture, Intelligent Context Manager, and The Real-Time Enterprise are trademarks of PeopleSoft, Inc. All other company and product
names may be trademarks of their respective owners. The information contained herein is subject to change without notice.

Open Source Disclosure

PeopleSoft takes no responsibility for its use or distribution of any open source or shareware software or documentation and disclaims any and
all liability or damages resulting from use of said software or documentation. The following open source software may be used in PeopleSoft
products and the following disclaimers are provided.
Apache Software Foundation
This product includes software developed by the Apache Software Foundation (http://www.apache.org/). Copyright (c) 1999-2000 The Apache
Software Foundation. All rights reserved.
THIS SOFTWARE IS PROVIDED “AS IS” AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN
NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.

OpenSSL
Copyright (c) 1998-2003 The OpenSSL Project. All rights reserved.
THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT “AS IS” AND ANY EXPRESSED OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR ITS CONTRIBUTORS BE LIABLE FOR ANY
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

SSLeay
Copyright (C) 1995-1998 Eric Young. All rights reserved.
THIS SOFTWARE IS PROVIDED BY ERIC YOUNG “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT
NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.

Loki Library
Copyright (c) 2001 by Andrei Alexandrescu. This code accompanies the book:

Alexandrescu, Andrei. “Modern C++ Design: Generic Programming and Design Patterns Applied”. Copyright (c) 2001. Addison-Wesley.
Permission to use, copy, modify, distribute and sell this software for any purpose is hereby granted without fee, provided that the above
copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation.
PSTrace Viewer User Guide Version 1.004

PSTrace Viewer User Guide Version 1.004 Release April 2005

Overview of PSTrace Viewer .................................................................................................................... 2

Getting Started....................................................................................................................................... 2
Execution Path ................................................................................................................................... 3
Statistics ............................................................................................................................................. 5
SQL Statements ................................................................................................................................. 9
Database Connections ..................................................................................................................... 10
Trace Settings...................................................................................................................................... 12
PeopleCode Trace Settings ............................................................................................................. 13
SQL Trace Settings .......................................................................................................................... 14
Saving Results ..................................................................................................................................... 15
Index .................................................................................................................................................... 16

PeopleSoft Proprietary and Confidential Page 1

PSTrace Viewer User Guide Version 1.004

Overview of PSTrace Viewer

PSTrace Viewer (PSTV) displays a log file as a visual tree in an easy-to-use interface that lets you filter
and sort trace file data and helps you identify performance issues and bugs using the following two main
sections:
• Execution path—Visual display.

• Statistics—At-a-glance performance analysis for PeopleCode and SQL.

Development, PRD, and QA use PSTrace Viewer to perform the following functions:
• View and parse a PeopleSoft Trace file

• Save parsed and statistical information

• Filter information

• Identify possible performance issues

• Execute SQL query statements from trace files

• Provide statistics to help developers improve code

• Set and modify desired trace logging settings on a specified application and server

Getting Started
To open a Trace file:
1. (Optional) To add PeopleTools SELECT statements to the PSTrace Viewer displays that are, by
default, excluded when a Trace file opens, on the File menu, click Include PeopleTools SELECT.
2. (Optional) On the File menu, click Reread.
3. On the File menu, click Open.
4. Locate the desired PeopleCode Trace file.
5. Click Open, to display the Trace file’s execution path, statistics, and SQL statements.
You can run an Explain Plan on SQL defined in the trace file. Explain Plans are executed on the
following supported databases:
• MS SQL Server

• Oracle

• Sybase

• Informix

• DB2/Unix

Additionally, you can execute SQL defined in the trace file. SQL are executed as queries on all of the
supported databases previously listed.

PeopleSoft Proprietary and Confidential Page 2

PSTrace Viewer User Guide Version 1.004

Note. It may take several minutes to open or reread a Trace file, depending on its size.

Execution Path
The default Execution Path view displays the Trace file in the following two formats:
• A Tree structure in the top pane

• A log view (Trace file without any changes or formatting) in the second pane

PSTrace Viewer - Execution Path window

Selecting a node in the tree view automatically highlights the corresponding row in the log view. The
opposite (clicking a line in the log view) does not highlight a corresponding row in the tree view, because
many lines in the log view do not have entries in the tree view.

PeopleSoft Proprietary and Confidential Page 3

PSTrace Viewer User Guide Version 1.004

Trace log entries display as the following icons in the tree view:
Indicates a PeopleCode Event.

Indicates External/Public Calls.

Indicates Internal/External Function Calls.

Indicates SQL Statements.

To expand or collapse all displayed Tree View nodes, on the View menu, click Expand All (Ctrl+E) or
Collapse All (Ctrl+L) respectively.
To execute a Tree view SQL statement against the specified database, double-click it (or pressF5).
Connecting to a database is not required to view trace logs. If you did not specify a database (refer to the
Getting Started and the Database Connections sections of this guide for more details), when you double-
click the SQL node, the Connect to database window displays for you to enter the Server, Database, User
ID and Password. The name of the database that PSTrace Viewer is currently connected to displays at
the bottom of the PSTrace Viewer window.
To disconnect from the displayed database, on the File menu, click Disconnect.
To find a search string in the log view and highlight the corresponding node in the Tree view, on the Edit
menu, click Find, and then click the Find window to view the selected row.
Right-clicking a line in the top pane’s Tree view displays a menu of varying commands, depending on the
node type. The Find in… options takes you directly to the lines relating to the selected node in the various
views.

PeopleSoft Proprietary and Confidential Page 4

PSTrace Viewer User Guide Version 1.004

Statistics
Click Statistics, and then click the right or left arrows on the right side of the window to scroll through all
eight sections.

PSTrace Viewer - Statistics window

Click any column heading to sort the information by that column.
You can copy information by clicking Copy from the Edit menu (or by clicking Copy Without Statistics from
the Edit menu). To delete, on the Edit menu click Delete; however, this command hides the selected
statistics until you reread the Trace file and does not update the original Trace file.

PeopleSoft Proprietary and Confidential Page 5

PSTrace Viewer User Guide Version 1.004

To find information, first select a line to set the focus to the desired view, and then click Find on the Edit
menu.
Total Time Select a line to display the duration, which is execution
time plus fetch time.

# of Calls Displays the number of times the SQL was executed.

# of Fetch Displays the number of rows returned.

Exec Time Displays the SQL (or PeopleCode) execution time.

Fetch Time Displays the time used to return SQL results.

Right-clicking a line displays a menu with the following two commands:

• Trace File/Execution Path—Finds the selected entry in the Execution Path view.

• Show Details—Opens the Details view that displays an individual line for each execution (Double-
clicking a row also opens the Details view.).

Details window
Click Find in Log to find the specific execution in the Log view of the Execution Path. Clicking a column
heading sorts the list by that column.
SELECT Statements Displays the total time, number of calls, number of
fetches, execution time, fetch time, and the FROM
segment of all expected SQL SELECT statements.
Double-clicking a line opens the Details view that lists an
individual line for each execution.

DELETE Statements Displays total time, number of calls, and the FROM
segment of the DELETE SQL statement.

INSERT Statements Displays total time, number of calls, and the FROM
segment of the SQL INSERT statements.

UPDATE Statements Displays the same information as both the INSERT and
DELETE sections (total time), number of calls and the
FROM segment of the SQL.

EVENTS Displays each called PeopleCode event, as well as the

number of calls and total time used.

PeopleSoft Proprietary and Confidential Page 6

PSTrace Viewer User Guide Version 1.004

EXTERNAL Calls Displays total time, number of calls, the function name,
and the PeopleCode event for application-specific
External Calls.

Internal/External Calls Displays the number of calls, the type of function, and the
PeopleCode event for the External Calls described earlier,
as well as any internal calls.

Totals Displays the total amount of time, number of functions,

and number of calls for each section described earlier.

There is no detail view or right-click menu available. The

information displayed is divided into the following three
horizontal panes:

• Total Times for Level-One nodes

• SQL Statistics
• Function Statistics

PSTrace Viewer - Statistics: Totals

PeopleSoft Proprietary and Confidential Page 7

PSTrace Viewer User Guide Version 1.004

Total Times for Level-One Displays the total time for Level 1 duration.
Nodes
Additionally, this pane also displays the total Level 1 times
for SQL Selects, Inserts, Updates, and Deletes, as well as
the Level 1 times for Internal/External Calls, External
Calls, and PeopleCode Events. These totals only include
events and SQL from Level 1; the system does not add to
these totals any nested SQL or event times.

SQL Statistics Displays a summary of all SQL statistics (from all levels of
the log).

In addition to Number of Statements, Number of Calls,

and Total Time, PSTrace Viewer displays the Minimum,
Maximum, and Average Time for Select, Insert, Update,
and Delete statements.

Function Statistics Displays totals for External Calls, PeopleCode Events,

and Internal/External Calls including the Number of
Functions, Number of Calls, Total time for each area,
Minimum and Maximum times for each area, and the
Average time.

PeopleSoft Proprietary and Confidential Page 8

PSTrace Viewer User Guide Version 1.004

SQL Statements
Click SQL Statements to work with SQL statements and statistics related directly to them. Right-click the
individual lines to display a context-sensitive menu.

PSTrace Viewer - SQL Statements window

PeopleSoft Proprietary and Confidential Page 9

PSTrace Viewer User Guide Version 1.004

All SQL Statements Displays statistics about all SQL statements in the Trace
file.

Double-click any line to execute the SQL. If you did not

establish a database connection, in the window that
displays, enter a server, database, user ID, and password.
Additionally, press F5 to execute the selected SQL
statement.

The system displays the line number (in the Trace log file),
total time, number of fetches, FROM clause, WHERE
clause, and full SQL. Clicking the header of any column
sorts the data by the selected column.

The system includes insert, update, and delete SQL

statements; so use caution to avoid executing unwanted
SQL statements that could modify data in your specified
database.

SELECT by unique WHERE Displays all SQL Select statements with unique WHERE
clause clauses.

The system does not include insert, update, and delete

statements. The systems does display total time, number
of calls, the FROM clause, the WHERE clause, and
complete SQL for each row. Double-clicking a row opens
a Details window displaying individual statistics for each
line that contain that specific WHERE clause. Statistics
available in the detail view include line number, duration,
execution time, fetch time, and number of fetches.

SELECT by unique FROM Displays the same information as the SELECT by unique
clause WHERE clause except, instead of being grouped by
WHERE clauses, the data is grouped by FROM clauses.

Database Connections
PSTrace Viewer supports the following for all database interactions:
• Query Execution—PSTV executes queries against the connected database. Successful and failed
queries output their results to the SQL window (the pane at the bottom of PSTV that can optionally be
hidden).

• Execution Plans—PSTV can determine execution plans for a query against the connected database.
Successful and failed queries output their results to the SQL window.

PeopleSoft Proprietary and Confidential Page 10

PSTrace Viewer User Guide Version 1.004

To execute queries or display execution plans:

1. Select either the Execution Path or the SQL Statements tab.

2. Do one of the following:

• To perform a query execution, right-click, and then click Execute SQL Statement.
(Alternatively, from the SQL menu, click Execute SELECT Statements)

• To display an execution plan, right-click, and then click Display Execution Path.
(Alternatively, from the SQL menu, click Show Execution Plans)
3. If you are not already connected to a database, from the Select Database Connection window that displays,
enter the desired connection criteria as in the following example:

Select Database Connection window (PTSSql Components Login)

Connection Type: Select from the following supported databases:

• MS SQL Server
• Oracle
• Sybase
• Informix
• DB2/Unix
Server Name: Enter the name of the server that you want to use.

User ID: Enter your user ID.

Password: Enter your password.

Save Password Select to save your password for future logins.

PeopleSoft Proprietary and Confidential Page 11

PSTrace Viewer User Guide Version 1.004

Connect Click to connect to the selected database using the

platform that you specified.

When you click Connect, the system automatically saves

the criteria that you defined. You can access this
information in the future by clicking the Predefined button.

Cancel Click to cancel and close the connection window.

Predefined Click to display and select from a list of previously defined

connections.

Select Database Connection - Predefined Connections window

Trace Settings
In addition to viewing trace files, use PSTrace Viewer to set the desired trace settings to create a trace
file. On the Tools menu, click Settings to open the Trace Settings dialog. PSTrace Viewer asks you to
select a PeopleTools installation directory and a valid Domain name. Without a valid Tools installation
location and Domain name, you are unable to modify any trace settings.
The settings displayed in the Trace Settings dialog are NOT the current selections for the specified
Domain. They are the options that you last selected in the dialog box.
The displayed selections correspond to available settings for the PeopleCode and SQL Tracing in the
psappsrv.cfg file. Selecting the desired settings and clicking OK in the PSTrace Viewer Trace Settings
dialog updates the psappsrv.cfg file for the selected PeopleTools installation/Domain.
For the settings to take affect, log out of PIA, and then log back in. In some cases, you must restart the
application server.

PeopleSoft Proprietary and Confidential Page 12

PSTrace Viewer User Guide Version 1.004

Trace Settings window

PeopleCode Trace Settings

Trace Start of Programs Select to display the starting and ending points of the
program.

Trace External Function Select to display calls to application-written functions.

Calls (Application written functions means functions written by a
product developer vs. the PeopleTools functions.)

Trace Internal Function Select to display calls to PeopleTools built-in function

Calls calls.

Note. These check boxes directly correspond to the PeopleCode Tracing Bitfield options available in
the psappsrv.cfg file.

Bit Type of Tracing

64 Trace start of programs.
128 Trace external function calls.
256 Trace internal function calls.
TracePC=XXX TracePCMask=4095

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

PeopleSoft Proprietary and Confidential Page 13

PSTrace Viewer User Guide Version 1.004

SQL Trace Settings

Trace SQL Statement Select to display the SQL statement.

Trace SQL Statement Select to display Bind values for SQL statements that
Variables have parameter markers.

Trace SQL Connect, Select to display SQL Cursor activities.

disconnect, commit and
rollback

Trace Row Fetch Select to display Fetch call for the Select Statement.
Occurrence

All Other API Calls Except Select to display other API calls (such as Execute,
ssb Describe, and so on.).

Note. Because selecting this check box is required for

PSTrace Viewer to correctly parse log files, it is
automatically set in PSTrace Viewer when you select
Enable SQL Logging and does not display as an option for
users to choose.

Note. These check boxes directly correspond to the SQL Tracing Bitfield options available in the
psappsrv.cfg file.

Bit Type of Tracing

1 SQL statements
2 SQL statement variables
4 SQL connect, disconnect, commit and rollback
8 Row Fetch (indicates that it occurred, not data)
16 All other API calls except ssb
TraceSql=XX TraceSqlMask=12319

Warning! Trace creates large files fast. Be sure to turn the Trace Settings off once the desired Trace file
has been created.

PeopleSoft Proprietary and Confidential Page 14

PSTrace Viewer User Guide Version 1.004

Saving Results
To save all of the statistics provided by PSTrace Viewer as well as the tree structure of the Trace file:
1. On the File menu, click Save Results As.
2. Select a location and file name for the results file, which you should save as an Excel document.
3. Click Save to save the file and display a confirmation message.
The saved Excel document contains 12 worksheets—one for each of the information views available in
PSTrace Viewer. The tab name corresponds to which segment of information is contained.

Note. If you delete any rows of statistics, those rows are NOT included in the saved results file.

PeopleSoft Proprietary and Confidential Page 15

PSTrace Viewer User Guide Version 1.004

Index
bitfield options executing SQL statements, 11, 12
PeopleCode tracing, 14 saving results, 16
SQL tracing, 15 search string, 5
database SQL Statements window, 10
connecting to, 5, 12 Statistics window, 6
disconnecting from, 5 copying information, 6
platforms supported, 12 deleting information, 6
Details window, 7 finding information, 7
Execution Path window, 3 scrolling through sections, 6
connecting to a database, 5 setting focus to desired view, 7
disconnecting from a database, 5 sorting information, 6
displaying menu in tree view, 5 totals, 8
executing a tree view SQL statement, 5 trace log icon descriptions, 3
expanding or collapsing tree view nodes, 5 Trace Settings window, 13, 14
finding a search string, 5 modifying, 13
trace log icon descriptions, 3 PeopleCode trace settings, 14
execution plans PeopleCode tracing bitfield options, 14
displaying execution plans for SQL SQL trace settings, 15
statements, 11, 12
trace file, 13
getting started, 2
updating the psappsrv.cfg file, 13
multi-database functionality
tree view
platforms supported, 12
collapsing nodes, 5
opening a trace file, 2
displaying menu in, 5
overview, 2
expanding nodes, 5
psappsrv.cfg file, 13
windows
PSTrace Viewer
Details, 7
getting started, 2
Execution Path, 3
overview, 2
SQL Statements, 10
query execution
Statistics, 6

PeopleSoft Proprietary and Confidential Page 16