Previous Page TOC Index Next Page

SOLID Server DIAGNOSTIC TOOLS


SOLID Server provides several diagnostic tools for observing performance. These tools, SQL info facility and the EXPLAIN PLAN statement, are helpful in tuning your application and identifying inefficient SQL statements in your application.

SOLID Server provides also tools for tracing the communication between client and server and locating problems that may slow down your application. The Network trace facility can be used in the server end and the Ping facility in the client end.

Observing Performance

The SQL Info Facility

Run your application with the SQL Info facility enabled. The SQL Info facility generates information for each SQL statement processed by SOLID Server.

SQL Info levels

Info value

Information

0

no output

1

table, index, and view info in SQL format

2

SQL execution graphs

3

some SQL estimate info, Solid selected key name

4

all SQL estimate info, Solid selected key info

5

Solid info also from discarded keys

6

Solid table level info

7

SQL info from every fetched row

8

Solid info from every fetched row

The SQL Info facility is turned on by setting a non-zero value to the Info parameter in the [SQL] section of the configuration file. The output is written to a file named soltrace.out in the SOLID directory.

Example:

[SQL]

info = 1

The SQL Info facility can also be turned on with the following SQL statement (this sets SQL Info on only for the client that executes the statement):

SET SQL INFO ON LEVEL info-value FILE file-name

and turned off with the following SQL statement:

SET SQL INFO OFF
Example:
SET SQL INFO ON LEVEL 1 FILE ‘my_query.txt’

The EXPLAIN PLAN Statement

The EXPLAIN PLAN statement is used to show the execution plan that the SQL optimizer has selected for a given SQL statement. An execution plan is a series of primitive operations, and an ordering of these operations, that SOLID Server performs to execute the statement. Each operation in the execution plan is called a unit.

Unit

Description

JOIN UNIT

Join unit joins two or more tables. The join can be done by using loop join or merge join. Note that the join unit is generated also for queries that reference only a single table. In that case no join is executed in the join unit, the join unit just passes the rows without manipulating them.

TABLE UNIT

Table unit is used to fetch the data rows from a table. Table unit is always the last unit in the chain, since it is responsible for fetching the actual data from the index or table.

ORDER UNIT

Order unit is used to order rows for grouping or to satisfy ORDER BY. The ordering can be done in memory or using an external disk sorter.

GROUP UNIT

Group unit is used to do grouping and aggregate calculation.

The syntax of the EXPLAIN PLAN statement is:

EXPLAIN PLAN FOR sql-statement

Explain Plan Table Columns

The table returned by the EXPLAIN PLAN statement contains the following columns.

Column name

Description

ID

The output row number, used only to guarantee that the rows are unique.

UNIT_ID

This is the internal unit id in the SQL interpreter. Each unit has a different id. The unit id is a sparse sequence of numbers, because the SQL interpreter generates unit ids also for those units that are removed during the optimization phase. If more than one row has the same unit id it means that those rows belong to the same unit. For formatting reasons the info from one unit may be divided into several different rows.

PAR_ID

Parent unit id for the unit. The parent id number refers to the id in the UNIT_ID column.

JOIN_PATH

For join unit there is a join path which specifies which tables are joined in the join unit and the join order for tables. The join path number refers to the unit id in the UNIT_ID column. It means that the input to the join unit comes from that unit. The order in which the tables are joined is the order in which the join path is listed. The first listed table is the outermost table in a loop join.

UNIT_TYPE

Unit type is the execution graph unit type.

INFO

Info column gives additional info. It may contain e.g. index usage, the database table name and constraints used in the database engine to select rows. Note that the constraints listed here may not match those constraints given in the SQL statement.

The following texts may exist in the INFO column for different types of units.

Unit type

Text in Info column

Description

TABLE UNIT

<tablename>

The table unit refers to table <tablename>.

TABLE UNIT

<constraints>

The constraints that are passed to the database engine are listed. If for example in joins the constraint value is not known in advance, the constraint value is displayed as NULL.

TABLE UNIT

SCAN TABLE

Full table scan is used to search for rows.

TABLE UNIT

SCAN <indexname>

Index <indexname> is used to search for rows. If all selected columns are found from an index, sometimes it is faster to scan the index instead of the clustering key because the index has fewer disk blocks.

TABLE UNIT

PRIMARY KEY

