.. _using_backends: ############## Using Backends ############## In this section you can find useful information of the different backends currently implemented. To use them just specify the ``NESMIK_BACKEND`` environment variable to the **case-sensitive** backend name. E.g. ``NESMIK_BACKEND=Default`` .. note:: .. csv-table:: TL;DR :header: "``NESMIK_BACKEND=``", "Requires", "Short Description" "``Default``", , "Prints every region start and stop to `stdout`." "``Detection``", , "Helps identify problems with the annotation." "``Extrae::TypeStack``", "`EXTRAE`", "Creates paraver events for each annotation." "``TALP``", "`DLB`", "Simple wrapper around TALP monitoring regions." "``TALP::Tree``", "`DLB`", "Call-stack sensitive wrapper to TALP monitoring regions." "``CaPI``", "`DLB`", "Uses hash values of callstack as region identifiers." "``CaPIColl``", "`DLB`", "Like CaPI but detects hash collisions." "``NSYS``", "`CUDA`", "Can control the NVIDIA nsys tracer" "``OTF-CPT``", "`MPI`", "Uses MPI Pcontrol to control the OTF-CPT" "``SCOREP``", "`MPI`", "Emits anonymous SCOREP regions" "``MERIC``", "`MERIC`", "Wrapper around MERIC monitoring regions" ******************** Independent backends ******************** These backends don't require any dependency and are always provided, and are helpful to solve problems that you might encounter with the annotation. ``Default`` =========== The ``Default`` backend implements both **Properly Nested** and **Not Properly Nested** versions. This backend will just print the region name to the `stdout` and can be used to check if neSmiK is working correctly. ``Detection`` ============= This backend helps users to identify problems with their annotation. It checks the annotations if they are actually properly nested or not and tries to help with problematic regions that are not properly nested. It also checks if annoatations are called from multiple threads, as not all backends support that. Options ------- * ``NESMIK_DETECTION_SHOW_ALL_REGIONS`` Report summary for all regions. If disabled, only regions with odd behaviour will be reported. (default:off)" *************** Extrae Backends *************** .. note:: Requires neSmiK to be configured with ``-DWITH_EXTRAE=ON`` To use the Extrae backends you need to set up an Extrae run as usual, and also set the ``NESMIK_BACKEND``. Here is an example for the ``Extrae::TypeStack`` backend: .. code-block:: bash export NESMIK_BACKEND="Extrae::TypeStack" export EXTRAE_CONFIG_FILE="./extrae.xml" # where you put you extrae configuration mpirun -n env LD_PRELOAD=${EXTRAE_HOME}/lib/libmpitrace.so ./test ``Extrae::TypeStack`` ======================= The ``Extrae::TypeStack`` provides a way to get your annotations into paraver. Options --------- * ``NESMIK_EXTRAE_WRITE_CONFIG_FILE`` When setting this to a boolean variable (1,0) the backend will generate corresponding `.cfg` files to view the anntation in the directory the application was run from. .. _backends_post_process_traces: Post-process traces ------------------- We recommend to use `pertalde `_ to postprocess the generated trace, as the semantic values of the region string are their hash values. Using ``pertalde unir -p nesmik `` will post-process the trace to make all the values of neSmiK regions start at 1, and increment them for each semantic, which is highly beneficial as Paraver does not support arbitrary value ranges for histograms. Additionally, if you have multiple traces you can unify them all with the same command, which will ensure that all the traces share the values for the same semantics, for example ``pertalde unir -p nesmik trace1.prv trace2.prv``. ************ DLB Backends ************ .. note:: Requires neSmiK to be configured with ``-DWITH_DLB=ON`` To use the DLB backends you still need to configure your execution to run with DLB. This requires preloading the right DLB library and setting the correct ``DLB_ARGS``. For example, for the ``TALP`` backend: .. code-block:: bash export NESMIK_BACKEND="TALP" export DLB_ARGS="--talp" mpirun -n env LD_PRELOAD=${DLB_HOME}/lib/libdlb_mpi.so ./test ``TALP`` ======================= The ``TALP`` backend is a simple wrapper into the TALP module of the `DLB Library. `_ ``TALP::Tree`` ======================= The ``TALP::Tree`` backend is a call path sensitive wrapper of TALP monitoring regions. This backend will create a monitoring region for each unique hierrarchy of regions. ``CaPI`` ======================= The ``CaPI`` backend uses the hash value of the callstack as the region identifier. This is useful when you have many different regions with the same name but different call paths, as TALP will treat each unique call stack as a separate region. Using a special toolchain an annotated metacg callgraph can be resconstructed and used with other CAPI based tools. ``CaPIColl`` ======================= The ``CaPIColl`` backend is identical to the ``CaPI`` backend (a wrapper around TALP that uses hash values of the callstack as region identifiers), but with additional collision detection. It monitors for hash collisions where different call stacks produce the same hash value. When collisions are detected, they are reported in the console output from MPI rank 0. This backend is useful for debugging and verifying whether hash collisions could be affecting the accuracy when using the ``CaPI`` backend. Options --------- * ``NESMIK_JSON_OUTPUT``: Enable output to a JSON file. (default: ``on``) * ``NESMIK_JSON_FILE``: Set the name of the output JSON file. (default: ``capinesmik_collision_detection.json``) Nvidia Nsight Systems (nsys) Backends ======================================= .. note:: Requires neSmiK to be configured with ``-DENABLE_NSYS=ON`` ``NSYS`` ======================= The ``NSYS`` backend is a simple wrapper into the `NVTX Library. `_ All the neSmiK annotations are separated into a `domain `_ called ``neSmiK``, to not interfere with other annotation libs. ******************* OTF-CPT Backend ******************* .. note:: Requires neSmiK to be configured with ``-DENABLE_OTFCPT=ON`` and ``-DWITH_MPI=ON`` The ``OTF-CPT`` backend writes traces in OTF-CPT format, which can be analyzed with the `CPS Tool `_. To use: .. code-block:: bash export NESMIK_BACKEND="OTF-CPT" mpirun -n ./test ******************* SCOREP Backend ******************* .. note:: Requires neSmiK to be configured with ``-DENABLE_SCOREP=ON`` and ``-DWITH_MPI=ON`` The ``SCOREP`` backend integrates with the `SCOREP `_ profiling infrastructure. All neSmiK regions are recorded as SCOREP user regions. To use: .. code-block:: bash export NESMIK_BACKEND="ScoreP" mpirun -n ./test ******************* MERIC Backend ******************* .. note:: Requires neSmiK to be configured with ``-DENABLE_MERIC=ON`` and ``-DMERIC_DIR=`` The ``MERIC`` backend integrates with the `MERIC `_ performance measurement infrastructure. MERIC can measure energy and performance of specific code regions. To use: .. code-block:: bash export NESMIK_BACKEND="MERIC" ./test Options --------- * ``NESMIK_MERIC_ENUMERATE``: Comma-separated list of region names to enumerate. When set, MERIC will create unique measurements for each invocation of the specified regions by appending ``___0``, ``___1``, etc. to the region name. This is useful for measuring multiple iterations of the same region separately. Example: .. code-block:: bash export NESMIK_MERIC_ENUMERATE="region1,region2" ./test