Installation

Prerequisites

Tiny Tracer is a PIN tool, it means in order to run it you need Intel PIN platform.

Intel PIN is available for free here. PIN's license does not allow for distribution of the tools in a compiled form, that's why you need to compile them from the sources.

On Windows

To compile Tiny Tracer, you need:

• Pin : a version relevant to the particular release (the last tested was 3.22)
  • If you need to use Pin < 3.19, use TinyTracer.old.vcxproj - works for Pin: 3.16 - 3.18
• Visual Studio : minimum 2012

NOTE: Since the version 3.20 Pin has dropped a support for old versions of Windows. If you need to use the tool on Windows lower than 8, try to compile it with Pin 3.19 (or below).

How to compile

Once you downloaded the PIN platform, you need to unpack it to your destination directory. The recommended path is C:\pin:

You can use any path of your choice, just remember that it will cause you to have some additional work editing some paths during installation.

Once you have your PIN unpacked, you need to clone/copy the sources of tiny tracer into \source\tools. For the default configuration to work, the root directory of TinyTracer should be: tiny_tracer.

Now open the TinyTracer.vcxproj in Visual Studio. For the purpose of backward compatibility, the project is targeted to Visual Studio 2012, but you can easily retarget it to any newer version. To do so, right click on the solution head, and choose Retarget solution from the menu.

Compile 2 versions of the TinyTracer.dll: 32 and 64 bit in a Release mode.

After compiling the sources, you can use a batch script: move_dlls.bat:

The script will move both versions of the compiled DLL into the installation directory under the desired names: TinyTracer32.dll and TinyTracer64.dll.

How to install

The TinyTracer can be added to the context menu, so that you can trace conveniently any executable of your choice. If your PIN platform is in C:\pin, you don't have to make any changes in the scripts.

Go to the directory install32_64, where the installation toolkit is located.

If you had the TinyTracer already installed, make sure that you remove the previous installation by running delete_menu.reg before you continue.

Then, read the README.txt, to confirm that all the paths are set valid. If everything is OK, you can run the add_menu.reg in order to add your PIN tracer to the context menu.

As a result you should see the additional option Run with PIN (Tiny Tracer):

If the setup was correct, running the executable with PIN will cause a similar info to show up:

As the execution progress, the log will be saved in a file with a .tag extension.

For viewing the log in real-time I recommend Baretail.

Attaching to an existing process

Running the application via Pin is possible with the help of the installed menu. However, sometimes we may need to attach to already running application. It can be done with the help of the script pin_attach.bat.

The script should be run from a commandline, and provided two parameters:

• a path to the module (within the given process) that we want to trace
• a target PID

Example:

C:\pin\source\tools\tiny_tracer\install32_64>pin_attach.bat "C:\Users\tester\Desktop\test_app.exe" 8924

On Linux

To compile Tiny Tracer, you need:

• Pin : a version relevant to the particular release (the last tested was 3.22)

How to compile

Once you downloaded the PIN platform, you need to unpack it to your destination directory. The recommended path is $HOME/pin.

cd $HOME/pin
~/pin$ ls
doc  extras  ia32  intel64  licensing  pin  pin.log  pin.sig  pintool.log  README  source

Once you have your PIN unpacked, you need to clone/copy the sources of tiny tracer into /source/tools. For the default configuration to work, the root directory of TinyTracer should be: tiny_tracer.

~/pin/source/tools/tiny_tracer$ ls
FuncWatch.cpp  makefile.rules  move_dlls.bat    ProcessInfo.h  tiny_runner.sh          TraceLog.cpp
FuncWatch.h    make_linux.sh   obj-ia32         README.md      TinyTracer.cpp          TraceLog.h
install32_64   ModuleInfo.cpp  obj-intel64      Settings.cpp   TinyTracer.old.vcxproj  Util.cpp
makefile       ModuleInfo.h    ProcessInfo.cpp  Settings.h     TinyTracer.vcxproj      Util.h

In order to automatically build both 32 and 64 bit version, you can use the script make_linux.sh.

~/pin/source/tools/tiny_tracer$ ./make_linux.sh 

If the compilation was successful, two output directories have been created: obj-intel64 and obj-ia32. Make sure that each of them contains TinyTracer.so

~/pin/source/tools/tiny_tracer$ ls obj-intel64/TinyTracer.so 
obj-intel64/TinyTracer.so
~/pin/source/tools/tiny_tracer$ ls obj-ia32/TinyTracer.so 
obj-ia32/TinyTracer.so

How to install

Now you can run your applications via TinyTracer using tiny_runner.sh. If you didn't change the recommended path, the script does not require any modifications. Otherwise you need to edit the paths within a script accordingly.

The script is can be copied to any directories of your choice.

In order to make PIN tracing available from any directory, you can add a symbolic link to your local bin directory:

ln -s $HOME/pin/source/tools/tiny_tracer/tiny_runner.sh ~/bin/tiny_runner.sh

Example of tracing:

~/Desktop/pin_tests$ tiny_runner.sh ./demo

Linux runner for Tiny Tracer
Usage: <target_app> [target_module*]
*-optional; default: target app's main module
Traced App: ./demo
Traced Module Name: demo
The app is 64 bit.
Watch 5 functions
Watch 0 syscalls
===============================================
This application is instrumented by TinyTracer v.2.1
Tracing module: demo
See file ./demo.tag for analysis results
===============================================
Hello World!

As the execution progress, the log will be saved in a file with a .tag extension.

You can enable/disable features by editing TinyTracer.ini and parameters.txt, located in PIN_CONFIGS_DIR that is by default defined as $HOME/pin/source/tools/tiny_tracer/install32_64/.