The primary key is used to search rows. This differs from SCAN in that the whole table is not scanned because there is a limiting constraint to the primary key attributes.

TABLE UNIT

INDEX <indexname>

Index <indexname> is used to search for rows. For every matching index row, the actual data row is fetched separately.

TABLE UNIT

INDEX ONLY <indexname>

Index <indexname> is used to search for rows. All selected columns are found from the index, so the actual data rows are not fetched separately.

JOIN UNIT

MERGE JOIN

Merge join is used to join the tables.

JOIN UNIT

LOOP JOIN

Loop join is used to join the tables.

ORDER UNIT

NO ORDERING REQUIRED

No ordering is required, the rows are retrieved in correct order from the database engine.

ORDER UNIT

EXTERNAL SORT

External sorter is used to sort the rows. To enable external sorter, the temporary directory name must be specified in the Sorter section of the configuration file.

ORDER UNIT

FIELD <n> USED AS PARTIAL ORDER

Internal sorter (in-memory sorter) is used for sorting and the rows retrieved from the database engine are partially sorted with column number <n>. The partial ordering helps the internal sorter to avoid multiple passes over the data.

ORDER UNIT

NO PARTIAL SORT

Internal sorter is used for sorting and the rows retrieved in random order from the database engine.

Example 1

EXPLAIN PLAN FOR SELECT * FROM TENKTUP1 WHERE UNIQUE2_NI BETWEEN 0 AND 99;

ID

UNIT_ID

PAR_ID

JOIN_
PATH

UNIT_
TYPE

INFO

1

2

1

3

JOIN UNIT


2

3

2

0

TABLE UNIT

TENKTUP1

3

3

2

0


FULL SCAN

4

3

2

0


UNIQUE2_NI <= 99

5

3

2

0


UNIQUE2_NI >= 0

6

3

2

0



Execution graph:

JOIN UNIT 2 gets input from TABLE UNIT 3

TABLE UNIT 3 for table TENKTUP1 does a full table scan with constraints UNIQUE2_NI <= 99 and UNIQUE2_NI >= 0

Execution graph

Example 1. Execution graph

Example 2

EXPLAIN PLAN FOR SELECT * FROM TENKTUP1, TENKTUP2 WHERE TENKTUP1.UNIQUE2 > 4000 AND TENKTUP1.UNIQUE2 < 4500 AND TENKTUP1.UNIQUE2 = TENKTUP2.UNIQUE2;

ID

UNIT_ID

PAR_ID

JOIN_
PATH

UNIT_
TYPE

INFO

1

6

1

9

JOIN UNIT

MERGE JOIN

2

6

1

10



3

9

6

0

ORDER UNIT

NO ORDERING REQUIRED

4

8

9

0

TABLE UNIT

TENKTUP2

5

8

9

0


PRIMARY KEY

6

8

9

0


UNIQUE2 < 4500

7

8

9

0


UNIQUE2 > 4000

8

8

9

0



9

10

6

0

ORDER UNIT

NO ORDERING REQUIRED

10

7

10

0

TABLE UNIT

TENKTUP1

11

7

10

0


PRIMARY KEY

12

7

10

0


UNIQUE2 < 4500

13

7

10

0


UNIQUE2 > 4000

14

7

10

0



Execution graph:

JOIN UNIT 6 the input from order units 9 and 10 are joined using merge join algorithm

ORDER UNIT 9 orders the input from TABLE UNIT 8. Since the data is retrieved in correct order, no real ordering is needed

ORDER UNIT 10 orders the input from TABLE UNIT 7. Since the data is retrieved in correct order, no real ordering is needed

TABLE UNIT 8: rows are fetched from table TENKTUP2 using primary key. Constraints UNIQUE2 < 4500 and UNIQUE2 > 4000 are used to select the rows

TABLE UNIT 7: rows are fetched from table TENKTUP1 using primary key. Constraints UNIQUE2 < 4500 and UNIQUE2 > 4000 are used to select the rows

Undisplayed Graphic

Example 2. Execution graph

Tracing Communication between Client and Server

SOLID Server provides following tools for observing the communication between client and server:

You can use these tools to analyze the functionality of the networking between client and server. The network trace facility should be used when you want to know why a connection is not established to the server. The ping facility is used to determine how fast packets are transferred between the client and server.

The Network Trace Facility

Network tracing can be done on the server, on the client or on both computers concurrently. The trace information is written to the default trace file or file specified in the TraceFile parameter.

