Collecting instrumentation data with the API

API instrumentation identifies the time that elapsed during application activities. It is used for applications and products that use the IBM Spectrum Protect API. By default, instrumentation data is automatically collected by the API during backup or restore processing.

About this task

To disable or later enable instrumentation, use the enableinstrumentation option.

With this option enabled, you do not have to wait for a customer service representative to direct you to collect performance data when a problem occurs. Instead, the data is collected whenever you run a backup or restore operation. This feature can be helpful because you do not have to re-create the problem just to collect performance data. The information is already collected by the API.

The default setting of this option is yes, which means that instrumentation data is collected even if you do not specify this option. Typically, collecting instrumentation data by default has no measurable impact on regular performance.

By default, the output is appended to the instrumentation log file (dsminstr.log) in the directory that is specified by the DSM_LOG environment variable (or the DSMI_LOG environment variable for API-dependent products such as IBM Spectrum Protect for Databases: Data Protection for Microsoft SQL Server and IBM Spectrum Protect for Mail: Data Protection for Microsoft Exchange Server). If you did not set the DSM_LOG environment variable, the instrumentation log file is stored in the current directory (the directory where you started the dsmc command).

You can optionally change the name and location of the instrumentation log file by using the instrlogname option. You can also control the size of the log file by specifying the instrlogmax option.

The enableinstrumentation option replaces the -TESTFLAG=instrument:API option that is used in previous versions of the API.

Procedure

To collect API instrumentation data, use one of the following methods:

  • By default, API instrumentation data is automatically collected during backup or restore processing so you do not need to update the client options file.

    However, if you need to turn off the collection of instrumentation data, set the enableinstrumentation no option in the client options file (dsm.opt on Windows or dsm.sys on UNIX and Linux clients).

    To later enable instrumentation, set enableinstrumentation yes or remove the option from the client options file.

  • To turn API instrumentation on the command-line interface, append the following option to the end of a command: 
    -enableinstrumentation=yes
    To turn off API instrumentation on the command-line interface, append the following option to the end of a command:
    -enableinstrumentation=no

Results

The categories for tracking API activities are different from the client instrumentation categories.

Example

The following example shows the type of data that is collected:
PROCESS[4120] Starting TSM Instrumentation Report: Mon Apr 18 10:43:13 2016

========================>PROCESS[4120] NEW COMMENCE REPORT<========================

-----------------------------------------------------------------------------------
PROCESS[4120] TSM Client final instrumentation statistics: Mon Apr 18 10:43:13 2016

Instrumentation class: API
Completion status: Success

-----------------------------------------------------------------------------------

-----------------------------------------------------------------------------------

Detailed Instrumentation statistics for

Thread: 5472  Elapsed time =     3.354 sec

Section                  Actual(sec)	Average(msec)	Frequency used
-----------------------------------------------------------------------------------
Waiting on App             3.354	    838.5	        4
API Send Data              0.000	      0.0	        3
Other                      0.000	      0.0	        0

-----------------------------------------------------------------------------------

Detailed Instrumentation statistics for

Thread: 4208  Elapsed time =     9.703 sec

Section                  Actual(sec)	Average(msec)	Frequency used
-----------------------------------------------------------------------------------
Waiting on App             4.009	    167.1	       24
API Send Data              4.914	    614.3	        8
API Query                  0.062	     31.2	        2
API End Txn                0.499	    166.4	        3
API Misc                   0.218	     72.8	        3
Other                      0.000	      0.0	        0

-----------------------------------------------------------------------------------

Detailed Instrumentation statistics for

Thread: 2268  Elapsed time =    10.109 sec

Section                  Actual(sec)	Average(msec)	Frequency used
-----------------------------------------------------------------------------------
Waiting on App             9.532	   1361.7	        7
API Query                  0.312	     52.0	        6
API End Txn                0.187	    187.2	        1
API Misc                   0.078	     78.0	        1
Other                      0.000	      0.0	        0

-----------------------------------------------------------------------------------

Detailed Instrumentation statistics for

Thread: 4276  Elapsed time =    18.502 sec

Section                  Actual(sec)	Average(msec)	Frequency used
-----------------------------------------------------------------------------------
Waiting on App            16.193	    476.3	       34
API Query                  0.842	     49.6	       17
API Misc                   1.466	    209.5	        7
Other                      0.000	      0.0	        0

-----------------------------------------------------------------------------------

PROCESS[4120] Ended TSM Instrumentation Report: Mon Apr 18 10:43:32 2016

-----------------------------------------------------------------------------------