doc: Update event matching developer documentation
[deliverable/tracecompass.git] / doc / org.eclipse.tracecompass.doc.dev / doc / Developer-Guide.mediawiki
index f02804c24190bf8e912b4585e9581451e87d7263..062b673e5ad3d3ec0eb8f7c30f8df06fad252b87 100644 (file)
@@ -683,6 +683,36 @@ Several features in TMF and the Eclipse LTTng integration are using this framewo
 ** ''org.eclipse.tracecompass.tmf.ui.views.statesystem.TmfStateSystemExplorer.java''
 ** ''org.eclipse.tracecompass.analysis.os.linux.ui.views.cpuusage.CpuUsageComposite.java''
 
+== Timing Analysis Views and Viewers ==
+
+Trace Compass provides base implementations for timing views and viewers for generating Latency Tables, Scatter Charts, Density Graphs and Statistics Tables. They are well integrated with various Trace Compass features such as reading traces and time synchronization with other views. They also handle mouse events for navigating the trace and view, zooming or presenting detailed information at mouse position. The code can be found in the Analysis Timing plug-in ''org.eclipse.tracecompass.analysis.timing.ui''. See below for a list of relevant java packages:
+
+* Latency Table
+** ''org.eclipse.tracecompass.analysis.timing.ui.views.segmentstore.table'': Base classes for Latency Tables
+* Scatter Chart
+** ''org.eclipse.tracecompass.tmf.ui.views.tmfChartView.java'': Common base classes for X-Y-Chart viewers based on SWTChart
+** ''org.eclipse.tracecompass.analysis.timing.ui.views.segmentstore.scatter'': Base classes for Scatter Charts
+* Density Graph
+** ''org.eclipse.tracecompass.analysis.timing.ui.views.segmentstore.density'': Base classes for Density Graphs
+* Statistics Table
+** ''org.eclipse.tracecompass.analysis.timing.ui.views.segmentstore.statistics'': Base classes for Statistics Tables
+
+Several features in Trace Compass are using this framework and can be used as example for further development:
+
+* Latency Table
+** ''org.eclipse.tracecompass.internal.analysis.os.linux.ui.views.latency.SystemCallLatencyView.java''
+** ''org.eclipse.tracecompass.internal.tmf.analysis.xml.ui.views.latency.PatternLatencyTableView.java''
+* Scatter Chart
+** ''org.eclipse.tracecompass.internal.analysis.os.linux.ui.views.latency.SystemCallLatencyScatterView.java''
+** ''org.eclipse.tracecompass.internal.tmf.analysis.xml.ui.views.latency.PatternScatterGraphView.java''
+* Density Graph
+** ''org.eclipse.tracecompass.internal.analysis.os.linux.ui.views.latency.SystemCallLatencyDensityView.java''
+** ''org.eclipse.tracecompass.internal.tmf.analysis.xml.ui.views.latency.PatternDensityView.java''
+
+* Statistics Table
+** ''org.eclipse.tracecompass.internal.analysis.os.linux.ui.views.latency.statistics.SystemCallLatencyStatisticsView.java''
+** ''org.eclipse.tracecompass.internal.tmf.analysis.xml.ui.views.latency.PatternStatisticsView.java''
+
 = Component Interaction =
 
 TMF provides a mechanism for different components to interact with each other using signals. The signals can carry information that is specific to each signal.
@@ -961,6 +991,77 @@ Sent by the Stream List View when the user selects a new packet stream.
 
 Received by views that analyze packet streams.
 