The default name of the output file is SOLTRACE.OUT. This file will be written to the current working directory of the server or client depending on which end the tracing is started.

The file contains information about:

The Network Trace facility is turned on by editing the configuration file

[Com]

Trace ={Yes|No}
; default No
TraceFile = file-name
; default soltrace.out

or by using the environment variables SOLTRACE and SOLTRACEFILE to override the definitions in the configuration file. Setting of SOLTRACE and SOLTRACEFILE environment variables have the same effect as the parameters Trace and TraceFile in the configuration file.


NOTE. Defining the TraceFile configuration parameter or the SOLTRACEFILE environment variable automatically turns on the Network trace facility.


A third alternative to turn on the Network trace facility is to use the option -t and/or -ofilename as a part of the network name. The option
-t turns on the Network trace facility. The option -o turns on the facility and defines the name of the trace output file.

Example 1. Defining Parameter Trace in the Configuration File

[Com]

Connect = nmp SOLID
Listen = nmp SOLID
Trace = Yes

Example 2. Defining Environment Variables

set SOLTRACE = Yes

or

set SOLTRACEFILE = trace.out

Example 3. Using Network Name Options

[Com]

Connect = nmp -t solid
Listen = nmp -t solid

or

[Com]

Connect = nmp -oclient.out solid
Listen = nmp -oserver.out solid

The Ping Facility

The Ping facility can be used to test the performance and functionality of the networking. The Ping facility is built in all SOLID clients and is turned on with the network name option -plevel.

The output file will be written to the current working directory of the computer where the parameter is given. The default name of the output file is SOLTRACE.OUT.

Clients can always use the Ping facility at level 1. Levels 2, 3, 4 or 5 may only be used if the server is set to use the Ping facility at least at the same level.

The Ping facility levels are:

Setting

Function

Description

0

no operation

do nothing, default

1

check that server is alive

exchange one 100 byte message

2

basic functional test

exchange messages of sizes 0.1K, 1K, 2K..30K, increment 1K

3

basic speed test

exchange 100 messages of sizes 0.1K, 1K, 8K and display each sub-result and total time

4

heavy speed test

exchange 100 messages of sizes 0.1K, 1K, 2K, 4K, 8K, 16K and display each sub-result and total time

5

heavy functional test

exchange messages of sizes 1..30K, increment 1 byte

Example 1

The client turns on the Ping facility by using the following network name:

nmp -p1 -oping.out SOLID

This runs the Ping facility at the level 1 into a file named SOLTRACE.OUT. This test checks if the server is alive and exchanges one 100 byte message to the server.

After the Ping facility has been run, the client exits with the following message:

SOLID Communication return code xxx: Ping test successful/failed, results are in file FFF.XX

Example 2

If the server is using the following listen parameter

[Com]

Listen = nmp -p3 SOLID

clients can run the Ping facility at levels 1, 2 and 3, but not 4 and 5.


NOTE. Ping clients running at level greater than 3 may cause heavy network traffic and may cause slowness of application using the network. They will also slow down ordinary SQL clients connected to the same SOLID Server.


PROBLEM REPORTING

SOLID Server offers sophisticated diagnostic tools and methods for producing high quality problem reports with very limited effort. Use the diagnostic tools to capture all the relevant information about the problem.

All problem reports should contain the following files and information:

Problem Categories

Most problems can be divided into the following categories:

The following pages include a detailed instructions to produce proper problem report for each problem type. Please follow the guidelines carefully.

SOLID SQL API Problems

If the problem concerns the performance of SOLID SQL API or a specific SQL statement, you should run SQL info facility at level 4 and include the generated soltrace.out file into your problem report. This file contains the following information:

SOLID ODBC Driver Problems

If the problem concerns the performance of SOLID ODBC Driver, please include the following information:

If the problem concerns the cooperation of SOLID Server and any third party standard software package, please include the following information:

Use ODBC trace option to get a log of the ODBC statements and include it to your problem report.

UNIFACE Driver for SOLID Server Problems

If the problem concerns the performance of for SOLID UNIFACE Driver, please include following information:

Communication between Client and Server

If the problem concerns the performance of the communication between client and server use the Network trace facility and include the generated trace files into your problem report. Please include the following information:

Previous Page TOC Index Next Page

Copyright © 1992-1997 Solid Information Technology Ltd All rights reserved.