Skip to content

Installation

Jump to bottom
hasherezade edited this page Aug 24, 2024 · 70 revisions

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:

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).

If you have any problems with building the project, you can use the test builds from the AppVeyor server. Select the platform, and then 'Artifacts'. Check the 'Console' output to see what version of Pin is required to use them.

How to compile

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

install dir

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.

tiny_tracer_copied

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.

Retarget solution

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

Release mode

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

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.

TinyTracer DLLs copied

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):

PIN in the context menu

Demo

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

tracing

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.

You can enable/disable features by editing TinyTracer.ini and parameters.txt, located in the install32_64 directory.

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.31)
  • g++, make

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.sig  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    Settings.cpp            TinyTracer.vcxproj  Util.h
FuncWatch.h    make_linux.sh   ProcessInfo.cpp  Settings.h              TraceLog.cpp
install32_64   ModuleInfo.cpp  ProcessInfo.h    TinyTracer.cpp          TraceLog.h
makefile       ModuleInfo.h    README.md        TinyTracer.old.vcxproj  Util.cpp

In order to automatically build both 32 and 64 bit version, and place them in the required directory (install32_64 ), 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. Each of them should contain TinyTracer.so. The script will automatically copy each version of TinyTracer into install32_64 directory, under the names, appropriately, TinyTracer32.so and TinyTracer64.so.

If everything went fine, the script will finish its execution with printing:

[+] 64 bit build ok.
[+] 64 bit install ok.
[+] 32 bit build ok.
[+] 32 bit install ok.

How to install

Assuming that you built TinyTracer with make_linux.sh and you have both components in place, now you can trace applications using tiny_runner.sh. If you didn't change the recommended path, this script does not require any modifications. Otherwise you need to edit the paths within a script accordingly.

The script contains absolute paths to all the components, so it can be copied to any directories of your choice.

In order to make PIN tracing available from any directory (without the need of copying the script), you can add a symbolic link to your local bin directory:

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

Optionally, you can also create a link to the directory with tiny_tracer configuration, to have an easy access to them. For example:

ln -s $HOME/pin/source/tools/tiny_tracer/install32_64/ $HOME/Desktop/install32_64

Demo

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.2
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 the install32_64 directory.

Tiny Tracer Wiki, by hasherezade

Clone this wiki locally