Basics

Note

This manual focuses on the python bindings. For a definite reference to attributes of definitions or events, please read the documentation of the C interface: manual (available if built correctly)

Definitions

OTF2 specifies over twenty different definitions, which are used to represent the state of the application at the start of the tracing. Most definitions have an reference number. This number is unique between all instances of definitions with the same type. Some types of definitions may share the same space of possible reference numbers, e.g., otf2.definitions.MetricClass definitions and otf2.definitions.MetricInstance definitions. A definition can reference definitions of the same type and definitions of another type using the reference numbers. Definitions with a reference number inherit from the internal class otf2.definitions._RefDefinition or its subclass otf2.definitions._NamedRefDefinition.

Some definitions are used to represent the structure of the system, e.g., otf2.definitions.SystemTreeNode, otf2.definitions.SystemTreeNodeDomain, and otf2.definitions.SystemTreeNodeProperty.

A otf2.definitions.Region definition represents a code segment, which can be distinguished by name. In case of common code running on a processor, this represents functions. In a GPGPU context a region would represent a kernel.

A otf2.definitions.Location represents a place, where events can occur. This can be a thread running on a common processor or a thread running in a GPGPU environment. A otf2.definitions.Location can also be of the special type otf2.LocationType.METRIC, which is used in conjunction with asynchronous metrics (see Metrics).

In order to represent metrics, there are three types of definitions, i.e., otf2.definitions.MetricClass, otf2.definitions.MetricInstance, and otf2.definitions.MetricMember (see Metrics).

Creating definitions

Normally, definitions are not constructed directly, but rather through the otf2.registry.DefinitionRegistry of a given otf2.writer.Writer. The DefinitionRegistry provides a method for each definition. E.g. otf2.registry.DefinitionRegistry.system_tree_node() generates a otf2.definitions.SystemTreeNode. The registry will not generate duplicates: Instead of creating a definition that would be equal to an existing definition, the existing one is returned.

Fields of definitions

In general, definitions are nice Python objects with their expected member fields. With definitions referring to each other, they form an acyclic graph. All definition fields have a specific type. Possible types can be one following:

  • Simple immutable types such as int, otf2.enums (typesafe).

    Warning

    Never directly change the .value of an enum - game over.

  • Strings are denoted as type String, but they are stored as native str objects within the definitions. Their references are retrieved only when the definition is written.

  • A definition that refers to another definition simply has the other definition object as attribute.

    Note

    Only definition classes marked by the protected base class _RefDefinition or its subclass _NamedRefDefinition may be referred to by other definitions.

  • Aggregates (e.g. List of Definitions) are internally tuples (must be immutable). If you want to change/add/remove an element, you have to set it to a new tuple. You may pass any iterable to construct an aggregate attribute.

  • Other types, especially mutable types, are not supported.

Definitions know the IdRegistry that is responsible for them. Whenever any attribute of a Definition is changed, it informs it’s IdRegistry of the change.

Events

Events are used to represent the state changes, which happen during the execution of the traced application. As otf2.definitions.Location definitions represent all places, where an event can occur, every event is associated with a otf2.definitions.Location definition, i.e., the event has occurred at the associated location. Every event has a time stamp, which denotes the time point, when the event occurred at the associated location. All events, which occurred at the same location, are chronologically ordered by their timestamp in a monotonically increasing fashion. Certain events reference some definitions using their reference number, to represent stateless semantics.

OTF2 specifies over 50 different otf2.events. The majority of the specified events are used to represent the different supported parallelism paradigms, e.g., MPI, and OpenMP. All traces contain at least two types of events. These are otf2.events.Enter and otf2.events.Leave events. Enter and leave events reference a otf2.definitions.Region definition, denoting the begin and the end of the execution of the referenced region on the associated location. Therefore, they always occur as a pair and in this particular sequence. Another type of events is the otf2.events.Metric event. Metric events denote a measurement value of a metric.

Metrics

In OTF2 a metric comprises one or more different measurement points, e.g., an energy metric could comprise the measurement for current and voltage. These measurements are called otf2.definitions.MetricMember. They can have different units, value types, and measurement methods, but they have to be measured at the same time. The representation of these measurements is done with otf2.definitions.MetricMember definitions. Each metric is represented by a otf2.definitions.MetricClass definition. The otf2.definitions.MetricClass definition references all otf2.definitions.MetricMember definitions, which the metric consists of.

The recorded metric values are stored using otf2.events.Metric events associated to certain locations, which depends on the type of metric in question. Metrics are categorized in two categories. The first category defines, how many locations record the metric. This can be represented with a matching number of locations, which contain associated metric events. The second category is given by the fact, that some measurements are recorded externally, i.e., the recorded values of the metric are not available on the recording locations during the execution of the traced application. Therefore, a asynchronous metric requires, that the metric events are stored differently compared to synchronous metrics.

In case of an synchronous metric, the metric events are coupled to otf2.events.Enter and otf2.events.Leave events. The metric events always occur right before the enter and leave, though the metric events, and the enter and leave event share the same timestamp. The recorder and the scope of a synchronous metric is given implicitly by the associated locations of the metric events, which are referencing the metric class definition.

Asynchronous metrics require two additional definitions, i.e., a otf2.definitions.MetricInstance and a otf2.definitions.Location of type otf2.LocationType.METRIC. As asynchronous metrics are externally recorded, they cannot be recorded at the location to which the metric belongs, therefore, they have to explicit specify their scope and their recording location. Also the metric events of the asynchronous metrics has to be associated to a location of type instead otf2.LocationType.METRIC of the recorder.