Tivoli Storage Manager Trace Facility Guide


Client Trace Facility

Use this guide to trace problems in a particular client. This guide helps isolate a problem with the client or a related problem. This book describes how the client trace facility aids in that process.


Diagnosing Client Problems with Trace Commands

The client trace facility helps you diagnose client problems by tracing specific events. The trace facility uses trace functions from the options file or the command line. Trace output is displayed on the client screen or sent to a specified file. You can use tracing while in interactive mode or while using the graphical user interface.

Each trace flag enables tracing for a specified functional area of the client. Some trace flags generate large amounts of data, while others produce relatively small amounts. Depending on which trace flags are enabled, you can expect small to moderate performance degradation in the client.

The tracing facility described in this document applies to all TSM clients, including the backup-archive clients, the administrative client, the application programming interface (API), Web client, and the space management clients.


Client Trace Messages

For more information on the client trace messages refer to Tivoli Storage Manager Messages, order number GC35-0405. The TSM publications are available in softcopy on the TSM Web site at the following URL:

   http://www.tivoli.com/support/storage_mgr/tivolimain.html

Time stamps are added to the beginning of each trace message. You can turn off time stamps by turning off the TIMESTAMP class for client trace messages.

You can remove the module (line_number) suffix from client trace messages by turning off the PREFIX class.


Performance Considerations

From a performance standpoint, you should not keep your trace settings activated if you are in a stable environment and are not experiencing problems. Trace routines require processing time and could slow down the response times of your workstation applications. If a problem occurs, you can always activate the trace routines to gather trace information for diagnostic purposes. Call your Tivoli Service Representative for assistance in diagnosing TSM problems.


Using the Web Client Trace Flags

To enable the Web client trace flags follow these steps:

  1. From the main Web client window select the Edit menu; Applet Preferences item.
  2. Click the Enable applet traceflags box on the Applet Preferences window.
  3. Enter the trace flags that you want to enable, separated by commas.
  4. Select OK to enable the applet tracing. The trace flags are enabled for the current Web session only.

Figure 1 displays the available Web client applet traceflags. Trace flags are not case-sensitive.

Table 3. Web Client Applet Trace Flags

 Flag   Description 
 ALL   Enables: GUI, COMGUI, SESSVERB, VERBINFO 
 ALLSESS   Enables: SESSVERB, VERBINFO 
 ALLGUI   Enables: GUI, COMGUI 
 COMGUI   Graphical user interface controller tracing 
 GUI   Graphical user interface tracing 
 SERVICE   Enables: GUI, COMGUI, SESSVERB 
 SESSVERB   General agent-applet verb information 
 VERBINFO   Agent-applet verb contents tracing 

Using the Command Line

TSM trace routines provide you with diagnostic information that can be extremely useful in resolving processing problems on your workstation.

Using the Query Trace Status Commands

For TSM to capture diagnostic information, you must activate trace settings or flags. You can use the query tracestatus command to display whether tracing is active for a specific trace flag or all flags. For example, to show a list of all trace flags that are currently active, enter:

  dsmc query tracestatus -on

Other options are also available for the query tracestatus command. See Query Tracestatus for more information.

Using Tracing Options on Commands

The client trace facility provides the following options:

tracemax
tracefile
traceflags
notrace

You can use these options with most TSM commands. You can also use these options to override settings in the options file.

If you enter these options during an interactive command session, they remain in effect until you end the session.

Tracemax

The tracemax option lets you specify the maximum size for the tracefile.

When you enter trace options from the command line or in the options file,use the following sequence:

  1. tracemax
  2. tracefile
  3. traceflags

Following this order ensures that all trace entries from the start of the trace will go into the file that you specify.

Tracefile

The tracefile option lets you save your trace output to a file instead of displaying it on the client screen. For example, to archive the files in your /u/user/prog directory and save the trace output to a file, you can enter:

  dsmc archive -tracefile=trace.out -traceflags=all "/u/user/prog/*"

To save your trace output while you are using the graphical user interface, use the tracefile option when you start the GUI:

  dsm -tracefile=trace.out -traceflags=all

