Quickstart
----------

**1. Build**

Recorder requires MPI and HDF5 to build. Please make sure they are installed
before building Recorder.

Run the following to fetch, build, and install Recorder.
In this example, we will install Recorder under its srouce directory.
You can change the install localtion by modifying ``$RECORDER_INSTALL_PATH`` below. 

.. code:: bash

   git clone https://github.com/uiuc-hpc/Recorder.git
   cd Recorder
   export RECORDER_INSTALL_PATH=`pwd`/install
   git submodule update --init --recursive
   mkdir build
   cd build
   cmake .. -DCMAKE_INSTALL_PREFIX=$RECORDER_INSTALL_PATH
   make
   make install


**2. Trace an application**

Make sure ``$RECORDER_INSTALL_PATH`` points to the location where you installed Recorder.
Now let's run an application with Recorder to collect it traces.
We will use an example MPI program as our targeting application.
Go to the Recorder's source directory and run the following.

.. code:: bash

    cd test && mpicc test_mpi.c -o test_mpi
    mpirun -np N -env LD_PRELOAD $RECORDER_INSTALL_PATH/lib/librecorder.so ./test_mpi

    # On HPC systems, you may need to use srun or 
    # other job schedulers to replace mpirun, e.g.,
    srun -n4 -N1 --overlap --export=ALL,LD_PRELOAD=$RECORDER_INSTALL_PATH/lib/librecorder.so ./test_mpi

Once completed, you will see a folder named ``recorder-yyyymmdd``. This is a parent folder
that contains all traces folders generated on *yyyymmdd*.
Inside it, you will find the actual trace forlder of the application you just run.
The folder name follows the format of ``HHmmSS.ff-hostname-username-appname-pid``.

**3. Examine the traces**

Recorder provides several useful tools under ``$RECORDER_INSTALL_PATH$/bin`` for analysis purposes.

*recorder-summary* can be used to reports high-level statistics:

.. code:: bash

   $RECORDER_INSTALL_PATH/bin/recorder-summary /path/to/your_trace_folder/

*recorder2text* is used to convert the Recorder-format traces to plain text files.

.. code:: bash

   $RECORDER_INSTALL_PATH/bin/recorder2text /path/to/your_trace_folder/

This will generate text fomart traces under ``/path/to/your_trace_folder/_text``.
You will see *N* [pid].txt files, where *N* is the number processors you run your application.
Each of these txt files contains the traces generated by one processor indicated by the [pid].