Received by any component that needs to be notified of trace synchronization.
+=== TmfMarkerEventSourceUpdatedSignal ===
+
+''Purpose''
+
+This signal is used to indicate that a marker event source has been updated.
+
+''Senders''
+
+Sent by a component that has triggered a change in a marker event source.
+
+''Receivers''
+
+Received by any component that needs to refresh the markers due to the change in marker event source.
+
== Debugging ==
TMF has built-in Eclipse tracing support for the debugging of signal interaction between components. To enable it, open the '''Run/Debug Configuration...''' dialog, select a configuration, click the '''Tracing''' tab, select the plug-in '''org.eclipse.tracecompass.tmf.core''', and check the '''signal''' item.
=== ITmfEventMatching interface and derived classes ===
-This interface and its default abstract implementation '''TmfEventMatching''' control the event matching itself. Their only public method is ''matchEvents''. The class needs to manage how to setup the traces, and any initialization or finalization procedures.
-
-The abstract class generates an event request for each trace from which events are matched and waits for the request to complete before calling the one from another trace. The ''handleData'' method from the request calls the ''matchEvent'' method that needs to be implemented in children classes.
+This interface controls the event matching itself. Their only public method is ''matchEvents''. The implementing classes needs to manage how to setup the traces, and any initialization or finalization procedures.
-Class '''TmfNetworkEventMatching''' is a concrete implementation of this interface. It applies to all use cases where a ''in'' event can be matched with a ''out' event (''in'' and ''out'' can be the same event, with different data). It creates a '''TmfEventDependency''' between the source and destination events. The dependency is added to the processing unit.
+The is one concrete implementation of this interface: '''TmfEventMatching'''. It makes a request on the traces and match events where a ''cause'' event can be uniquely matched with a ''effect'' event. It creates a '''TmfEventDependency''' between the source and destination events. The dependency is added to the processing unit.
-To match events requiring other mechanisms (for instance, a series of events can be matched with another series of events), one would need to implement another class either extending '''TmfEventMatching''' or implementing '''ITmfEventMatching'''. It would most probably also require a new '''ITmfMatchEventDefinition''' implementation.
+To match events requiring other mechanisms (for instance, a series of events can be matched with another series of events), one would need to add another class either implementing '''ITmfEventMatching'''. It would most probably also require a new '''ITmfMatchEventDefinition''' implementation.
=== ITmfMatchEventDefinition interface and its derived classes ===
The '''getEventKey''' method will return a key for an event that uniquely identifies this event and will match the key from another event.
-Typically, there would be a match definition abstract class/interface per event matching type.
-
-The interface '''ITmfNetworkMatchDefinition''' adds the ''getDirection'' method to indicate whether this event is a ''in'' or ''out'' event to be matched with one from the opposite direction.
+The '''getDirection''' method indicates whether this event is a ''cause'' or ''effect'' event to be matched with one from the opposite direction.
As examples, two concrete network match definitions have been implemented in the ''org.eclipse.tracecompass.internal.lttng2.kernel.core.event.matching'' package for two compatible methods of matching TCP packets (See the Trace Compass User Guide on ''trace synchronization'' for information on those matching methods). Each one tells which events need to be present in the metadata of a CTF trace for this matching method to be applicable. It also returns the field values from each event that will uniquely match 2 events together.
+Each '''IMatchEventDefinition''' needs to be registered to the '''TmfEventMatching''' class using the following code for example
+
+<pre>
+TmfEventMatching.registerMatchObject(new TcpEventMatching());
+</pre>
+
=== IMatchProcessingUnit interface and derived classes ===
While matching events is an exercise in itself, it's what to do with the match that really makes this functionality interesting. This is the job of the '''IMatchProcessingUnit''' interface.
};
ITmfTrace[] traces = { getTrace() };
- tcpMatching = new TmfNetworkEventMatching(traces, matchProcessing);
+ tcpMatching = new TmfEventMatching(traces, matchProcessing);
tcpMatching.initMatching();
MyEventRequest request = new MyEventRequest(this, i);
}
</pre>
-=== Match network events from UST traces ===
+=== Match events from UST traces ===
Suppose a client-server application is instrumented using LTTng-UST. Traces are collected on the server and some clients on different machines. The traces can be synchronized using network event matching.
One would need to write an event match definition for those 2 events as follows:
<pre>
-public class MyAppUstEventMatching implements ITmfNetworkMatchDefinition {
+public class MyAppUstEventMatching implements ITmfMatchEventDefinition {
+
+ public class MyEventMatchingKey implements IEventMatchingKey {
+
+ private static final HashFunction HF = checkNotNull(Hashing.goodFastHash(32));
+ private final int fTo;
+ private final long fId;
+
+ public MyEventMatchingKey(int to, long id) {
+ fTo = to;
+ fId = id;
+ }
+
+ @Override
+ public int hashCode() {
+ return HF.newHasher()
+ .putInt(fTo)
+ .putLong(fId).hash().asInt();
+ }
+
+ @Override
+ public boolean equals(@Nullable Object o) {
+ if (o instanceof MyEventMatchingKey) {
+ MyEventMatchingKey key = (MyEventMatchingKey) o;
+ return (key.fTo == fTo &&
+ key.fId == fId);
+ }
+ return false;
+ }
+ }
+
@Override
public Direction getDirection(ITmfEvent event) {
String evname = event.getType().getName();
if (evname.equals("myapp:receive")) {
- return Direction.IN;
+ return Direction.EFFECT;
} else if (evname.equals("myapp:send")) {
- return Direction.OUT;
+ return Direction.CAUSE;
}
return null;
}
@Override
public boolean canMatchTrace(ITmfTrace trace) {
- if (!(trace instanceof CtfTmfTrace)) {
+ Set<String> events = ImmutableSet.of("myapp:receive", "myapp:send");
+ if (!(trace instanceof ITmfTraceWithPreDefinedEvents)) {
return false;
}
- CtfTmfTrace ktrace = (CtfTmfTrace) trace;
- String[] events = { "myapp:receive", "myapp:send" };
- return ktrace.hasAtLeastOneOfEvents(events);
- }
+ ITmfTraceWithPreDefinedEvents ktrace = (ITmfTraceWithPreDefinedEvents) trace;
- @Override
- public MatchingType[] getApplicableMatchingTypes() {
- MatchingType[] types = { MatchingType.NETWORK };
- return types;
+ Set<String> traceEvents = TmfEventTypeCollectionHelper.getEventName(ktrace.getContainedEventTypes());
+ traceEvents.retainAll(events);
+ return !traceEvents.isEmpty();
}
}
</pre>
-Somewhere in code that will be executed at the start of the plugin (like in the Activator), the following code will have to be run:
+The following code will have to be run before the trace synchronization takes place, for example in the Activator of the plugin:
<pre>
TmfEventMatching.registerMatchObject(new MyAppUstEventMatching());
</pre>
-Now, only adding the traces in an experiment and clicking the '''Synchronize traces''' menu element would synchronize the traces using the new definition for event matching.
+Now, only adding the traces in an experiment and clicking the '''Synchronize traces''' menu item will synchronize the traces using the new definition for event matching.
== Trace synchronization ==
The following classes implement this interface:
-* '''TmfTimestampTransform''': default transform. It cannot be instantiated, it has a single static object TmfTimestampTransform.IDENTITY, which returns the original timestamp.
+* '''TmfTimestampTransform''': default transform. It cannot be instantiated, it has a single static object ''TmfTimestampTransform.IDENTITY'', which returns the original timestamp.
+* '''TmfConstantTransform''': simply applies an offset to the timestamp, so the formula would be: ''f(t) = t + c'' where ''c'' is the offset to apply.
* '''TmfTimestampTransformLinear''': transforms the timestamp using a linear formula: ''f(t) = at + b'', where ''a'' and ''b'' are computed by the synchronization algorithm.
+These classes are not accessible directly, to create any timestamp transform, one needs to use one of the methods from the '''TimestampTransformFactory''' utility class.
+
One could extend the interface for other timestamp transforms, for instance to have a transform where the formula would change over the course of the trace.
== Todo ==
Here's a list of features not yet implemented that would enhance trace synchronization and event matching:
* Ability to select a synchronization algorithm
-* Implement a better way to select the reference trace instead of arbitrarily taking the first in alphabetical order (for instance, the minimum spanning tree algorithm by Masoume Jabbarifar (article on the subject not published yet))
-* Ability to join traces from the same host so that even if one of the traces is not synchronized with the reference trace, it will take the same timestamp transform as the one on the same machine.
+* Implement the minimum spanning tree algorithm by Masoume Jabbarifar (article on the subject not published yet) to automatically select the best reference trace
* Instead of having the timestamp transforms per trace, have the timestamp transform as part of an experiment context, so that the trace's specific analysis, like the state system, are in the original trace, but are transformed only when needed for an experiment analysis.
* Add more views to display the synchronization information (only textual statistics are available for now)
* A way to differentiate between hypervisor mode and normal mode for the virtual CPU. A virtual CPU usually runs within a process on the host, but sometimes that process may need to run hypervisor-specific code. That is called '''hypervisor mode'''. During that time, no code from the guest itself is run. Typically, the process is running on the host (not preempted), but from the guest's point of view, the virtual CPU should be preempted.
A model implementation for a new hypervisor will need to implement class '''IVirtualMachineModel''', that can be found in package '''org.eclipse.tracecompass.internal.lttng2.kernel.core.analysis.vm.model'''. See the javadoc in the class itself for more information on what each method does.
+
+= JUL Logging =
+
+Logging can be quite useful to debug a class, see its interactions with other components and understand the behavior of the system. TraceCompass uses JUL to log various events in the code, which can then be used to model and analyze the system's workflow. Here are some guidelines to use logging efficiently in Trace Compass. See the User Documentation for instructions on how to enable logging and obtain traces.
+
+=== Use a static logger for each class ===
+
+Each class should define and use their own static logger like this:
+
+ private static final Logger LOGGER = TraceCompassLog.getLogger(StateSystem.class);
+
+It is then easy to filter the components to log by their full class name. The ''TraceCompassLog#getLogger'' method is a wrapper for ''java.util.logging.Logger#getLogger'', but the Trace Compass's logging initialization (overriding the default's ConsoleHandler and INFO level for the org.eclipse.tracecompass namespace when logging is not enabled) is done in the static initializer of this class. Using the wrapper method ensures that this code is called and the user will not see Console message all over the place.
+
+'''Note on abstract classes''': It is debatable whether to use a static logger with the abstract class name or a logger with the concrete class's name.
+
+In the former case, logging for this class uses the classes's own namespace, but it is impossible to discriminate logging statement by concrete classes unless the concrete class name is added as parameter to the statement (when necessary).
+
+The latter case has the advantage that one can log only the concrete class and see all that goes on in the abstract class as well, but the concrete class may be in another namespace and will not benefit from the ''TraceCompassLog'' logging initialization and the user will see console logging happen.
+
+Both methods have their advantages and there is no clear good answer.
+
+=== Use a message supplier ===
+
+A logging statement, to be meaningful, will usually log a string that contains data from the context and will thus do string concatenation. This has a non-negligible overhead. To avoid having to do the costly string concatenation when the statement is not logged, java provides method taking a ''Supplier<String>'' as argument and that method should be used for all logging statements
+
+ LOGGER.info(() -> "[Component:Action] param1=" + myParam1 + ", param2=" + myParam2);
+
+=== Choose the appropriate log level ===
+
+The available log levels for JUL are SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST. The default level when not specified is INFO.
+
+* As a rule of thumb, enabling all INFO level statements should have a near zero impact on the execution, so log parameters that require some computations, or methods that are called very often should not be logged at INFO level.
+* CONFIG level should provide more detailed information than the INFO level, but still not impact the execution too much. It should be possible for a component to use up to CONFIG level statements and make meaningful analyses using the timestamps of the events.
+* FINE, FINER and FINEST are for statements that will not be used with the timestamps. Enabling them may have a visible effect on the performance of Trace Compass. They will typically be used with a purpose in mind, like debugging a component or getting data on caches for examples.
+
+=== Log message format ===
+
+JUL logging will produce trace data and unless one wants to visually parse a trace one event at a time, it will typically be used with an analysis to produce a result. To do so, the log messages should have a format that can then be associated with a trace type.
+
+Third party plugins provide a custom trace parser and LTTng trace type for JUL statements that use the following format
+
+ [EventName:MayContainSemiColon] paramName1=paramValue1, paramName2=paramValue2
projects / deliverable / tracecompass.git / blobdiff