+=== TmfStartAnalysisSignal ===
+
+''Purpose''
+
+This signal is used to indicate that an analysis has started.
+
+''Senders''
+
+Sent by an analysis module when it starts to execute the analyis.
+
+''Receivers''
+
+Received by components that need to be notified of the start of an analysis
+or that need to receive the analysis module.
+
+=== TmfCpuSelectedSignal ===
+
+''Purpose''
+
+This signal is used to indicate that the user has selected a CPU core.
+
+''Senders''
+
+Sent by any component that allows the user to select a CPU.
+
+''Receivers''
+
+Received by viewers that show information specific to a selected CPU.
+
+=== TmfThreadSelectedSignal ===
+
+''Purpose''
+
+This signal is used to indicate that the user has selected a thread.
+
+''Senders''
+
+Sent by any component that allows the user to select a thread.
+
+''Receivers''
+
+Received by viewers that show information specific to a selected thread.
+
+=== TmfTraceSynchronizedSignal ===
+
+''Purpose''
+
+This signal is used to indicate that trace synchronization has been completed.
+
+''Senders''
+
+Sent by the experiment after trace synchronization.
+
+''Receivers''
+
+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.
@@ -1296,6 +1397,23 @@ analysis plugin will normally ship both the state provider and the view, and
 they will have been written by the same person. In other cases, it's possible to
 use getSubAttributes() to explore the organization of the attribute tree first.
 
+===== optQuarkAbsolute()/optQuarkRelative() =====
+
+These two methods are similar to their counterparts getQuarkAbsolute() and
+getQuarkRelative(). The only difference is that if the referenced attribute does
+not exist, the value ITmfStateSystem#INVALID_ATTRIBUTE (-2) is returned instead
+of throwing an exception.
+
+These methods should be used when the presence of the referenced attribute is
+known to be optional, to avoid the performance cost of generating exceptions.
+
+===== getQuarks() =====
+
+This method (with or without a starting node quark) takes an attribute path
+array which may contain wildcard "*" or parent ".." elements, and returns the
+list of matching attribute quarks. If no matching attribute is found, an empty
+list is returned.
+
 ===== waitUntilBuilt() =====
 
 This is a simple method used to block the caller until the construction phase of
@@ -1394,7 +1512,7 @@ state system activities.
 
 ==== AttributeNotFoundException ====
 
-This is thrown by getQuarkRelative() and getQuarkAbsolute() (but not byt the
+This is thrown by getQuarkRelative() and getQuarkAbsolute() (but not by the
 -AndAdd versions!) when passing an attribute path that is not present in the
 state system. This is to ensure that no new attribute is created when using
 these versions of the methods.
@@ -2869,13 +2987,11 @@ Here's a description of the major parts involved in event matching.  These class
 
 === 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.
+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.
 
-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.
+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.
 
-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.
-
-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 ===
 
@@ -2885,12 +3001,16 @@ The '''canMatchTrace''' method will tell if a definition is compatible with a gi
 
 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.
@@ -2938,7 +3058,7 @@ class MyAnalysis extends TmfAbstractAnalysisModule {
         };
 
         ITmfTrace[] traces = { getTrace() };
-        tcpMatching = new TmfNetworkEventMatching(traces, matchProcessing);
+        tcpMatching = new TmfEventMatching(traces, matchProcessing);
         tcpMatching.initMatching();
 
         MyEventRequest request = new MyEventRequest(this, i);
@@ -2978,7 +3098,7 @@ class MyEventRequest extends TmfEventRequest {
 }
 </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.
 
@@ -3013,15 +3133,45 @@ The following metadata describes the events:
 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;
     }
@@ -3043,30 +3193,27 @@ public class MyAppUstEventMatching implements ITmfNetworkMatchDefinition {
 
     @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 ==
 
@@ -3093,9 +3240,12 @@ Timestamp transforms are the formulae used to transform the timestamps from a tr
 
 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 ==
@@ -3103,8 +3253,7 @@ One could extend the interface for other timestamp transforms, for instance to h
 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)
 
