Model-Based Tracing of UML models in Papyrus

1. Introduction

The Papyrus Trace Framework allows annotating UML model elements with a trace annotation. Different kind of model elements can be annotated, such as operations or ports. These annotations are shown by means of a decoration icon. When the code of the application is generated, the trace declaration must lead to an instrumentation of the generated code for a specific trace implementation, in our case primarily LTTng.

2. Annotating Model elements

Several model elements can be annotated with trace information. In the sequel, we list these and outline the different trace options.

1. Class/component itself. When a class is annotated, by default its creation and destruction is traced. In addition, a class has several features (such as operations and attributes). These can be traced without having to place a tracepoint on the feature itself. The user can choose whether he wants to trace in addition all attributes, all operations or all states. This choice is available in the tracing context menu, after the tracepoint has been applied.

2. Port of a component

If a port of a component is traced, an interceptor is placed within the components container. The interceptor traces the operations that are associated with a port. For instance, a data-flow port is associated with push or pull operations that take the concerned data type as parameter.

3. Operation of a class

A tracepoint may be placed on an operation of a class. This means that an interceptor (on class level) will create a trace event before and/or after the operation has been called. In addition, there is the option to add the operation name and the model reference into the trace point, or ' in addition ' all of the operations parameters. If the trace event is produced before the application invocation, out parameters and return values are not part of the trace event.

4. Property of a class

Properties (attributes) of a class can be traced, if the attribute's type is itself a class. In this case, the tracepoint is interpreted as a trace on the instance. It implies activating tracing on the attributes type, but restricting the production of a trace to the role (instance) that the type plays within the class declaring the attribute. This mechanism can be realized within the framework, but is not implemented at the moment.

5. Trace an instance specification

Putting a trace point on an instance specification is quite similar to putting a trace point to an attribute: the classifier referenced by the instance specification will have trace support but actual tracing is restricted to concrete instance. Not implemented (planned for 2013)

6. State (within a statechart)

If a class defines a state-chart, the states can be annotated with a trace marker. A trace event is produced, if the state is entered and/or left (configurable via option). Not implemented (planned for 2013)

7. Transition: A transition can be annotated. A trace event is produced, when the transition is fired.

Code produced for a trace annotation

2.1 Trace declaration

In LTTng, a trace events need to have a declaration. We distinguish events that have a generic declaration and those requiring a specific declaration. For instance, a call event for an operation has a generic declaration, if parameters are not included: all that is needed is the operation name (or identifier). Although we could always use a generic declaration with the operation name as parameter, we declare the name (and URI reference) in the events declaration, i.e. in its meta-data. Thus, an event instance does not include the model URI and is therefore quite lcompact on the expense of a potentially large number of different events.

In general, the event declaration includes a model reference, e.g. ref. to port or operation and event data. In case of an operation call, the event data corresponds to the values of parameter and an identification of the associated instance. The following code fragment shows, how a tracepoint is declared in case of a port interception. Here, the port 'p', typed with interface ICompute is traced, these are the actual of a package template with the two formal parameters interface and port.

We use a canonical name for the event type which is composed of the model name, the name of a package template and the actual variables for the template. In our example, the model is called ClientServerTraceTest, the package methodCall_port_ICompute_p (the underlying package template is called methodCall_port, the actual for the two formals Interface and port are 'ICompute' and 'p', respectively). The second parameter for the event declaration is the elements name, e.g. the operation name ('add' in the example) in case of a traced operation.

TRACEPOINT_EVENT(ClientServerTraceTest_methodCall_port_ICompute_p, add,

TP_ARGS(const char *, instanceName, int, a, int, b),

TP_FIELDS(

ctf_string(instanceName, instanceName)

ctf_integer(int, a, a)

ctf_integer(int, b, b)

)

)

TRACEPOINT_MODEL_EMF_URI(ClientServerTraceTest_methodCall_port_ICompute_p, add, "platform:/resource/org.eclipse.papyrus.qompass.designer.examples/model/ClientServerTraceTest.uml#_4KiE8DLbEd2qeKRLMdIx_A")

For each trace event, the added instrumentation code with invoke the tracepoint, in case of the example above by

tracepoint(ClientServerTraceTest_methodCall_port_ICompute_p, add, instanceName, a, b);

Note that instanceName is an attribute of the interception class, i.e. not a fixed string, a and b are the actual parameters of an operation.

3. Example

This section demonstrates the use of the trace mechanism by means of a very simple application, called client/server trace test. The model is available via the 'new example' menu. Select the example from the 'Qompass examples' folder.

trace4.png

Figure 1: Tracepoint on operation, shown in model explorer, diagram and trace view

Figure 1 shows a small test application. A tracepoint is placed on an operation testOp. The tracepoint is also visible in the tracepoint view (first selected entry) and in the model explorer and the left. The tracepoint view is an additional view that can be shown via the Eclipse standard 'show view' dialog, appearing in the Papyrus category.

trace9.png

Figure 2: Set trace points via context menu

Figure 2 shows a part of the context menu of a model element in the model explorer or a diagram. It contains a sub-menu called 'Tracing' that contains trace related functions. In particular, it is possible to toggle a tracepoint, i.e. add or remove a tracepoint. A tracepoint can be active or inactive. While the instrumentation is always added, i.e. also when the tracepoint is inactive, trace events should only be produced for an active tracepoint. This sould be done via the LTTng runtime control mechanisms.

trace8.png

Figure 4: Preference dialog for tracing

Figure 4 shows the preference dialog for tracing within the Papyrus category. The dialog captures the different options how a tracepoint of a class, a state and on an operation should be interpreted, e.g. whether an operation is be trace with or without parameter values.

In addition to these options, the instrumentation has a modular realization mechanism and the default implementation among available implementations can be chosen. The Qompass model library contains for instance not only an LTTng based trace implementation, but also one based on OTF (open trace format).

trace7-events.png

Figure 5: Trace event view via TMF

Once the tracepoints are set, an application can be compiled and executed. Currently, the runtime trace options must be set manually (e.g. enable all events). The generated trace can be imported by means of the TMF (trace monitoring framework) which is part of the LTTng linux-tools. Figure 5 shows the event view of this framework (note that the view will be replaced by an editor from version 2.0 on) displaying the trace of the client/server trace test model. The screenshot shows the event timestamp, type and content. It depicts that the type corresponds to a qualified name in the model element and that the contents contains parameter values.

trace5-events-filtered.png

Figure 6: Trace event view, filtered (only 'testOp' is shown)

In Figure 6, the event view has been restricted to the operation 'testOp' by means of a context operation of an element in the model explorer or diagram. In this case, only events for the operation testOp are shown.