Reading and decoding instrumentation files

Instrumentation .dat files are compacted binary files that can be read only after they are decoded.

How do I start instrumentation logging?
Complete the following steps: 

1. Log into the Process Admin Console as a user in the tw_admins group, such as tw_admin or admin.
   
   For example:
   http://server_name:port_number/ProcessAdmin 
   
   Note: The SECJ0305I might display if this step is run without the base internal users. The user also needs to be a member of the 'AUDITOR' and 'OPERATOR' roles in the WebSphere Application Server configuration. By default, the tw_admin and the specified administrator at install have these rights, for example, admin or bpmadmin.
   
2. Under Monitoring, click Instrumentation.  
3. Click Start Logging to collect data. Note where it stores the file. For example, in IBM Business Process Manager Version 7.5, the file might be stored in the following directory:
   C:\IBM\BPM\v7.5\profiles\ProcCtr01\logs\inst001.dat 
4. Click Stop Logging.
5. Retrieve the file for processing. 

 
How do I to decode the instrumentation .dat files? 
Use the following command to extract the data: 
java -Xmx1024M -cp svrcoreclnt.jar  com.lombardisoftware.instrumentation.log.tools.NonXMLDump inst001.dat >  inst001.txt 
 
Notes: 

• The svrcoreclnt.jar file needs to be in a path that Java can execute. You can copy this file to a separate directory to your desktop to run. The location of  the Java archive (JAR) file is: [install_dir]\Lombardi\lib 
• 1024MB heap will be sufficient for almost all cases.
• inst001.dat is the instrumentation file.
• inst001.txt is a decoded file in the plain text format. 

Reading the decoded file 
The decoded file is a plain text file. Most text editors do not allow you to edit very large files (greater than 25MB). Using a command-line tool, like grep, enables you to quickly search through the entire file. Grep is available in most Linux distributions and there is a free client for Windows as well. 


The instrumentation log files are important because they tell you exactly how long it took for something to run. The following command finds all threads that took longer than 1000 milliseconds (1 second) to complete, which are the threads that you should examine first.
 
grep -E "(THREAD|period [0-9]{4,}ms)" inst001.txt 

Example Sample output: 
>> THREAD Thread-47 << 
>> THREAD WebContainer : 2 << 
03:17:10.356 period 1156ms 'Resume Workflow Engine' { 
03:17:10.418    period 1031ms 'Do Job'  
Worker=com.lombardisoftware.component.javaconnector.worker.JavaConnectorWorker { 
03:17:10.418       period 1031ms 'Java Execution' { 
>> THREAD WebContainer : 13 << 
>> THREAD WebContainer : 16 << 

The time are nested,  1156ms 'Resume Workflow Engine' is running a coach and took 1.2 seconds. Within here, you see 1.0 seconds for executing Java. After this function, there might be another function that took 400 milliseconds.

Example Grep commands
grep.exe -E "(THREAD|period [0-9]{4,}ms)" inst001.txt    - This command finds all calls that are greater than 1 second.

g r ep.exe"  %1 %2 > %2FindItem.txt - These commands find %1 in file %2 and stores the result in a new text file. - grep.exe " 1031ms 'Java Execution' " inst001.txt

grep.exe" -A %1 %2 %3 > %3FindXLines.txt - These commands find a block text after a specific search string and stores it in a text file - grep.exe -A " 1031ms 'Java Execution' 300 inst001.txt