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.
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.
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.
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.
To enable the Web client trace flags follow these steps:
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 |
TSM trace routines provide you with diagnostic information that can be extremely useful in resolving processing problems on your workstation.
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.
The client trace facility provides the following options:
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.
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:
Following this order ensures that all trace entries from the start of the trace will go into the file that you specify.
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.
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
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
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.
The following commands and options are available for tracing TSM clients.
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
Query Tracestatus -ALl
Query Tracestatus -OFf
Query Tracestatus -ON
Query Tracestatus -NOTrace
Query Tracestatus -TRACEFIle=/u/user/traceout
Query Tracestatus -TRACEFLags=general,session
Examples
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
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
Examples
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
If tracefile is not specified and tracing is active, trace statements are sent to standard output by default.
Examples
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
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. |
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
dsmc -TRACEFLags=ALL,-commdetail,-nls
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.