Tivoli Storage Manager Trace Facility Guide


Server Trace Facility

The server trace facility is intended for use at the request of Tivoli Service to gather information on specific server activities to assist with diagnosis of server problems. This chapter provides information on the commands used to control the trace facility and select those functions to be traced.


Diagnosing Server Problems with Trace Commands

Administrators with analyst privilege can diagnose server problems by enabling, disabling and controlling the server trace activity. Any administrator with general privilege can display information about trace activities.

Authorized administrators can trace TSM events by initiating trace functions from the server screen, or to trace functions as the server is started, by placing the trace commands in the server options file. Trace output is displayed on the server screen or sent to a file specified with the trace begin command.

Tracing is achieved by enabling and disabling trace classes. Each trace class produces diagnostic information for a specific functional area of the server. Some trace classes generate extremely large amounts of data, while others produce relatively small amounts. Depending on which trace classes are enabled, expect moderate to severe performance degradation in the server. For this reason, perform tracing on the server in a controlled environment with general user access limited to those client or administrator nodes necessary to recreate the problem, and only at the request of a Tivoli service representative.

These are the trace functions:

Begin
Start server tracing. The server writes trace information to the trace buffer according to the trace classes that are enabled. See Trace Begin.

Disable
Deactivate trace classes that are specified in the trace class list. Trace classes are deactivated immediately; however, tracing continues for other active trace classes until the trace is ended with the trace end command. See Trace Disable.

ENAble
Activate trace classes. After a trace class is enabled, begin server tracing. See Trace Enable.

END
Stop tracing. See Trace End.

Flush
Write any trace records left in the trace buffer when you end a trace to an output file. See Trace Flush.

List
List all common aggregate trace classes. See Trace List.

Query
Query the status of enabled trace classes and trace activity. See Query Trace.

Server Trace Messages

For more information on the client trace messages, refer to Tivoli Storage Manager Messages. 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 SYSTIME class for server trace messages.

Trace Begin

Use the trace begin command to start server tracing. Tracing can adversely affect the performance of the TSM system. The trace begin command should only be used at the request of an IBM service representative. Trace output is displayed on the server screen or sent to a file that you specify with the trace begin command.

Privilege Class

Analyst

Syntax

>>-TRace Begin------ filespec----------------------------------><
 

Parameters

filespec
Specifies the name of the file that trace output is sent to. If you do not specify a file, output is displayed on the server screen. Use the following formats:

VM File Specification for Trace Output
On VM, files are typically entered in the format filename filetype filemode.

TSM requires that the file specification entered as filename.filetype.filemode. The periods are required. However, the filemode is optional, and the default is A.

If you specify a filemode other than A, that minidisk must be linked and accessed in write mode.

For example:

Command
VM file created

TRace Begin trace.output
trace output a1

TRace Begin trace.output.b
trace output b1

MVS Dataset Specification for Trace Output
The filespec on an MVS system is appended to the user ID on the job statement if the TSM server is run as a job, or to the RACF default task owner (site specified for RACF) when the TSM server is run as a started task. When you want trace output directed to a file, you can specify a fully qualified file name such as 'HOLLAND.TRACE.OUTPUT' to override the default first level qualifier. TSM dynamically allocates and catalogs the data set if it does not exist. If catalogued data set with the specified name exists, TSM uses the existing data set and appends to it if it already contains trace data. If a large data set is required for the trace, or the administrator wants more allocation and placement control, the administrator can preallocate and catalog the data set. The DCB attributes for the trace data set are DSORG=PS, RECFM=VB, LRECL=1028, and BLKSIZE=6144. For example:

Command
MVS Dataset Created

TRace Begin trace.output
USERID.TRACE.OUTPUT

The first level qualifier, USERID, is that of the user ID on the job statement when the TSM server is run as a job.

TRace Begin trace.output
RRRRRR.TRACE.OUTPUT

The first level qualifier, RRRRRR, was specified by your site for the RACF default owner on a started task when the TSM server is run as a started task.

TRace Begin "'holland.trace.output'"
HOLLAND.TRACE.OUTPUT

The first level qualifier, HOLLAND, is specified on the command and is not appended to any other qualifier.

AIX, OS/2, Windows NT, HP-UX, and SunOS File Specification for Trace Output
On AIX, OS/2, Windows NT, HP-UX, and SunOS, files are typically specified trace.out.

