Enabling a trace while the client is running

You can trace the available backup-archive client while the client is running.

Before you begin

The backup-archive client must be installed to use dynamic tracing.
The DSMTRACELISTEN YES option must be in effect when the client is started.
- This option is specified in the system options file (dsm.sys) in the stanza that the client uses. Users must be logged in as root to use dsmtrace.
- This option is specified in the client options file (usually dsm.opt). Users must be logged in as a member of the Administrators group.

When the client starts, it starts a separate trace listener thread. This thread listens on a named pipe, waiting to be contacted by the dsmtrace utility. To make the named pipe name unique, the client process ID (PID) is a part of the pipe name. When you use dsmtrace to configure tracing, it contacts the client through the named pipe on which the client is listening and passes to it the preferred trace configuration operation. The client then passes the results of the operation back to dsmtrace through another similarly named output pipe. dsmtrace displays the results to the console. The client starts the trace listener thread only when client option DSMTRACELISTEN YES is in effect. If DSMTRACELISTEN NO is in effect, then the listener thread is not started and dynamic tracing is not available to that client. DSMTRACELISTEN NO is the default value.

About this task

The steps for gathering a client trace are as follows:

Procedure

Stop the backup-archive client.
Configure the client options file with the preferred trace options.
Restart the backup-archive client and reproduce the problem.
Stop the backup-archive client.
Remove the trace options from the backup-archive client options file.

Send the resulting trace file to IBM technical support for analysis.

You can also use the dsmtrace utility to start, stop, and configure client tracing dynamically without having to stop the client or modify the options file. Dynamic tracing is especially useful when you must trace only the beginning of a long-running backup-archive client operation, or when you must start tracing after the backup-archive client is running for some time.

The dsmtrace utility includes the following features:

Identify running processes and their process PIDs
Enable client tracing
Disable client tracing
Query client trace status

The following table summarizes the availability of this feature:

Table 1. Availability of the dsmtrace utility
Client Component	AIX® or Linux® Program Name	Windows Program Name
Backup-Archive Client (command line)	dsmc	dsmc.exe
Backup-Archive Client (GUI)	N/A	dsmagent.exe
Client acceptor	dsmcad	dsmcad.exe
Remote Client Agent	dsmagent	dsmagent.exe
Scheduler Service	N/A	dsmcsvc.exe
Journal Service	N/A	tsmjbbd.exe
Data Protection for Domino (command line)	domdsmc	domdsmc.exe
Data Protection for Domino (GUI)	N/A	domdsm.exe
Data Protection for Microsoft Exchange (command line)	N/A	tdpexcc.exe
Data Protection for Microsoft Exchange (GUI)	N/A	tdpexc.exe
Data Protection for Microsoft SQL Server (command line)	N/A	tdpsqlc.exe
Data Protection for Microsoft SQL Server (GUI)	N/A	tdpsql.exe

Note:

The center column in Table 1 includes Macintosh OS X.
Tracing for the Data Protection components is for the IBM Storage Protect application programming interface (API) only.
The IBM Storage Protect API tracing is available with any multithreaded application that uses the IBM Storage Protect API. The executable file name is the name of the application program that loads the API.

Example

The following example shows you how to enable client trace while the client is running:

Identify the process PID of the backup-archive client that you want to trace (make sure that DSMTRACELISTEN YES is in effect). Issue the following command to show all running instances of the client: dsmtrace query pids

Example output:

D:\tsm>dsmtrace query pids 

IBM
Storage Protect
dsmtrace utility 
	dsmtrace Version 5, Release 3, Level 0.0 
	dsmtrace date/time: 10/24/2004 21:07:36 
(c) Copyright by IBM Corporation and other(s) 1990, 2004. All Rights Reserved. 

PROCESS ID  PROCESS OWNER  DESCRIPTION                   EXECUTABLE NAME 
4020        andy           Backup-Archive Client (CLI)   dsmc.exe 

D:\tsm>

Important: The threading model for some versions of Linux is to run each thread as a separate process, which means that when you query process information, you might see several processes for each instance of the client. The process that you must identify is the dsmc parent process. For example:

fvtlinuxppc:/opt/tivoli/tsm/client/ba/bin # dsmtrace q p