@@ -3131,15 +3280,11 @@ public class MyLttngKernelAnalysis extends TmfAbstractAnalysisModule {
     @Override
     public Iterable<TmfAnalysisRequirement> getAnalysisRequirements() {
 
-        // initialize the requirement: domain and events
-        TmfAnalysisRequirement domainReq = new TmfAnalysisRequirement(SessionConfigStrings.CONFIG_ELEMENT_DOMAIN);
-        domainReq.addValue(SessionConfigStrings.CONFIG_DOMAIN_TYPE_KERNEL, ValuePriorityLevel.MANDATORY);
-
-        List<String> requiredEvents = ImmutableList.of("sched_switch", "sched_wakeup");
-        TmfAnalysisRequirement eventReq = new TmfAnalysisRequirement(SessionConfigStrings.CONFIG_ELEMENT_EVENT,
-                requiredEvents, ValuePriorityLevel.MANDATORY);
+        // initialize the requirement: events
+        Set<@NonNull String> requiredEvents = ImmutableSet.of("sched_switch", "sched_wakeup");
+        TmfAbstractAnalysisRequirement eventsReq = new TmfAnalysisEventRequirement(requiredEvents, PriorityLevel.MANDATORY);
 
-        return ImmutableList.of(domainReq, eventReq);
+        return ImmutableList.of(eventsReq);
     }
 
     @Override
@@ -3366,41 +3511,66 @@ where '''MyLttngKernelParameterProvider''' will be registered to analysis ''"my.
 
 === Analysis requirement provider API ===
 
-A requirement defines the needs of an analysis. For example, an analysis could need an event named ''"sched_switch"'' in order to be properly executed. The requirements are represented by the class '''TmfAnalysisRequirement'''. Since '''IAnalysisModule''' extends the '''IAnalysisRequirementProvider''' interface, all analysis modules must provide their requirements. If the analysis module extends '''TmfAbstractAnalysisModule''', it has the choice between overriding the requirements getter ('''IAnalysisRequirementProvider#getAnalysisRequirements()''') or not, since the abstract class returns an empty collection by default (no requirements).
+A requirement defines the needs of an analysis. For example, an analysis could need an event named ''"sched_switch"'' in order to be properly executed. The requirements are represented by extending the class '''TmfAbstractAnalysisRequirement'''. Since '''IAnalysisModule''' extends the '''IAnalysisRequirementProvider''' interface, all analysis modules must provide their requirements. If the analysis module extends '''TmfAbstractAnalysisModule''', it has the choice between overriding the requirements getter ('''IAnalysisRequirementProvider#getAnalysisRequirements()''') or not, since the abstract class returns an empty collection by default (no requirements).
 
 === Requirement values ===
 
-When instantiating a requirement, the developer needs to specify a type to which all the values added to the requirement will be linked. In the earlier example, there would be an ''"event"''  or ''"eventName"'' type. The type is represented by a string, like all values added to the requirement object. With an 'event' type requirement, a trace generator like the LTTng Control could automatically enable the required events. This is possible by calling the '''TmfAnalysisRequirementHelper''' class. Another point we have to take into consideration is the priority level of each value added to the requirement object. The enum '''TmfAnalysisRequirement#ValuePriorityLevel''' gives the choice between '''ValuePriorityLevel#MANDATORY''' and '''ValuePriorityLevel#OPTIONAL'''. That way, we can tell if an analysis can run without a value or not. To add values, one must call '''TmfAnalysisRequirement#addValue()'''.
+Each concrete analysis requirement class will define how a requirement is verified on a given trace. 
+When creating a requirement, the developer will specify a set of values for that class.
+With an 'event' type requirement, a trace generator like the LTTng Control could automatically
+enable the required events. 
+Another point we have to take into consideration is the priority level when creating a requirement object.
+The enum '''TmfAbstractAnalysisRequirement#PriorityLevel''' gives the choice
+between '''PriorityLevel#OPTIONAL''', '''PriorityLevel#ALL_OR_NOTHING''',
+'''PriorityLevel#AT_LEAST_ONE''' or '''PriorityLevel#MANDATORY'''. That way, we
+can tell if an analysis can run without a value or not.
+
+
+To create a requirement one has the choice to extend the abstract class
+'''TmfAbstractAnalysisRequirement''' or use the existing implementations:
+'''TmfAnalysisEventRequirement''' (will verify the presence of events identified by name),
+'''TmfAnalysisEventFieldRequirement''' (will verify the presence of fields for some or all events) or
+'''TmfCompositeAnalysisRequirement''' (join requirements together with one of the priority levels).
 
 Moreover, information can be added to requirements. That way, the developer can explicitly give help details at the requirement level instead of at the analysis level (which would just be a general help text). To add information to a requirement, the method '''TmfAnalysisRequirement#addInformation()''' must be called. Adding information is not mandatory.
 
 === Example of providing requirements ===
 
-In this example, we will implement a method that initializes a requirement object and return it in the '''IAnalysisRequirementProvider#getAnalysisRequirements()''' getter. The example method will return a set with two requirements. The first one will indicate the events needed by a specific analysis and the last one will tell on what domain type the analysis applies. In the event type requirement, we will indicate that the analysis needs a mandatory event and an optional one.
+In this example, we will implement a method that initializes a requirement object
+and return it in the '''IAnalysisRequirementProvider#getAnalysisRequirements()'''
+getter. The example method will return a set with three requirements.
+The first one will indicate a mandatory event needed by a specific analysis,
+the second one will tell an optional event name and the third will indicate
+mandatory event fields for the given event type.
+
+Note that in LTTng event contexts are considered as event fields. Using the
+'''TmfAnalysisEventFieldRequirement''' it's possible to define requirements
+on event contexts (see 3rd requirement in example below).
 
 <pre>
-@Override
-public Iterable<TmfAnalysisRequirement> getAnalysisRequirements() {
-    Set<TmfAnalysisRequirement> requirements = new HashSet<>();
+    @Override
+    public @NonNull Iterable<@NonNull TmfAbstractAnalysisRequirement> getAnalysisRequirements() {
 
-    /* Create requirements of type 'event' and 'domain' */
-    TmfAnalysisRequirement eventRequirement = new TmfAnalysisRequirement("event");
-    TmfAnalysisRequirement domainRequirement = new TmfAnalysisRequirement("domain");
+        /* Requirement on event name */
+        Set<@NonNull String> requiredEvents = ImmutableSet.of("sched_wakeup");
+        TmfAbstractAnalysisRequirement eventsReq1 = new TmfAnalysisEventRequirement(requiredEvents, PriorityLevel.MANDATORY);
 
-    /* Add the values */
-    domainRequirement.addValue("kernel", TmfAnalysisRequirement.ValuePriorityLevel.MANDATORY);
-    eventRequirement.addValue("sched_switch", TmfAnalysisRequirement.ValuePriorityLevel.MANDATORY);
-    eventRequirement.addValue("sched_wakeup", TmfAnalysisRequirement.ValuePriorityLevel.OPTIONAL);
+        requiredEvents = ImmutableSet.of("sched_switch");
+        TmfAbstractAnalysisRequirement eventsReq2 = new TmfAnalysisEventRequirement(requiredEvents, PriorityLevel.OPTIONAL);
 
-    /* An information about the events */
-    eventRequirement.addInformation("The event sched_wakeup is optional because it's not properly handled by this analysis yet.");
+        /* An information about the events */
+        eventsReq2.addInformation("The event sched_wakeup is optional because it's not properly handled by this analysis yet.");
 
-    /* Add them to the set */
-    requirements.add(domainRequirement);
-    requirements.add(eventRequirement);
+        /* Requirement on event fields */
+        Set<@NonNull String> requiredEventFields = ImmutableSet.of("context._procname", "context._ip");
+        TmfAbstractAnalysisRequirement eventFieldRequirement = new TmfAnalysisEventFieldRequirement(
+                 "event name",
+                 requiredEventFields,
+                 PriorityLevel.MANDATORY);
 
-    return requirements;
-}
+         Set<TmfAbstractAnalysisRequirement> requirements = ImmutableSet.of(eventsReq1, eventsReq2, eventFieldRequirement);
+         return requirements;
+    }
 </pre>
 
 
@@ -4385,3 +4555,45 @@ This analysis tracks the state of the virtual CPUs in conjunction with the physi
 * 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
This page took 0.031278 seconds and 5 git commands to generate.