SAP MaxDB database trace

SAP MaxDB database kernel trace

This page explains how the database trace (aka kernel trace or vtrace) can be activated and deactivated and how the trace file can be converted into an ASCII file.

When is the database trace used?
Where is the trace file located?
When should I create a copy of the knltrace file?
Activating the database trace
Deactivating the database trace
Flushing the database trace
Converting the database trace into an ASCII file
The database trace in the SAP system
Further information

When is the database trace used?

The database trace is a very detailed debugging trace generated by the database kernel on request. It is mostly used only by support staff. The information contained can be used to analyze a wide range of problems, including SQL problems and kernel communication bugs.
The database trace is activated to analyze a specific database problem. You should deactivate the database trace as soon as possible after the problem has been reproduced. This prevents that the trace information will be overwritten.

back to top

Where is the trace file located?

Like most other database log files, the database trace file (knltrace) is located in the rundirectory of the database.
The trace information is first written in main memory only. You need to flush the database trace to get the trace information into the trace file.

back to top

When should I create a copy of the knltrace file?

In case of a database crash information might be written into the knltrace file even if the database trace was not activated. As the trace file is initialized when the database is started, you should create a copy of file knltrace before you start the database instance after a crash.

back to top

Activating the database trace

The database needs to be in operational state ADMIN or ONLINE. In operational state OFFLINE the database trace cannot be activated.
To activate the database trace, you can use either Database Studio or Database Manager CLI.

Further information: Creating Database Trace, Commands for the Database Trace Function

Using Database Studio

Use menu Administration Tasks -> Database Trace to activate the database trace.
You can select if only the DEFAULT trace or other components as well should be activated. In general DEFAULT is sufficient.
If the trace should be activated for a specific database session, choose tab Advanced. Select Trace Session and enter the session ID (hex).
Furthermore you can specify that the trace should stop automatically after a specified error occured: tab Advanced, select Stop on Error and enter the error code.

Using DBMCLI

Use the following DBM command to activate the database trace:
dbmcli -d <database_name> -u <dbm_operator>,<password> trace_on default
(Instead of default you could also specify other trace options.)

The database trace always needs to be activated before you can specify any of the advanced options.

To activate the trace for a specific database session use the following command:
dbmcli -d <database_name> -u <dbm_operator>,<password> -c db_execute DIAGNOSE VTRACE SESSION x'<session ID>'

If the database trace should be stopped automatically after a specified error occured, enter the following command:
dbmcli -d <database_name> -u <dbm_operator>,<password> -c db_execute DIAGNOSE VTRACE STOP ON ERROR <error code>

back to top

Deactivating the database trace

Deactivate the database trace as soon as possible after the problem has been reproduced.

Using Database Studio

Use menu Administration Tasks -> Database Trace to deactivate the database trace. You can select all or just some of the activated components to be deactivated.

Using DBMCLI

Use the following DBM command to deactivate the trace:
dbmcli -d <database_name> -u <dbm_operator>,<password> trace_off default
(Instead of default you could also specify other trace options.)

back to top

Flushing the database trace

The database trace is written in main memory. When the database trace is 'flushed' the information from the memory is written into file knltrace. If you forget to flush the trace, no information is found in the trace file.

Using Database Studio

In menu Administration Tasks -> Database Trace use the flush button to flush the trace.

Using DBMCLI

Use the following DBM command to flush the database trace:
dbmcli -d <database_name> -u <dbm_operator>,<password> trace_flush

back to top

Converting the database trace into an ASCII file

Before the trace can be analyzed, file knltrace needs to be converted into an ASCII file.

Using Database Studio

In menu Administration Tasks -> Database Trace choose tab Open Database Trace. Mark all options and then choose Make Protocol. In the rundirectory of the database file <database_name>.prt is created.

Using DBMCLI

Use the following DBM command to create file <database_name>.prt in the rundirectory of the database:
dbmcli -d <database_name> -u <dbm_operator>,<password> trace_prot abkmx

back to top