IBM
Storage Protect 
dsmtrace utility 
	dsmtrace Version 5, Release 3, Level 0.0 
	dsmtrace date/time: 10/24/04 08:07:37 
(c) Copyright by IBM Corporation and other(s) 1990, 2004. All Rights Reserved. 

PROCESS ID   PROCESS OWNER  DESCRIPTION                   EXECUTABLE NAME 
28970       root            Backup-Archive Client (CLI)    dsmc 
28969       root            Backup-Archive Client (CLI)    dsmc 
28968       root            Backup-Archive Client (CLI)    dsmc 
28967       root            Backup-Archive Client (CLI)    dsmc 

fvtlinuxppc:/opt/tivoli/tsm/client/ba/bin #

In such a situation, issue the PS command to identify the parent dsmc process:

linuxppc:~ # ps -ef | grep dsmc 

root   28967   1151   0    Oct22 pts/16   00:00:00  dsmc 
root   28968   28967  0    Oct22 pts/16   00:00:00  dsmc 
root   28969   28968  0    Oct22 pts/16   00:00:00  dsmc 
root   28970   28968  0    Oct22 pts/16   00:00:00  dsmc 
root   24092   24076  0    08:15 pts/93   00:00:00  	grep dsmc 

linuxppc:~ #

Notice that the parent for processes 28969 and 28970 is 28968. The parent for 28968 is 28967. The parent for 28967 is 1151, but the 1151 process does not appear in this display output. Process 1151 is the process that started dsmc. So, the correct parent process ID is 28967.

Issue the following command to enable tracing on the client:

dsmtrace enable 4020 -traceflags=service -tracefile=d:\trace.txt

Example output:

C:\program files\tivoli\tsm\baclient>dsmtrace enable 4020 -traceflags=service
-tracefile=d:\trace.txt

IBM
Storage Protect
dsmtrace utility
	dsmtrace Version 5, Release 3, Level 0.0
	dsmtrace date/time: 10/24/2004 21:45:54
(c) Copyright by IBM Corporation and other(s) 1990, 2004. All Rights Reserved.

ANS2805I Tracing has been enabled.

C:\program files\tivoli\tsm\baclient>
C:\program files\tivoli\tsm\baclient>

Important: When you are tracing an API application, the -pipenameprefix option must be included.

Use prefix /tmp/TsmTraceTargetAPI
Use prefix \\.\pipe\TsmTraceTargetAPI

After sufficient trace data is collected, disable the tracing by issuing the following command:

dsmtrace disable 4020

Example output:

C:\program files\tivoli\tsm\baclient>dsmtrace disable 4020

IBM
Storage Protect
dsmtrace utility
  dsmtrace Version 5, Release 3, Level 0.0
  dsmtrace date/time: 10/24/2004 21:47:43
(c) Copyright by IBM Corporation and other(s) 1990, 2004. All Rights Reserved.

ANS2802I Tracing has been disabled.

Other examples of enabling client trace while the client is running are defined in the following list:

dsmtrace query pids: This command displays all running processes whose names are listed in the table in the Background section.
dsmtrace query pids -filter=*: This command displays all running processes.
dsmtrace query pids -filter=dsm*: This command displays all running processes whose name begins with dsm
dsmtrace query pids -filter=dsm?: This command displays all running processes whose name begins with dsm plus one other character.
dsmtrace enable 2132 -traceflags=service -tracefile=c:\trace.txt: This command turns on SERVICE tracing for process 2132. Trace output is written to file c:\trace.txt.
dsmtrace enable 2132 -traceflags=-extrc: This command turns off extrc tracing for process 2132 (presumably tracing is already running for this process).
dsmtrace enable 4978 -traceflags=fileops -tracefile=/tmp/dsmtrace.out -tracemax=1000 -tracesegsize=200: This command turns on FILEOPS tracing for process 4978. The trace is written to files /tmp/dsmtrace.out.1, /tmp/dsmtrace.out.2, and so on, with each file being no larger than 200 MB. After 1000 MB are written, tracing wraps back to /tmp/dsmtrace.out.1.
dsmtrace query trace 4978 -on: This command displays basic trace information and lists trace flags that are turned on for process 4978.
dsmtrace disable 4978: This command disables tracing for process 4978.
dsmtrace disable 364 -pipenameprefix=/tmp/TsmTraceTargetAPI: This command disables tracing for API application process 364.