You can send the trace data to dsmerror.log so that you can see the relevant ANS error messages and how they relate to the trace data, as in the following example:

   dsm -tracefile=$dsm_log/dsmerror.log

If you do not use the tracefile option, the output is displayed on your client screen.

Traceflags

The traceflags option lets you set specific trace flags. For example, if you are having a problem with the incremental command, you might want to turn on the ERROR trace flag when you execute the command. The ERROR trace flag captures all severe error messages. You can turn it on by entering:

  dsmc incremental -traceflags=error

You can turn on all of the trace flags by using the ALL parameter. You can also use the ALL parameter with exceptions. For example, to back up a specific file and turn on all of the trace flags except COMMFULL and NLS (both of which generate a large amount of data), enter the following command:

  dsmc selective -traceflags=all,-commfull,-nls /home/spot/myfile

To turn on particular trace flags while you are using the graphical user interface, specify the traceflags option when you start the GUI:

  dsm -traceflags=general,session

Notrace

You can turn off all tracing by using the notrace option. For example, to turn off the tracing when using the incremental command, you can enter:

  dsmc incremental -notrace

To turn off tracing while you are using the graphical user interface, specify the notrace option when you start the GUI:

  dsm -NOTrace

Using the Options File

You can include tracemax, tracefile, and traceflags, in your client options file to enable these options whenever you start a TSM session. The options can be overridden during a session by using the same options in a TSM command.


Client Commands and Options

The following commands and options are available for tracing TSM clients.

Query Tracestatus

Purpose

Use the query tracestatus command to display a list of available trace flags and their current settings. The ALL, OFF and ON options must be entered each time you enter this command in loop mode.

Format

>>-dsmccmd---Query Tracestatus---+----------+------------------><
                                 '- options-'
 

Parameters

dsmccmd
The TSM command-line interface command. For example, DSMC (for OS/2, Windows, or UNIX) or LOAD DSMC (for NetWare).

options
Any of the following:

-ALL
Displays both active and inactive trace flag settings. This is the default unless you specified another setting in a previous command in the same interactive command session. To display both active and inactive trace flag settings, enter:
  Query Tracestatus -ALl

-OFf
Displays only inactive trace flag settings; for example:
  Query Tracestatus -OFf

-ON
Displays only active trace flag settings; for example:
  Query Tracestatus -ON

-NOTrace
Turns tracing off if it is enabled in the options file; for example:
  Query Tracestatus -NOTrace

-TRACEFIle
Writes trace output to a specified directory and file name. If you do not specify a file or it is not specified in the tracefile option in your client options file, output from active trace routines is only displayed on your client screen. For diagnostic purposes, you should save trace output to a file. For example, to save trace output to the traceout file in the /u/user directory, enter:
  Query Tracestatus -TRACEFIle=/u/user/traceout

-TRACEFLags
Turns on specific flags; for example, to turn on the GENERAL and SESSION trace flags, enter:
  Query Tracestatus -TRACEFLags=general,session

Examples

Task
Display the status of your trace flags.

Command
dsmc Query Tracestatus

Notrace

Use the notrace option to turn tracing off if tracing is enabled on the client.

You can use notrace on the command line as an option in a TSM command, but you cannot use it in the client options file.

Syntax

>>-NOTrace-----------------------------------------------------><
 

Examples

Client user options file example:
Not available

Command line example:
dsmc -NOTrace

Tracemax

Use the tracemax option to specify the maximum size, in kilobytes, that the tracefile can grow to. This option can also be defined on the server.

Syntax

>>-TRACEMAX size-----------------------------------------------><
 

Parameters

size
The size, in kilobytes, for the maximum size of the trace file. The range of values is 0 to 10000. The default is 0, which disables trace file wrapping and allows the trace file to grow indefinitely.

Examples

Client user options file example:
tracemax 4000

Command line example:
dsmc -tracemax=4000

Tracefile

Use the tracefile option to place the trace output into a specified file. If the file does not already exist, then it is created. If the file exists, then the trace output is appended to the file.

