Turning on tracing for the ITCAM ARM DLL is now easier than ever.

Client Application Tracker Agent

Goto the $ITMHOME/tmaitm6/arm/log/cat directory do one of the following:

1. Create a file named debug_all.txt - This turns on DLL level tracing for all processes.
2. Create a file named debug_<pid>.txt – This turns on DLL level tracing only for the specified process.

This turns on debugging until you delete the file, and then the tracing turns off.

Robotic Agent

Goto the $ITMHOME/tmaitm6/arm/log/kt6 directory do one of the following:

1. Create a file named debug_all.txt - This turns on DLL level tracing for all processes.
2. Create a file named debug_<pid>.txt – This turns on DLL level tracing only for the specified process.

This turns on debugging until you delete the file, and then the tracing turns off. Be aware that this will incur significant overhead and only leave it on as long as you need it.

General Notes

If both agents are on the same machine, then you will use the CAT instructions for all ARM applications except our robotic agents.

All logging will goto (ensure the directories exist before you turn logging on, or you won't get any logging).

Windows:

C:\program files\ibm\tivoli\common\bwm\logs\trace-armdebug.log

Unix:

/opt/ibm/tivoli/common/bwm/logs/trace-armdebug.log

Important things to keep in Mind

• Also keep in mind that the files sizes are not limited and do not rollover, so you will need to turn off tracing and delete the files when you are done.
• Tracing every ARM call will incur significant overhead and you should only leave it on as long as you need it.

Probably the most common question I get asked is "How do I configure Websphere and/or DB2 to issue ARM calls?". Below is the answer, enjoy!

General Requirements

1. DB2 Distributed Version 8.2 (or 8.1 FP11)
   1. Only non-zos DB2 8.2+ supports ARM, and it supports ARM v4
2. Websphere Application Server 5.1 or higher
   1. Only Sebsphere can pass correlators to DB2, and DB2 will not issue ARM calls unless a correlator is received for the connection.

Step 1: (RT 6.2 only )Install the Client Application Monitoring Agent

    The CAT agent is the agent that supports Generic ARM instrumentation. Installing it automatically installs support for all ARM instrumented applications (t4 is it's prefix as you will see in paths below).

Step 2: Configure Websphere

1. Set a custom property (Application Servers->server1->ProcessDefinition->Java Virtual Machine -> Custom Properties) of ws.ext.dirs equal to the values below ( which will include the armjni4.jar, armjni4.dll and libarm4.dll files. ) – Key is to have ws.ext.dirs point to where the armjni4.jar file is located at.

ITCAM for RT 6.2 and above only 

1. Setup websphere to include the armjni4.jar file in it's library path. $ITMHOME defaults to c:\ibm\itm for windows and /opt/IBM/ITM/ for unix.
   1. Windows - set ws.ext.dirs $ITMHOME\tmaitm6\t4\lib
   2. Linux - $ITMHOME/li6243/kt4/lib/
   3. AIX - $ITMHOME/aix51/kt4/lib/
   4. HPUX - $ITMHOME/ hpx1111/kt4/lib/
   5. Solaris - $ITMHOME/ sol283/kt4/lib/
2. Set your LD_LIBRARY_PATH  to include the ARM libraries (before runing ./startServer.sh on unix)
1. Windows - You can skip this step since ITM automatically includes c:\ibm\itm\tmaitm6\ in your system path. You might need to reboot for it to take effect if you haven't rebooted since you first installed ITM framework.
2. Linux    - Set your LD_LIBRARY_PATH=  $ITMHOME/li6243/kt4/lib/
3. AIX      - Set your LIBPATH=  $ITMHOME/aix51/kt4/lib/
4. HPUX    - Set your SHLIB_PATH= $ITMHOME/hpx1111/kt4/lib/
5. Solaris  - Set your LD_LIBRARY_PATH= $ITMHOME/sol283/kt4/lib/

ITCAM for RTT 5.3, 6.0, 6.1 only 

1. Setup websphere to include the armjni4.jar file in it's library path. $MAHOME defaults to c:\Program files\IBM\Tivoli\MA for windows and /opt/IBM/tivoli/MA for unix.
1. ws.ext.dirs=$MAHOME\lib
2. Set your LD_LIBRARY_PATH  to include the ARM libraries
1. Windows – set your PATH to include $MAHOME\bin\w32-ix86\SYSTEM32\
2. Linux x86- set LD_LIBRARY_PATH to $MAHOME/bin/linux-ix86/USRLIB/
3. Linux PPC - set LD_LIBRARY_PATH to $MAHOME/bin/linux-ppc/USRLIB/
4. Linux s390 - set LD_LIBRARY_PATH to $MAHOME/bin/linux-s390/USRLIB/
5. AIX - set LIBPATH to $MAHOME/bin/aix4-r1/USRLIB/
6. HPUX - set SHLIB_PATH to $MAHOME/bin/hpux10/USRLIB/
7. OS/400 - set LIBPATH to $MAHOME/bin/os400/USRLIB/
8. Solaris2 - set LD_LIBRARY_PATH to $MAHOME/bin/solaris2/USRLIB/

Required for All Versions

1. Configure request metrics
   1. Detail Level you want (Monitoring and Tuning -> Request Metrics)
      The detail level you want:
      1. HOPS – Entry and exit only. Lowest overhead and only gives overall transaction performance.
      2. Performance_DEBUG – Medium overhead and higher detail. Includes Session Beans etc.
      3. DEBUG – Highest overhead and the most detail. Gives Entity bean get/set timings
   2. Set the Request metrics destination to ARM agent
   3. Set the agent type to ARM4
   4. Set the ARM factory to com.ibm.tivoli.transperf.arm4.transaction.Arm40TransactionFactory
2. To enable correlator passing to DB2 (required for DB2 to issue ARM calls) do the following
   define this custom JVM property: com.ibm.websphere.pmi.reqmetrics.PassCorrelatorToDB to true;
   To set custom properties, you can either specify the command as a -D option to the Java™ command, or connect to the administrative console and navigate to the Java virtual machine custom properties panel:
   Application server Servers > Application Servers > server1, and then, under Server Infrastructure, click Java and Process Management > Process Definition > Java Virtual Machine > Custom Properties
   Custom Properties Documentation

   

3. Restart websphere.
4. Websphere should now be issuing ARM calls when you navigate through it's servlets. Additionally it should be passing correlators to DB2.

Step 3: Configure DB2 for ARM support

    DB2 register with ARM if it finds a libarm4.dll (.a/.so) in it's LIBPATH. In order to issue actual start/stop calls for transactions it requires a correlator be passed in with the JDBC connection, which we configured above inside of WAS. To configure the DB2 LIBPATH issue the following command from within the DB2 environment:

db2set DB2LIBPATH=<libarm4.dll directory location>

Where <libarm4.dll directory location> is equal to one of the paths below:

1. ITCAM for RT 6.2 and above – $ITMHOME defaults to c:\ibm\itm for windows and /opt/IBM/ITM/ for unix.
   1. Windows - $ITMHOME\tmaitm6\
   2. Linux - $ITMHOME/li6243/t4/lib/
   3. AIX - $ITMHOME/aix51/t4/lib/
   4. HPUX - $ITMHOME/ hpx1111/t4/lib/
   5. Solaris - $ITMHOME/sol283/t4/lib/
2. ITCAM for RTT 5.3, 6.0, 6.1 - $MAHOME defaults to c:\Program files\IBM\Tivoli\MA for windows and /opt/IBM/tivoli/MA for unix.
   1. Windows - $MAHOME\bin\w32-ix86\SYSTEM32\ AND $MAHOME\lib
   2. Linux x86- $MAHOME\bin\linux-ix86\USRLIB\ AND $MAHOME\lib
   3. Linux PPC - $MAHOME/bin/linux-ppc/USRLIB
   4. Linux s390 - $MAHOME/bin/linux-s390/USRLIB
   5. AIX - $MAHOME/bin/aix4-r1/USRLIB/
   6. HPUX - $MAHOME/bin/hpux10/USRLIB/
   7. OS/400 - $MAHOME/bin/os400/USRLIB
   8. Solaris - $MAHOME/bin/solaris2/USRLIB/

Updated: 10/25/2007 – Corrected path windows for ws.ext.dirs and where to set the custom properties.
Updated: 6/5/2008 - setting java.library.path doesn't work, you have to manually set your library path before starting websphere on unix.