.. _tool_control:

#################
Tool Control
#################

The tool control in neSmiK is the main method to control the backends downstream.

We introduce a small domain specific language that we will explain in this document.


Levels of measurement detail
============================

The currently supported levels of detail are:

==============  ================================================
Level           Description
==============  ================================================
``off``         Disable measurements for the specified region.
``annotate``    tool dependent
``profile``     tool dependent
``trace``       Full tracing with all information.
``forceoff``    Force-disable measurements
==============  ================================================

Each level implies the levels above it. For example, ``trace`` includes both
``profile`` and ``annotate`` functionality.


neSmiK configuration file
============================

You can specify the environment flag ``NESMIK_CONFIG_FILE`` and neSmiK will read
the file following this syntax:

.. code-block::

    # Lines starting with # are comments and are ignored
    # Empty lines are also ignored

    # Initial level directive (optional, must be first statement)
    !trace()

    # Region directives
    !trace("my_region")
    !profile("another_region")
    !annotate("third_region")
    !off("disabled_region")

    # With single invocation number (trace invocation 5 only)
    !trace("my_region" "5")

    # With invocation range (trace invocations 1 through 10)
    !trace("my_region" "1-10")

    # Multiple ranges (profile invocations 2, 5, and 7-15)
    !profile("my_region" "2, 5, 7-15")

.. note::

    Invocation ranges are optional. When omitted, the region is measured for
    all invocations. When specified, only the listed invocations are measured.


Initial Level
-------------

The initial measurement level can be set using the DSL file instead of the
``NESMIK_MEASUREMENT_LEVEL`` environment variable. This is done by specifying a level
directive with empty parentheses as the first statement in the file:

.. code-block::

    # Set initial level to trace
    !trace()

    # Then configure regions
    !annotate("important_region")

If the DSL file contains an initial level directive, it will override the
``NESMIK_MEASUREMENT_LEVEL`` environment variable. The initial level directive must
be the first non-comment, non-empty line in the file.




Environment Variables
-----------------------

``NESMIK_CONFIG_FILE``
    Path to the DSL configuration file. If not set, neSmiK will use default
    settings.

``NESMIK_BACKEND``
    Selects which backend to use. Options depend on compile-time configuration.
    Common options include ``Default``, ``TALP``, ``Extrae::TypeStack``, etc.

``NESMIK_MEASUREMENT_LEVEL``
    Sets the initial measurement level. Overridden by DSL initial level directive.
    Options: ``off``, ``annotate``, ``profile``, ``trace``, ``forceoff``.


Examples
---------

.. code-block::

    # Set initial level to trace
    !trace()

    # Profile MPI operations in "comm" region for invocations 10-50
    !profile("comm" "10-50")

    # Annotate all calls to "init" function
    !annotate("init")

    # Trace "compute" region for invocations 1, 5, and 100-200
    !trace("compute" "1, 5, 100-200")

    # Forcefully disable measurements for "debug" region
    !forceoff("debug")

    # Profile region "allreduce" for all invocations (no range specified)
    !profile("allreduce")