Use the file naming conventions associated with the platform, and:

Command
File created

TRace Begin trace.out
trace.out

Examples

Task:
Start server tracing with the currently enabled trace classes and display all trace information on the screen.

Command:
TRace Begin

Task:
Start server tracing with the currently enabled trace classes and send all trace information to the file specified in filespec; in this case the file trace.output.

Command:
From another TSM command line client, enter: TRace Begin trace.output

Task:
Start AS/400 server tracing with the currently enabled trace classes and send all trace information to the file specified in filespec.

Command:
From a TSM AS/400 admin command line or the client options file, enter: TRace Begin Libraryname/Filename (membername)

Trace Disable

Use the trace disable command to deactivate server trace classes. Trace classes are deactivated immediately; however tracing continues for other active trace classes until the trace is ended with the trace end command.

Privilege Class

Analyst

Syntax

                   .- *---------------.
>>-TRace Disable---+------------------+------------------------><
                   |  .-------------. |
                   |  V             | |
                   '--- traceclass--+-'
 

Parameters

*
Specifies that all trace classes are deactivated. This is the default.

traceclass
Specifies a list of the trace classes to deactivate. You must separate trace classes by spaces. See Table 5 for a list of the trace classes.

Examples

Task:
Disable the TCPINFO trace class.

Command:
TRace Disable TCPINFO

Trace Enable

Use the trace enable command to activate server trace classes. Tracing does not start until a trace begin command is issued.

There are aggregate trace classes defined to enable multiple trace classes, grouped together for logical function tracing.

Privilege Class

Analyst

Syntax

                  .---------------.
                  V               |
>>-TRace ENAble------ traceclass--+----------------------------><
 

Parameters

traceclass
Specifies trace classes to activate. You must separate trace classes by spaces.

In some cases the trace class, or aggregate trace class, enables different tracing on the different platforms. You can activate as many trace classes as you want.


Table 5. Server Trace Classes

 Trace Class   Description 
 ADMCMD   Command tracing 
 APPCERROR   APPC driver error data tracing 
 APPCINFO   APPC driver general information tracing 
 BLKDISK   Block oriented disk driver 
 DIALERROR   DIAL driver error tracing (S/390) 
 DIALINFO   DIAL driver general information tracing (S/390) 
 IPXDATA   IPX driver data (OS/2, AIX) 
 IPXERROR   IPX driver errors (OS/2, AIX) 
 IPXINFO   IPX driver informational data (OS/2, AIX) 
 IUCVERROR   IUCV driver error tracing (S/390) 
 IUCVINFO   IUCV driver general information tracing (S/390) 
 LVM   Database/Recovery log management functions 
 MMSBASE   Entry points into mount management services component 
 NETBIOSDATA   (OS/2, AIX) - Netbios driver data 
 NETBIOSERROR   (OS/2, AIX) - Netbios driver errors 
 OPER   Operator interface tracing (S/390) 
 PID   Command Process ID (UNIX) 
 SCHED   Central Scheduling 
 SYSTIME   System time on trace records 
 TCPERROR   TCP/IP driver error tracing 
 TCPINFO   TCP/IP driver general information tracing 
Note:
  • S/390 means a server running on an IBM S/390 mainframe (VM, MVS, or VSE).
  • OS/2 means a server running on an OS/2 workstation.
  • UNIX means a server running on an AIX, HP-UX, or SunOS workstation.

Examples

Task:
Enable the OPER and APPCINFO trace classes.

Command:
TRace ENAble OPER APPCINFO

Trace End

Use the trace end command to stop server tracing. After issuing a trace end command, all trace activities stop.

Privilege Class

Analyst

Syntax

>>-TRace END---------------------------------------------------><
 

Examples

Task
Stop tracing

Command
TRace END

Trace Flush

Use the trace flush command to write any trace records in the trace buffer to an output file. The trace buffer writes its contents to a when it is full. Unless you use this command, the contents in the buffer are not displayed except when the trace end command is issued. If you use the trace flush command, be sure to issue it before the trace end command to prevent loss of trace data in the last trace buffer.

Privilege Class

Analyst

Syntax

>>-TRace Flush-------------------------------------------------><
 

Examples

Task:
Flush the trace buffer.

Command:
TRace Flush

Trace List

