rocm-systems/docs/reference/omnitrace-glossary.rst

.. meta::
   :description: Omnitrace documentation and reference
   :keywords: Omnitrace, ROCm, profiler, tracking, visualization, tool, Instinct, accelerator, AMD

*******************
Omnitrace Glossary
*******************

This topic explains the terminology necessary to use Omnitrace. 
The list below provides a basic glossary for those who 
are new to binary instrumentation. It also clarifies ambiguities 
when certain terms have different 
contextual meanings, for example, the Omnitrace meaning of the term "module" 
when instrumenting Python.

**Binary**
  A file written in the Executable and Linkable Format (ELF). This is the standard file 
  format for executable files, shared libraries, etc.

**Binary instrumentation**
  Inserting callbacks to instrumentation into an existing binary. This can be performed 
  statically or dynamically.

**Static binary instrumentation**
  Loads an existing binary, determines instrumentation points, and generates a new binary 
  with instrumentation directly embedded. It is applicable to executables and libraries but 
  limited to only the functions defined in the binary. This is also known as **Binary rewrite**.

**Dynamic binary instrumentation**
  Loads an existing binary into memory, inserts instrumentation, and runs the binary. 
  It is limited to executables but is capable of instrumenting linked libraries. 
  This is also known as **Runtime instrumentation**.

**Statistical sampling**  
  At periodic intervals, the application is paused and the current call-stack of the CPU 
  is recorded along with various other metrics. It uses timers that measure either 
  (A) real clock time or (B) the CPU time used by the current thread and the CPU time 
  expended on behalf of the thread by the system. This is also known as simply **sampling**.

  **Sampling rate**
    * The period at which (A) or (B) are triggered (in units of ``# interrupts / second``)
    * Higher values increase the number of samples

  **Sampling delay**
    * How long to wait before (A) and (B) begin triggering at their designated rate

  **Sampling duration**
    * The amount of time (in real-time) after the start of the application to record samples. 
    * After this time limit has been reached, no more samples are recorded.

**Process sampling**
  At periodic (real-time) intervals, a background thread records global metrics without 
  interrupting the current process. These metrics include, but are not limited to: 
  CPU frequency, CPU memory high-water mark (i.e. peak memory usage), GPU temperature,
  and GPU power usage.

  **Sampling rate**
    * The real-time period for recording metrics (in units of ``# measurements / second``)
    * Higher values increase the number of samples

  **Sampling delay**
    * How long to wait (in real-time) before recording samples

  **Sampling duration**
    * The amount of time (in real-time) after the start of the application to record samples. 
    * After this time limit has been reached, no more samples are recorded.

**Module**
  With respect to binary instrumentation, a module is defined as either the filename 
  (such as ``foo.c``) or library name (``libfoo.so``) which contains the definition 
  of one or more functions.

  With respect to Python instrumentation, a module is defined as the **file** which contains 
  the definition of one or more functions. The full path to this file typically contains the 
  name of the "Python module".

**Basic block**
  A straight-line code sequence with no branches in (except for the entry) and 
  no branches out (except for the exit).

**Address range**
  The instructions for a function in a binary start at certain address with the ELF file 
  and end at a certain address. The range is ``end - start``.

  The address range is a decent approximation for the "cost" of a function. 
  For example, a larger address range approximately equates to more instructions.

**Instrumentation traps**
  On the x86 architecture, because instructions are of variable size, an instruction 
  might be too small for Dyninst to replace it with the normal code sequence 
  used to call instrumentation. When instrumentation is placed at points other 
  than subroutine entry, exit, or call points, traps may be used to ensure 
  the instrumentation fits. (By default, ``omnitrace-instrument`` avoids instrumentation 
  which requires a trap.)

**Overlapping functions**
  Due to language constructs or compiler optimizations, it might be possible for 
  multiple functions to overlap (that is, share part of the same function body) 
  or for a single function to have multiple entry points. In practice, it's 
  impossible to determine the difference between multiple overlapping functions 
  and a single function with multiple entry points. (By default, ``omnitrace-instrument`` 
  avoids instrumenting overlapping functions.)