BareCTF Tracing of UML models in Papyrus - Generated artifacts

Prepare your model and execute the transformation chain

In order to prepare your model for tracing, you need to add the additional BareCTF transformations to your transformation chain. These transformations are defined in the additional transformation chain, called "BareCTF". It is available as a registered model library, as shown in the following screenshot. Use the context menu on the model explorer and then "Import -> Import Registered Package" to load it.

Import trace library

Refer to the implementation independent specification how to reference this library to the stereotype ExecuteTransformationChain (or DeploymentPlan which inherits from the former). Once, you execute the transformantion chain "normally" via the menu entry "Designer -> Transform and Generate code", the tracing chain will add the trace instrumentation to the generated code."

Underlying CTF technology

The trace files use the common trace format (CTF). In order to be available on multiple platforms, the implementation is not based on the Linux implementation LTTng, but on barectf. Besides the code instrumentation, the code generator creates a configuration file for barectf. This file is called "config.yaml". It is placed into the folder src-gen/ctf. Each tracepoint in the model is associated with an event declaration. This event declaration has a name consisting of a suitable prefix and the name of the UML element to trace. All events have a parameter associated with the name instance. This instance name is assigned automatically during code generation, if UML instance specifications are contained in the deployment plan. If no instance is available, the instanceName defaults to the class name. For same elements, additional data is (optionally) included in the trace (see above).

Mapping of model types to CTF types

Flattening of nested types
Lists

ListHint

TraceHint

enumerations

UML enumerations are mapped to 8-bit integers, i.e. allowing for a maximum number of 256 different values (which should be sufficient for most cases). In the barectf configuration file, a so-called type-alias is created for the enumerations. This declaration is created in a separate configuration file having the name of the UML type with the extension .yaml. The integer definition is accompanied by a set of mapping definitions corresponding to the different enumeration literals. The following code example shows the generated configuration for the enumeration "ThreadFunctions" from the UML model used to test the code generator.

$field-type-aliases:
  ThreadFunctions:
    class: unsigned-enum
    size: 8
    alignment: 8
    mappings:
      TF_CHANGE_EVENT : [0]
      TF_TIME_EVENT : [1]
      TF_DO_ACTIVITY : [2]
      TF_ENTER_REGION : [3]
      TF_EXIT_REGION : [4]
      TF_TRANSITION : [5]
      TF_STATE_MACHINE_TYPE : [6]

STL string

Barectf is based on C, but it can be used with the string class from the standard template library. The std::string has a method c_str() returning a C style char pointer. The call of this method is automatically done by the generated instrumentation. Other STL classes offer this possibility as well, for instance std::vector has a data() method that returns a c-type array. But the use of lists is constrained to some basic types and therefore not automatically supported by the tool.

Trace declaration

In barectf, trace events are defined in a config.yaml file. These events have a canonical name derived from the UML element that needs to be traced. The following list shows how the event names are calculated depending on the model element (the calculation is done in the class EventNames.xtend). We use square brackets to reference attributes of the UML meta-model.

Operation

Two events, one for the start, one for the end: The start has the name "op_starts_[class.name]_[operation.name]", the instrumentation at the end has the same name with the prefix "op_ends" instead of "op_starts". In case of a constructor or destructor, the names are prefixed with "creation" and "destruction", respectively (and do not include a method name)

Port

Two events, one for the start, one for the end: The start has the name "port_op_starts_[class.name]_[port.name]_[operation.name]", the instrumentation at the end has the same name with the prefix "port_op_ends" instead of "port_op_starts".

State

Two events (optionally), one for entering the state, one for leaving it: The start has the name " "enter_state_[state.class.name]_[state.name]". The instrumentation for leaving a state has same name with the prefix "exit_state" instead of "enter_state".

Transition

The transition event has the name "transition_[class.name]_[transition.name]". The transition name itself has a specific calculation that takes into account that some models have empty or undefined transition names. In this case the transition name is the concatenation of source and target name.

All trace events are post-fixed by a 5 digit identifier associated with a counter. This ensures that the event name is unique, as the naming in the model does not generally guarantee this.

Each trace event has one parameter of type string: the instanceName which corresponds to the name of the instance specification in the deployment plan (if given - if it is not available, the value defaults to the class name). The additional parameters depend on the traced element, for instance in case of an operation, the tool can automatically include operation parameters (see section about specification).

The following code excerpt shows the beginning of the generated config.yaml file. This file is located in the folder src-gen/ctf.

# Needed YAML tag for the configuration object
--- !

# Configuration's trace
trace:
  # Type of the trace
  type:
    # Add standard field type aliases
    $include:
      - stdint.yaml
      - stdreal.yaml
      - stdmisc.yaml
      - BooleanType.yaml        // enumeration type from user model
      - ThreadFunctions.yaml    // enumeration type from user model

If the model contains enumeration types that are referenced in an trace event, additional configuration files are generated that defined these enumeration types, as shown in the beginning of this page for the example of ThreadFunctions. The command line tool barectf (which is invoked) by the transformation chain produces the following files.

barectf.h, barectf.c,
barectf-bitfield.h
metadata

In addition, a so-called platform file is required. The code transformations automatically copies a platform file that works with Linux or cygwin.

The code generator injects a specific attribute, called model.emf.uri into the generated metadata file. The attribute stores the model reference, e.g. ref. to port or operation and event data. The objective is that some trace viewers evaluate this attribute and enable a navigation to the original model element. The following except of the metadata file shows a trace event entry in the metadata file and the added EMF uri.

event {
	stream_id = 0;
	id = 2;
	name = "op_starts_D1_MyOperation_2_MyOperation_2";
	model.emf.uri = "platform:/resource/DemoTrace/DemoTrace.uml#_NfDIKG9fEeqJeI8mbLLRcg";
	fields := struct {
	...

Troubleshooting

The execution of the barectf on the generated config.yaml file may fail, for instance if the barectf command is not in the PATH or if it does not process the generated configuration file. In this case, the error should be logged. Open the "error log" view" and check for events. However, it is also useful to manually invoke "barectf" from a shell in the <project-name>/src-gen/ctf folder.

Known issues

The trace instrumentation is implemented as a model-to-model (M2M) transformation that is executed in a certain order within a transformation chain. It is executed before the state-machine transformation, as it eventually adds transition effects or entry/exit actions. If active in the option, the "creation_ends" instrumentation is added at the end the constructor. However, the state-machine transformation will add the "start_behavior" action at the end of the constructor afterwards, i.e. the "creation_ends" instrumentation is no longer at the end.