Administrators can use the trace list command to display the common aggregate trace classes available on a specific TSM server. This command is also useful in verifying the correct spelling of trace class names.

Privilege Class

Analyst

Syntax

>>-TRace List--------------------------------------------------><
 

Examples

Task:
List the trace classes.

Command:
TRace list

Output:
The following aggregate trace classes are available:
TM, DB, LOG, ADM, PM, BF, DF, AF, SS, DS, AS, IC, DRM, ORM,
DRMPR, PK, DISK, TCP, APPC, NETBIOS, IPX, COMMTRAP, THREAD,
PVR8MM, PVR4MM, PVRQIC, PVRDLT, PVRDTF, PVRECART, PVR, MMS,
SHM
 
The following simple trace classes are available:
INSTR, BTREE, DBALLOC, DBBUF, DBBUFWR, DBCKPT, DBTXN, DBLOG,
DBBACKUP, BITVECTOR, TXN, LOCK, LOGALLOC, LOGARCH, LOGBUF,
LOGBUFWR, LOGCOMP, LOGREC, LOGRESIZE, LOGSEG, SESSION, LVM,
ADMNODE, ADMADMIN, ADMPROC, ADMCMD, PMDOM, PMSET, PMMC, PMCG,
PMLOCK, PMCACHE, SCHED, XI, IMLOCK, IMSORT, BFCREATE, BFRTRV,
BFDESTROY, BFSALVAGE, BFLOCK, BFAGGR, DFCREATE, DFRTRV,
DFDESTROY, DFMOVE, DFLOCK, DFTXN, DFCOPY, AFCREATE, AFRTRV,
AFDESTROY, AFMOVE, AFLOCK, AFTXN, AFCOPY, SSCLASS, SSPOOL,
SSVOL, SSTRANS, SSSESS, SSLOCK, DSALLOC, DSRTRV, DSDEALLOC,
DSVOL, DSTXN, ASALLOC, ASRTRV, ASDEALLOC, ASMOUNT, ASVOL,
ASTXN, ASSD, DBDUMP, AUDIT, LM, ICBITS, ICHDRPG, ICBACK,
ICREST, ICTRIGGER, ICDISK, ICSTREAM, ICLOG, ICLOCK, DEADLOCK,
SYSTIME, DRMMACH, DRMMACHCHAR, DRMRECOVINST, DRMRECOVMEDIA,
DRMAPPEND, ORMDELETE, ORMUPDATE, DRMSETGA, DRMPRST,
DRMPRDBBACK, DRMPRDEVCLASS, DRMPRSTGPOOL, DRMPRLOGDBVOL,
DRMPRREQPOOL, DRMPRMDRM, ORMCMD, DRMLICCOMP, 3590POS, SQL,
NQR, IMEXP, DBBUFPF, TBPREFETCH, ID, HT, PERFSTAT, LANG,
THREADDETAIL, SHMEM, TRAPSYNC, BLKDISK, SIGAIX, TCPTRAP,
TCPINFO, TCPDATA, TCPSODEBUG, NETBIOSINFO, NETBIOSERROR,
NETBIOSDATA, NETBIOSTRAP, APPCINFO, APPCERROR, APPCDATA,
APPCTRAP, IPXINFO, IPXERROR, IPXDATA, IPXTRAP, THREADEP,
PVR8MMBASE, PVR4MMBASE, PVRQICBASE, PVRDLTBASE, PVRDTFBASE,
PVRFILE, PVRODSK, PVRCART, PVRVOL, PVRCLASS, PVRMP, PVRTAPE,
PVRGTS, PVRNTP, PVRTAPIBASE, PVRECARTBASE, MMSBASE, MMSTXN,
MMSLIB, MMSDRIVE, MMSOP, MMSMAN, MMSSCSI, MMSFLAG, MMSACSLS,
SNMP, SHMINFO

Query Trace

Use the query trace command on a server to display the currently enabled server trace classes and the status of trace activity.

Privilege Class

Analyst

Syntax

>>-Query TRace-------------------------------------------------><
 

Examples

Task:
Display all currently enabled trace classes.

Command:
Query TRace

Output:
The following trace classes are enabled:
SESSION, TCPINFO, MMSBASE, MMSTXN, MMSLIB, MMSDRIVE, MMSOP,
MMSMAN, MMSSCSI, MMSFLAG, MMSACSLS
 
Tracing status: active to file server.trc.


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