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:

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

# 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

# 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")