.. _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." "``Extrae::PartialTracer``", "`Extrae`", "Provides a mechanism to turn Extrae ON/OFF." "``TALP``", "`DLB`", "Simple wrapper around TALP monitoring regions." "``TALP::Tree``", "`DLB`", "Call-stack sensitive wrapper to TALP 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_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``. ``Extrae::PartialTracer`` =========================== The ``Extrae::PartialTracer`` is a easy ways to implement partial tracing using Extrae. Its a very powerful and simple way to programmatically call ``Extrae_shutdown`` and ``Extrae_restart`` for regions in your application. A very good example would for example be, if the user only wants to trace the "timestep" region and not get a trace for the initialization phase of the application. The regions will also part of the trace, as this backend internally also uses the ``TypeStack`` backend. The backend has quite a lot of options, so read them carefully before using it :) In this case we also recommend post-processing the trace with `pertalde `_, go to :ref:`backends_post_process_traces` for more information. Options --------- * ``NESMIK_PARTIAL_TRACER_REGION_NAMES``: Comma separated list of region names where tracing should be enabled. E.g. ``"timestep,timestep,finalize"`` * ``NESMIK_PARTIAL_TRACER_START_AT_CALL``: Comma separated list of the invocation numbers (starting at 0) at which encounter of the region tracing should start. E.g. ``"0,99,0"`` * ``NESMIK_PARTIAL_TRACER_STOP_AT_CALL``: Comma separated list of the invocation numbers (starting at 0) at which encounter of the region tracing should stop. E.g. ``"0,100,0"`` * ``NESMIK_PARTIAL_TRACER_ADD_ALL_REGIONS``: Boolean indicating if region information should be added into the trace if tracing is disabled. Default: False The examples above would generate a partial tracing configuration, where ``Extrae_shutdown`` is called directly after the initialization of neSmiK. Then when encoutering the region ``timestep`` the first time, ``Extrae_restart`` would be called. At the ``nesmik_region_stop("timestep")`` ``Extrae_shutdown`` would be called. The configuration shown above would then keep extrae disabled for the rest of the execution, and at the 100 timestep region invocation would enable it again until the 101 ends. It was also enable Extrae interception of runtimes at the first encounter of the ``finalize`` region. ************ 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. Options --------- * ``NESMIK_ASCII_OUTPUT``: Enable human readable output to standard output. (default: ``off``) * ``NESMIK_JSON_OUTPUT``: Enable output to a JSON file. (default: ``on``) * ``NESMIK_JSON_FILE``: Set the name of the output JSON file. (default: ``nesmik_talp_tree.json``) ************* NVTX Backends ************* .. note:: Requires neSmiK to be configured with ``-DWITH_NVTX=ON`` ``NVTX::Stack`` ======================= The ``NVTX::Stack`` 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.