If your trace file reaches the maximum size that you set with the tracemax option, subsequent trace entries will overwrite existing entries beginning at the top of the file.

There are message indicators showing where new entries begin and where the oldest entry appears. The first trace entries follow the starting trace texts such as "Tracing is active..." or "Tracefile maximum ...". The last entry of the trace is followed by an eyecatcher text "end of data - close". Figure 1 is an example of a typical trace file.

Figure 1. Example of a trace file

+--------------------------------------------------------------------------------+
|ADSM trace  3969        10240                                                   |
|04/22/1995 12:11:44.0449 : trace.c   (1140): Tracing is active to file 't.out'. |
|04/22/1995 12:11:44.0452 : trace.c   (1141): Tracefile maximum length set to 10k|
|04/22/1995 12:11:44.0453 : trace.c   (1150): -----------------------------------|
|04/22/1995 12:11:44  - Trace begun.                                             |
|  .                                                                             |
|  .  (trace entries here)                                                       |
|  .                                                                             |
|04/22/1995 12:11:44.0548 : procopts.c(5907):                                    |
|04/22/1995 12:11:44.0771 : anspsqry.c( 610): psqSendQuery: Using 'STANDARD' as t|
|  .                                                                             |
|  .                                                                             |
|  .                                                                             |
|end of data - close                                                             |
+--------------------------------------------------------------------------------+

You can set tracefile in your client options file or specify it as an option on a TSM command.

Syntax

>>-TRACEFIle---- filespec--------------------------------------><
 

Parameters

filespec
Specifies the name of the trace file, in the client's file name format. If no directory is specified, then the file is placed in the current directory.

If tracefile is not specified and tracing is active, trace statements are sent to standard output by default.

Examples

Client user options file example:
TRACEFIle /u/user/trace.out

Command line example:
dsmc -TRACEFIle=trace.out

Traceflags

Numerous components in the system have informational tracing imbedded. Tracing is activated by specifying trace flags for the desired component or area. You can use traceflags in your client options file or as an option in a TSM command to activate specific traceflags for the desired component or area. This option can also be defined on the server.

Syntax

                 .---------------.
                 V               |
>>-TRACEFlags--------+- flag--+--+-----------------------------><
                     '- -flag-'
 

Parameters

flags
Possible values for the trace flags are listed in Table 4.

When using aggregate flags such as ALLSESS, or when it is necessary to disable a default trace flag such as SYSTIME, discrete trace flags may be disabled by prefixing the trace flag with a dash (-). For example, the ALLSESS aggregate flag traces enables the flags SESSION, VERBINFO, SESSVERB, and VERBADMIN. If you want to trace all of these functions except VERBADMIN, and times stamps on the trace records are not needed, then specify:

Command line option:  -traceflags=allsess,-verbadmin,-systime
Options file:  traceflags allsess -verbadmin -systime

When using traceflags on a command, use commas to separate the individual trace flag values.

The default value is no tracing.

Note:See "Using the Web Client Trace Flags" for information about the Web client applet trace flags.

Table 4. Trace Flags

Trace flags are not case-sensitive.
 Flag   Description 
 ALL   Enables: All traceflags except INSTR, INSTR_CLIENT, INSTR_CLIENT_DETAIL, INSTR_VERBOSE 
 ADMIN   Administrative component 
 ALLCOMM   Enables: COMM, 3270COMM, EHLLAPI, 3270ERROR 
 ALLSESS   Enables: SESSION, VERBINFO, SESSVERB, VERBADMIN 
 ALLFILE   Enables: DIROPS, FILEOPS, FIOATTRIBS 
 ALLBACK   Enables: INCR, TXN, POLICY 
 ALLPROC   Enables: ALLBACK, ALLFILE, ALLSESS 
 API   API tracing 
 AUDIT   List files backed up or restored (Macintosh and Windows) 
 COMM   Communications interface 
 COMMFULL   Communications driver data 

This trace flag produces large amounts of trace data.

 COMMDETAIL   Detailed communications 

