************************************************************************************
* Copyright 2009 Syed Ali Jafar Naqvi
* *
* This file is part of Java Call Tracer. *
* *
* Java Call Tracer is free software: you can redistribute it and/or modify *
* it under the terms of the Lesser GNU General Public License as published by *
* the Free Software Foundation, either version 3 of the License, or *
* (at your option) any later version. *
* *
* Java Call Tracer is distributed in the hope that it will be useful, *
* but WITHOUT ANY WARRANTY; without even the implied warranty of *
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
* Lesser GNU General Public License for more details. *
* *
* You should have received a copy of the Lesser GNU General Public License *
* along with Java Call Tracer. If not, see <http://www.gnu.org/licenses/>. *
************************************************************************************
What is it all about?
---------------------
This tool helps you to record and print call trace of a java program. It has 2 modes of recording
1] Uncontrolled - In this mode the functioning of the tool is not controlled by the user.
2] Controlled - In this mode all the functions of the tool is controlled by the user. This mode also has an additional action "Flush"
Here is a table that explains the two modes of the tool in detail
-------------------------------------------------------------------------------------------------
Tool Action | Start Stop Print Prints to Flush
------------|------------------------------------------------------------------------------------
Tool Mode |////////////////////////////////////////////////////////////////////////////////////
-------------------------------------------------------------------------------------------------
Uncontrolled| JVM start JVM Shutdown JVM Shutdown File N/A
-------------------------------------------------------------------------------------------------
Controlled | User Trigger User Trigger User Trigger File & UI User
| & JVM Shutdown & JVM Shutdown Trigger
-------------------------------------------------------------------------------------------------
The tool comes with a web component that can be used with a J2EE application to initiate the different actions (mentioned in the above table).
This tools can present the output in 2 different formats
a] xml
b] text
You can also define exclusive and inclusive filters to control the recording. This is explained in detail in later sections.
This tool is thread safe.
How does it work?
-----------------
This tool is based on JVMPI (Java Vertual Machine Profiler Interface) and JNI (Java Native Interface). Using JVMPI (just like how profilers work) this tool records specific events like
a] Call Load
b] Call Unload
c] Method Call
d] Method Exit
e] Thread Start
f] Thread End
g] JVM Start
h] JVM Shutdown
from the JVM and build a call trace.
But this interface only worked till JDK 1.4, in higher JDK versions (1.5 and above) Sun has created a new interface called JVMTI (Java Virtual Machine Tooling Interface). This tool also comes in 2 versions calltracer2.dll is compatible with JDK 1.4 whereas calltracer5.dll is compatible with JDK 5 and above.
How to use the tool
-------------------
Add the following JVM options before running your Java program.
For JDK 1.5 and above
-agentpath:[full-path-to-folder-of-dll]\calltracer5.dll=traceFile-[trace-file],filterFile-[filter-file],filterList-[filter|filter|...],outputType-[xml or text],usage-[controlled, uncontrolled] -Djava.library.path=[full-path-to-folder-of-dll] -Dcalltracerlib=calltracer5
-agentpath:C:\calltracer\jvmti\calltracer5.dll=traceFile-C:\calltracer\call.trace,filterFile-C:\calltracer\filters.txt,outputType-xml,usage-uncontrolled -Djava.library.path=C:\calltracer\jvmti -Dcalltracerlib=calltracer5
Note: Dont forget to add the path (folder containing the dll) to the native library path prefix of your server, when running under an application server. Also in case you are running this tool with an application server try not to use -Djava.library.path option and use the application server's administration tool to configure the native library path prefix.
For JDK 1.4
-Xruncalltracer2:traceFile=[trace-file],filterFile=[filter-file],filterList=com.test,outputType=[xml or text],usage=[controlled, uncontrolled] -Djava.library.path=[full-path-to-folder-of-dll] -Dcalltracerlib=calltracer2
-Xruncalltracer2:traceFile=C:\calltracer\call.trace,filterFile=C:\calltracer\filters.txt,usage=uncontrolled -Djava.library.path=C:\calltracer\jvmpi -Dcalltracerlib=calltracer2
Note: If you get an error "Could not find -Xrun library: calltracer2.dll" (with jdk 1.4) all you need to do is set the folder in which calltracer2.dll is placed in the Path of Windows.
If you are using this tool to record a J2EE application flow in controlled mode, you can use the web component shipped with the tool to control the recording, printing and flushing. Just plug the web component into your J2EE application and you are good to go.
You can also take out the JNI class and code your own UI and controls (just see the code inside the CallTracerAction class).
For example if I have a J2EE application that does not have a web interface and I do not want to add a web component to it then I can easily take out the CallTracerJNI class, put it along with my other classes (please note not to change the package of the CallTracerJNI class) and then call the methods of this JNI class to either build my own control interface or just call the methods from different methods of my application classes.
Options Explained
-----------------
traceFile - The file where the output of the tool will be redirected. Default value is
"call.trace". You have to provide the full path to the file.
filterFile - The file where the inclusive and exclusive filters are listed. The filters are
separated by new line. You have to provide the full path to the file. This is not
a required option.
filterList - List of | separated filters. This is not a required option.
outputType - xml or text. Specifies the output format. Default value is "xml".
usage - controlled or uncontrolled. Specifies the mode of the tool. Default value is
"uncontrolled"
callThershold - Max method calls that will be recorded from a method. Default value is -1 which means unlimited.
Note that the filters can be specified in a file using filterFile option and at the same time as a list of | separated values using filterList option. In other words you can use filterFile and filterList options together.
Please note all options are case sensitive.
How to define Filters
---------------------
The filters work in the similar way as log4j. You can define filters as a list of | separated values in the JVM option using the filterFile option or inside a file using the filterFile option or both. A filter is basically a substring or a full string of a fully qualified class name. It its a substring then it needs to match from the start. For example, if the name of the class is com.test.TestClass then the matching filters will be
com or com.test or com.test.TestClass or com.t
However the following will not match
om.test.TestClass or com.test.TestClass1 or test or TestClass
By default (if no filters provided) all classes are excluded for recording i.e. none of the classes are recorded. However in a real usage you would want to control the recording. In order to achieve this, the tool offers 2 type of filters
1] Inclusive Filters - These tell the tool that the classes belonging to this category of filters need to be recorded or should not be filtered out. These are just specified as shown in the above example.
2] Exclusive Filters - These tell the tool that the classes belonging to this category of filters need to be filtered out or not recorded. These are specified by prefixing a ! character to an inclusive filter.
In this example I will try and explain the usage of the Inclusive and Exclusive filters
Lets say the filters are specified as
!com.test
com.test.TestClass
This specification tells the tool not to record any class that belongs to the package com.test except class com.test.TestClass (which will be recorded).
Please note here that the name of the calss has to be what the JVM reads it as. This means that you might have named you class com.test.TestClass but some JVMs see this name as com/test/TestClass or Lcom/test/TestClass. If in doubt you can define 3 entries for each filter. For example if I have to define a filter as com.test I would define 3 filters
com.test
com/test
Lcom/test
This type of definition would make sure that no matter what the JVM, the filters will work.
The Web Component
-----------------
The web component shipped with this tool offers Start, Stop, Print and Flush actions. Once you plug this into your J2EE application you can access the UI of this component by
http://[host:port]/CallTracer
Compatibility
-------------
This tool has been compiled to run on Windows environment.
However since the tool is written in C it can easily be ported to other environments like Solaris or Linux etc, that have a c compiler. The other principles are same.
Drawbacks
---------
1] This tool might make your application to run a little slower (it is a very minor degradation). But given the fact that it can be started and stopped (in the controlled mode) its not a big issue.
2] When running the tool to record a J2EE application, it is possible that sometimes two different application flows are reported in the same thread. This is because application server does thread pooling, i.e. it uses the same thread object time and again. This is also not a big issue as the two flows will be listed as siblings under the same thread.
Downloading the tool
--------------------
To download the tool goto https://sourceforge.net/projects/javacalltracer/files/ and under the latest version you will find the Calltracer and Calltrace2Seq folders. You can download the files under these folders (and sub-folders) as needed.
Running the calltracer.exe
--------------------------
The calltracer.exe helps you generate a sample output of the Calltracer tool. This exe was built by defining #define TEST_MYTRACE at the top of the ctrace.c file. You can recompile the exe by defining #define TEST_MYTRACE at the top of the ctrace.c file and running the nmake all command from the javacalltracer\Calltracer\test folder (Make sure you make appropriate changes to the javacalltracer\Calltracer\test\Makefile first).
To run the exe just type calltracer.exe [trace file name] from the javacalltracer\Calltracer\test folder.
e.g.
calltracer.exe c:\calltracer\test.txt
In case you need to compile and build the DLL again
---------------------------------------------------
Using VC++ on Windows
1) Download VC++ Express 5 using the link http://go.microsoft.com/fwlink/?LinkId=51410&clcid=0x409
2) Install it an register it (its free)
3) It typically gets installed under C:\Program Files\Microsoft Visual Studio 8\VC
4) Open the command prompt and goto the C:\Program Files\Microsoft Visual Studio 8\VC folder.
5) In the command prompt enter vcvarsall.bat (this will setup the env variables) and goto step 6
Using g++ on Windows
1) Download and install MinGW or Cygwin with the gcc and g++ packages and goto step 6
Using g++ on other OS
1) Make sure that the g++ package is installed and goto step 6
6) Goto the calltracer folder (using command prompt)
7) Open the ctrace.c file in textpad (or any editor), this file is inside src folder of the calltracer folder
For JVMPI
7) At the top of the file make sure that #define JVMPI_TYPE is uncommented and #define JVMTI_TYPE & #define TEST_MYTRACE are commented
8) Goto jvmpi folder (using command prompt)
9) Check the Makefile and make the appropriate changes there as specified
10) run the "nmake clean" command (using command prompt)
11) run the "nmake all" command (using command prompt)
For JVMTI
7) At the top of the file make sure that #define JVMTI_TYPE is uncommented and #define JVMPI_TYPE & #define TEST_MYTRACE are commented
8) Goto jvmti folder (using command prompt)
9) Check the Makefile and make the appropriate changes there as specified
10) run the "nmake clean" command (using command prompt)
11) run the "nmake all" command (using command prompt)
Support
-------
Please write to Syed Ali Jafar Naqvi at ali.jafar@gmail.com for any support regarding this tool.
Download Latest Version
javacalltracer.zip (9.6 MB)