When the communications buffer is larger than 192 bytes, this trace flag displays only the first and last 96 bytes of data.

 COMPRESS   Compression, expansion processing 
 CONFIG   Configuration file processing 
 CONFIRM   Confirm tracing 
 DIRDETAIL   Detailed directory operations 
 DIROPS   Directory operations 
 EHLLAPI   PC3270W V3.0 EHLLAPI tracing 
 ENTER   Entering or exiting a major function 
 ERROR   Severe errors tracing 
 ERRPROG   X'800' turns on a bit to indicate special error program processing. 

This is used for daemon-initiated errors (from Space Management, for example) that need special error handling

 EVENT   Event logging tracing 
 EVENTLOG   Windows NT backup and restore event logs tracing 
 EXIT   Function exits 
 FILELISTS   User interface file list processing 
 FILEOPS   File I/O operations 
 FIOATTRIBS   File and directory attributes during backup and archive 
 FS   File space processing 
 FSPS   Platform-specific file system tracing 
 GENERAL   General process flow operations 
 INCR   Incremental process operations 
 INSTR   Instrumentation tracing 
 INSTR_API   API instrumentation 
 INSTR_CLIENT   Client entry or exit and network times 
 INSTR_CLIENT_DETAIL   Print detailed process information 
 INSTR_VERBOSE   Print all and final time statistics 
 LINK   Hard link processing (UNIX) 
 MEMDETAIL   Detailed memory tracing 
 MEMORY   Memory allocation, buffer pool 
 MESSAGES   User interface event messages 
 NETWARE   Enables SMSDEBUG 
 NLS   National Language Support processing 

This trace flag produces large amounts of trace data.

 NTREGISTRY   Windows NT Registry tracing 
 OPTIONS   Enables CONFIG 
 PERFORM   Enables: CONFIG, STATS, INSTR_CLIENT_DETAIL 
 PID   Enables process or thread identification information 
 POLICY   Policy management tracing 
 PREFIX   Adds module(line number) tracing suffixes to messages 

Enabled by default. May be disabled by using -PREFIX in the TRACEFLAGS lists

 SERVICE   Enables: ALL, -NLS, -COMMDETAIL, -COMMFULL, -DIRDETAIL, -MEMORY, -MEMDETAIL 
 SESSION   Session layer tracing 
 SESSVERB   Enables raw verb tracing 
 SM   Space Management tracing (UNIX) 
 SMSDEBUG   Storage Management Services (NetWare) 
 SMVERBOSE   Space Management detailed tracing (UNIX) 
 STATS   Backup and archive statistics 
 TEST   Development test flag 
 TIMESTAMP   Timestamps on trace records 

Enabled by default. May be disabled by using -TIMESTAMP in the TRACEFLAGS lists

 TRUSTED   Trusted Communications Agent specific tracing (UNIX) 
 TXN   Backup and Archive Transaction list processing. 
 VERBADMIN   Administrator Datastream tracing 
 VERBINFO   Client-server Verb fields contents tracing 
 WINUAETRAP   Catches Windows unauthorized access errors 
 95REGISTRY   Windows 95 backup and restore registry tracing 
 3270COMM   Low-level 3270 for Windows tracing 
 3270ERROR   Low-level 3270 error tracing (Windows) 

Examples

Client user options file examples:
TRACEFLags general config comm

 
TRACEFLags ALL -COMMDETAIL -nls

Command line examples:
dsmc -TRACEFLags=GENERAL,CONFIG,comm

dsmc -TRACEFLags=ALL,-commdetail,-nls

Tracing for the Tivoli Data Protection for Lotus Notes

You can monitor the performance of the Tivoli Data Protection for Lotus Notes (TDP Notes) operations by setting up tracing. First, turn tracing on by setting the environment variable DSMNOTES_TRACE in the NOTES.INI file. For example:

   DSMNOTES_TRACE=ON

The name of the trace file is TRACE.DSM. Its location is determined by the environment variable DSMNOTES_TRACEDIR in NOTES.INI. For example:

   DSMNOTES_TRACEDIR=c:\mydir

TRACE.DSM does not wrap. Its contents are overwritten each time a new TDP for Lotus Notes operation, like an incremental backup or a single restore, is invoked.


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]