Skip to main content
aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorMatthew Khouzam2014-05-29 19:00:18 +0000
committerBernd Hufmann2014-09-16 23:34:10 +0000
commitcbcf3e84ecdd714d63b914d6e717dea6cfb23e04 (patch)
treecfadcde79b47f875b2a83a05d65a39763ecc3935
parente6dd5a040719ef9eff19e67f6b38ec642619a1ba (diff)
downloadorg.eclipse.linuxtools-cbcf3e84ecdd714d63b914d6e717dea6cfb23e04.tar.gz
org.eclipse.linuxtools-cbcf3e84ecdd714d63b914d6e717dea6cfb23e04.tar.xz
org.eclipse.linuxtools-cbcf3e84ecdd714d63b914d6e717dea6cfb23e04.zip
Squashed commit of missing user guide updates from stable-3.0
tmf: update user guide to have UST section Signed-off-by: Matthew Khouzam <matthew.khouzam@ericsson.com> Reviewed-on: https://git.eclipse.org/r/27504 Reviewed-by: Bernd Hufmann <bernd.hufmann@ericsson.com> Tested-by: Bernd Hufmann <bernd.hufmann@ericsson.com> Update introduction and installation of user guide Signed-off-by: Matthew Khouzam <matthew.khouzam@ericsson.com> Reviewed-on: https://git.eclipse.org/r/27402 Reviewed-by: Bernd Hufmann <bernd.hufmann@ericsson.com> Tested-by: Hudson CI Signed-off-by: Bernd Hufmann <Bernd.Hufmann@ericsson.com> tmf-guide: Introduction chapter about TMF built-in views and viewers Signed-off-by: Bernd Hufmann <Bernd.Hufmann@ericsson.com> Reviewed-on: https://git.eclipse.org/r/28065 Reviewed-by: Alexandre Montplaisir <alexmonthy@voxpopuli.im> Reviewed-by: Marc-Andre Laperle <marc-andre.laperle@ericsson.com> Tested-by: Marc-Andre Laperle <marc-andre.laperle@ericsson.com> Reviewed-by: Matthew Khouzam <matthew.khouzam@ericsson.com> Tested-by: Hudson CI tmf: Developer guide update about trace types Signed-off-by: Matthew Khouzam <matthew.khouzam@ericsson.com> Signed-off-by: Alexandre Montplaisir <alexmonthy@voxpopuli.im> Reviewed-on: https://git.eclipse.org/r/27952 Tested-by: Hudson CI Reviewed-on: https://git.eclipse.org/r/33466 Reviewed-by: Marc-Andre Laperle <marc-andre.laperle@ericsson.com> Reviewed-by: Jeff Johnston <jjohnstn@redhat.com> Tested-by: Jeff Johnston <jjohnstn@redhat.com> Change-Id: I217ae1c2c0729f4064745fee5dbe487bfc5d82ff Signed-off-by: Bernd Hufmann <Bernd.Hufmann@ericsson.com> Reviewed-on: https://git.eclipse.org/r/33467 Tested-by: Hudson CI Reviewed-by: Alexandre Montplaisir <alexmonthy@voxpopuli.im>
-rw-r--r--lttng/org.eclipse.linuxtools.lttng.help/doc/User-Guide.mediawiki156
-rw-r--r--lttng/org.eclipse.linuxtools.lttng.help/doc/images/memoryUsage/memory-usage-multithread.pngbin0 -> 39693 bytes
-rw-r--r--lttng/org.eclipse.linuxtools.lttng.help/doc/images/memoryUsage/memory-usage-no-thread-info.pngbin0 -> 24578 bytes
-rw-r--r--lttng/org.eclipse.linuxtools.tmf.help/doc/Developer-Guide.mediawiki357
-rw-r--r--lttng/org.eclipse.linuxtools.tmf.help/doc/images/NTTAddType.pngbin57648 -> 56846 bytes
-rw-r--r--lttng/org.eclipse.linuxtools.tmf.help/doc/images/NTTExtensionPoint.pngbin49468 -> 44492 bytes
-rw-r--r--lttng/org.eclipse.linuxtools.tmf.help/doc/images/NTTPluginxmlComplete.pngbin65785 -> 73797 bytes
-rw-r--r--lttng/org.eclipse.linuxtools.tmf.help/doc/images/NTTTraceType.pngbin49951 -> 43259 bytes
8 files changed, 201 insertions, 312 deletions
diff --git a/lttng/org.eclipse.linuxtools.lttng.help/doc/User-Guide.mediawiki b/lttng/org.eclipse.linuxtools.lttng.help/doc/User-Guide.mediawiki
index 738d7e5e0e..5083514ebb 100644
--- a/lttng/org.eclipse.linuxtools.lttng.help/doc/User-Guide.mediawiki
+++ b/lttng/org.eclipse.linuxtools.lttng.help/doc/User-Guide.mediawiki
@@ -4,7 +4,7 @@
LTTng (Linux Trace Toolkit, next generation) is a highly efficient tracing tool for Linux that can be used to track down kernel and application performance issues as well as troubleshoot problems involving multiple concurrent processes and threads. It consists of a set of kernel modules, daemons - to collect the raw tracing data - and a set of tools to control, visualize and analyze the generated data. It also provides support for user space application instrumentation.
For more information about LTTng, refer to the project [http://lttng.org site]
-'''Note''': This User Guide covers the integration of the latest LTTng (v2.0) in Eclipse. The legacy version (v0.x) of both the tracer and the LTTng integration are no longer being maintained.
+'''Note''': This User Guide covers the integration of the latest LTTng (up to v2.4) in Eclipse.
== About Tracing ==
@@ -14,7 +14,7 @@ Tracing is similar to logging: it consists in recording events that happen in a
Traces may include events from the operating system kernel (IRQ handler entry/exit, system call entry/exit, scheduling activity, network activity, etc). They can also consists of application events (a.k.a UST - User Space Tracing) or a mix of the two.
-For the maximum level of detail, tracing events may be viewed like a log file. However, trace analyzers and viewers are available to derive useful information from the raw data. These programs must be specially designed to handle quickly the enormous amount of data a trace may contain.
+For the maximum level of detail, tracing events may be viewed like a log file. However, trace analyzers and viewers are available to derive useful information from the raw data coupled with knowledge of the traced program. These programs must be specially designed to handle quickly the enormous amount of data a trace may contain.
== LTTng integration ==
@@ -30,10 +30,16 @@ The LTTng Eclipse plug-in provides the following views:
These views can be extended or tailored for specific trace types (e.g. kernel, HW, user app).
-At present, the LTTng Eclipse plug-in for Eclipse supports the following kernel-oriented analysis:
+At present, the LTTng Eclipse plug-in for Eclipse supports the following kernel-oriented views:
* ''Control Flow'' - to visualize processes state transitions
* ''Resources'' - to visualize system resources state transitions
+* ''CPU usage'' - to visualize the usage of the processor with respect to the time in traces
+
+It also supports the following User Space traces views:
+
+* ''Memory Usage'' - to visualize the memory usage per thread with respect to time in the traces
+* ''Call Stack'' - to visualize the call stack's evolution over time
Although the control and fetching parts are targeted at the LTTng tracer, the underlying framework can also be used to process any trace that complies with the ''Common Trace Format'' ([http://www.efficios.com/ctf CTF]). CTF specifies a very efficient and compact binary trace format that is meant to be application-, architecture-, and language-agnostic.
@@ -47,11 +53,14 @@ The LTTng Eclipse plug-in has a number of features to allow efficient handling o
* Views synchronization of currently selected time or time range, and window time range
* Efficient searching and filtering of events
* Support for trace bookmarks
+* Support for importing and exporting trace packages
There is also support for the integration of non-LTTng trace types:
* Built-in CTF parser
* Dynamic creation of customized parsers (for XML and text traces)
+* Dynamic creation of customized state systems (from XML files)
+* Dynamic creation of customized views (from XML files)
= Installation =
@@ -81,9 +90,16 @@ The LTTng plug-ins are structured as a stack of features/plug-ins as following:
** ''Feature'': org.eclipse.linuxtools.ctf
** ''Plug-ins'': org.eclipse.linuxtools.ctf.core, org.eclipse.linuxtools.ctf.parser
+* '''State System Core''' - State system for TMF
+** ''Plug-ins'': org.eclipse.linuxtools.statesystem.core
+
* '''TMF''' - ''Tracing and Monitoring Framework'' a framework for generic trace processing
** ''Feature'': org.eclipse.linuxtools.tmf
-** ''Plug-ins'': org.eclipse.linuxtools.tmf.core, org.eclipse.linuxtools.tmf.ui
+** ''Plug-ins'': org.eclipse.linuxtools.tmf.core, org.eclipse.linuxtools.tmf.ui. org.eclipse.linuxtools.tmf.analysis.xml.core, org.eclipse.linuxtools.tmf.analysis.xml.ui
+
+* '''CTF support for TMF''' - CTF support for the TMF Feature
+** ''Feature'': org.eclipse.linuxtools.tmf.ctf
+** ''Plug-ins'': org.eclipse.linuxtools.tmf.ctf.core
* '''LTTng''' - The wrapper for the LTTng tracer control. Can be used for kernel or application tracing.
** ''Feature'': org.eclipse.linuxtools.lttng2.control
@@ -93,9 +109,13 @@ The LTTng plug-ins are structured as a stack of features/plug-ins as following:
** ''Feature'': org.eclipse.linuxtools.lttng2.kernel
** ''Plug-ins'': org.eclipse.linuxtools.lttng2.kernel.core, org.eclipse.linuxtools.lttng2.kernel.ui
+* '''LTTng UST''' - Analysis components specific to Linux userspace traces
+** ''Feature'': org.eclipse.linuxtools.lttng2.ust
+** ''Plug-ins'': org.eclipse.linuxtools.lttng2.ust.core, org.eclipse.linuxtools.lttng2.ust.ui
+
== LTTng Eclipse Dependencies ==
-The Eclipse LTTng controls the LTTng tracer through an ''ssh'' connection even if the tracer is running locally (the 'degenerate' case).
+The Eclipse LTTng controls the LTTng tracer through an ''ssh'' connection, if the tracer is running locally it can use or bypass the ''ssh'' connection.
Therefore, the target system (where the tracer runs) needs to run an ''ssh'' server as well as ''sftp'' server (for file transfer) to which you have permission to connect.
@@ -103,6 +123,8 @@ On the host side (where Eclipse is running), you also need to have Eclipse RSE (
== Installation Verification ==
+If you do not have any, sample LTTng traces can be found here [http://lttng.org/download]. At the bottom of the page there is a link to some sample LTTng 2.0 kernel traces. The trace needs to be uncompressed to be read.
+
Here are the quick steps to verify that your installation is functional:
* Start Eclipse
@@ -112,8 +134,8 @@ Here are the quick steps to verify that your installation is functional:
** Enter the name of your project (e.g. "MyLTTngProject")
** The project will be created. It will contain 2 empty folders: "Traces" and "Experiments"
* Open a sample trace
-** Right-click on the newly created project "Traces" folder and select "Open Trace Directory..."
-** Navigate to the sample LTTng trace that you want to visualize
+** Right-click on the newly created project "Traces" folder and select "Open Trace..."
+** Navigate to the sample LTTng trace that you want to visualize and select any file in the trace folder
** The newly imported trace should appear under the Traces folder
* Visualize the trace
** Expand the Traces folder
@@ -122,9 +144,7 @@ Here are the quick steps to verify that your installation is functional:
If an error message is displayed, you might want to double-check that the trace type is correctly set (right-click on the trace and "Select Trace Type...").
-Refer to [[#Tracing Perspective | Tracing Perspective]] for detailed description of the views and their usage.
-
-To download sample LTTng traces, go to [http://lttng.org/download]. At the bottom of the page there is a link to some sample LTTng 2.0 kernel traces.
+Refer to [[#Tracing Perspective]] for detailed description of the views and their usage.
= LTTng =
@@ -662,50 +682,6 @@ The view shows a tree of currently selected traces and their registered state sy
To modify the time of attributes shown in the view, select a different current time in other views that support time synchronization (e.g. event table, histogram view). When a time range is selected, this view uses the begin time.
-== Call Stack View ==
-
-The Call Stack view allows the user to visualize the call stack per thread over time, if the application and trace provide this information.
-
-The view shows the call stack information for the currently selected trace.
-
-The table on the left-hand side of the view shows the threads and call stack. The function name, depth, entry and exit time and duration are shown for the call stack at the selected time.
-
-Double-clicking on a function entry in the table will zoom the time graph to the selected function's range of execution.
-
-The time graph on the right-hand side of the view shows the call stack state graphically over time. The function name is visible on each call stack event if size permits. The color of each call stack event is randomly assigned based on the function name, allowing for easy identification of repeated calls to the same function.
-
-Clicking on the time graph will set the current time and consequently update the table with the current call stack information.
-
-Shift-clicking on the time graph will select a time range. When the selection is a time range, the begin time is used to update the stack information.
-
-Double-clicking on a call stack event will zoom the time graph to the selected function's range of execution.
-
-Clicking the '''Select Next Event''' or '''Select Previous Event''' or using the left and right arrows will navigate to the next or previous call stack event, and select the function currently at the top of the call stack.
-
-Clicking the '''Import Mapping File''' ([[Image:images/import.gif]]) icon will open a file selection dialog, allowing you to import a text file containing mappings from function addresses to function names. If the callstack provider for the current trace type only provides function addresses, a mapping file will be required to get the function names in the view. See the following sections for an example with LTTng-UST traces.
-
-=== Using the Callstack View with LTTng-UST traces ===
-
-There is support in the LTTng-UST integration plugin to display the callstack of applications traced with the ''liblttng-ust-cyg-profile.so'' library (see the ''liblttng-ust-cyg-profile'' man page for additional information). To do so, you need to:
-
-* Recompile your application with "''-g -finstrument-functions''".
-* Add the ''vtid'' and ''procname'' contexts to your trace session. See the [[#Adding Contexts to Channels and Events of a Domain]] section. Or if using the command-line:
-** <pre>lttng add-context -u -t vtid -t procname</pre>
-* Preload the ''liblttng-ust-cyg-profile'' library when running your program:
-** <pre>LD_PRELOAD=/usr/lib/liblttng-ust-cyg-profile.so ./myprogram</pre>
-
-Once you load the resulting trace, making sure it's set to the ''Common Trace Format - LTTng UST Trace'' type, the Callstack View should be populated with the relevant information. However, since GCC's cyg-profile instrumentation only provides function addresses, and not names, an additional step is required to get the function names showing in the view. The following section explains how to do so.
-
-=== Importing a function name mapping file for LTTng-UST traces ===
-
-If you followed the steps in the previous section, you should have a Callstack View populated with function entries and exits. However, the view will display the function addresses instead of names in the intervals, which are not very useful by themselves. To get the actual function names, you need to:
-
-* Generate a mapping file from the binary, using:
-** <pre>nm myprogram > mapping.txt</pre>
-* Click the '''Import Mapping File''' ([[Image:images/import.gif]]) button in the Callstack View, and select the ''mapping.txt'' file that was just created.
-
-The view should now update to display the function names instead. Make sure the binary used for taking the trace is the one used for this step too (otherwise, there is a good chance of the addresses not being the same).
-
== Custom Parsers ==
Custom parser wizards allow the user to define their own parsers for text or XML traces. The user defines how the input should be parsed into internal trace events and identifies the event fields that should be created and displayed. Traces created using a custom parser can be correlated with other built-in traces or traces added by plug-in extension.
@@ -1714,9 +1690,79 @@ The LTTng Kernel Events editor '''is''' the plain TMF [[#Events_Editor | Events
* '''Event Type''': the event type (or kernel marker)
* '''Content''': the raw event content
-
[[Image:images/LTTng2EventsEditor.png]]
+= LTTng-UST Analyses =
+
+The Userspace traces are taken on an application level. With kernel traces, you know what events you will have as the domain is known and cloistered. Userspace traces can contain pretty much anything. Some analyses are offered if certain events are enabled.
+
+== Call Stack View ==
+
+The Call Stack view allows the user to visualize the call stack per thread over time, if the application and trace provide this information.
+
+To open this view go in '''Window''' -> '''Show View''' -> '''Other...''' and select '''Tracing/Call Stack''' in the list. The view shows the call stack information for the currently selected trace. Conversely, you can select a trace and expand it in the '''Project Explorer''' then expand '''LTTng-UST CallStack Analysis''' (the trace must be loaded) and open '''Call Stack'''.
+
+The table on the left-hand side of the view shows the threads and call stack. The function name, depth, entry and exit time and duration are shown for the call stack at the selected time.
+
+Double-clicking on a function entry in the table will zoom the time graph to the selected function's range of execution.
+
+The time graph on the right-hand side of the view shows the call stack state graphically over time. The function name is visible on each call stack event if size permits. The color of each call stack event is randomly assigned based on the function name, allowing for easy identification of repeated calls to the same function.
+
+Clicking on the time graph will set the current time and consequently update the table with the current call stack information.
+
+Shift-clicking on the time graph will select a time range. When the selection is a time range, the begin time is used to update the stack information.
+
+Double-clicking on a call stack event will zoom the time graph to the selected function's range of execution.
+
+Clicking the '''Select Next Event''' or '''Select Previous Event''' or using the left and right arrows will navigate to the next or previous call stack event, and select the function currently at the top of the call stack.
+
+Clicking the '''Import Mapping File''' ([[Image:images/import.gif]]) icon will open a file selection dialog, allowing you to import a text file containing mappings from function addresses to function names. If the callstack provider for the current trace type only provides function addresses, a mapping file will be required to get the function names in the view. See the following sections for an example with LTTng-UST traces.
+
+=== Using the Callstack View with LTTng-UST traces ===
+
+There is support in the LTTng-UST integration plugin to display the callstack of applications traced with the ''liblttng-ust-cyg-profile.so'' library (see the ''liblttng-ust-cyg-profile'' man page for additional information). To do so, you need to:
+
+* Recompile your application with "''-g -finstrument-functions''".
+* Add the ''vtid'' and ''procname'' contexts to your trace session. See the [[#Adding Contexts to Channels and Events of a Domain]] section. Or if using the command-line:
+** <pre>lttng add-context -u -t vtid -t procname</pre>
+* Preload the ''liblttng-ust-cyg-profile'' library when running your program:
+** <pre>LD_PRELOAD=/usr/lib/liblttng-ust-cyg-profile.so ./myprogram</pre>
+
+Once you load the resulting trace, making sure it's set to the ''Common Trace Format - LTTng UST Trace'' type, the Callstack View should be populated with the relevant information. However, since GCC's cyg-profile instrumentation only provides function addresses, and not names, an additional step is required to get the function names showing in the view. The following section explains how to do so.
+
+=== Importing a function name mapping file for LTTng-UST traces ===
+
+If you followed the steps in the previous section, you should have a Callstack View populated with function entries and exits. However, the view will display the function addresses instead of names in the intervals, which are not very useful by themselves. To get the actual function names, you need to:
+
+* Generate a mapping file from the binary, using:
+** <pre>nm myprogram > mapping.txt</pre>
+* Click the '''Import Mapping File''' ([[Image:images/import.gif]]) button in the Callstack View, and select the ''mapping.txt'' file that was just created.
+
+The view should now update to display the function names instead. Make sure the binary used for taking the trace is the one used for this step too (otherwise, there is a good chance of the addresses not being the same).
+
+== Memory Usage ==
+
+The Memory Usage view allows the user to visualize the active memory usage per thread over time, if the application and trace provide this information.
+
+The view shows the memory consumption for the currently selected trace.
+
+The time chart plots heap memory usage graphically over time. There is one line per process, unassigned memory usage is mapped to "Other".
+
+In this implementation, the user needs to trace while hooking the ''liblttng-ust-libc-wrapper'' by running ''LD_PRELOAD=liblttng-ust-libc-wrapper.so'' '''<exename>'''. This will add tracepoints to memory allocation and freeing to the heap, NOT shared memory or stack usage. If the contexts '''vtid''' and '''procname''' are enabled, then the view will associate the heap usage to processes. As detailed earlier, to enable the contexts, see the [[#Adding Contexts to Channels and Events of a Domain]] section. Or if using the command-line:
+* <pre>lttng add-context -u -t vtid -t procname</pre>
+
+If thread information is available the view will look like this:
+
+[[Image:images/memoryUsage/memory-usage-multithread.png]]
+
+If thread information is not available it will look like this:
+
+[[Image:images/memoryUsage/memory-usage-no-thread-info.png]]
+
+The view allows selection of a specific time by left-clicking on a point in the chart. Left mouse dragging will select a time range. Right mouse dragging on the area will zoom in on that window. Middle mouse dragging will move the display window. Mouse wheel operations will zoom in and out also.
+
+Please note this view will not show shared memory or stack memory usage.
+
= Trace synchronization =
It is possible to synchronize traces from different machines so that they have the same time reference. Events from the reference trace will have the same timestamps as usual, but the events from traces synchronized with the first one will have their timestamps transformed according to the formula obtained after synchronization.
diff --git a/lttng/org.eclipse.linuxtools.lttng.help/doc/images/memoryUsage/memory-usage-multithread.png b/lttng/org.eclipse.linuxtools.lttng.help/doc/images/memoryUsage/memory-usage-multithread.png
new file mode 100644
index 0000000000..2634abc24c
--- /dev/null
+++ b/lttng/org.eclipse.linuxtools.lttng.help/doc/images/memoryUsage/memory-usage-multithread.png
Binary files differ
diff --git a/lttng/org.eclipse.linuxtools.lttng.help/doc/images/memoryUsage/memory-usage-no-thread-info.png b/lttng/org.eclipse.linuxtools.lttng.help/doc/images/memoryUsage/memory-usage-no-thread-info.png
new file mode 100644
index 0000000000..fb74815ce6
--- /dev/null
+++ b/lttng/org.eclipse.linuxtools.lttng.help/doc/images/memoryUsage/memory-usage-no-thread-info.png
Binary files differ
diff --git a/lttng/org.eclipse.linuxtools.tmf.help/doc/Developer-Guide.mediawiki b/lttng/org.eclipse.linuxtools.tmf.help/doc/Developer-Guide.mediawiki
index 557064d269..1d92f83bb0 100644
--- a/lttng/org.eclipse.linuxtools.tmf.help/doc/Developer-Guide.mediawiki
+++ b/lttng/org.eclipse.linuxtools.tmf.help/doc/Developer-Guide.mediawiki
@@ -11,7 +11,8 @@ The framework can easily be extended to support more trace types. To make a new
* The trace reader
* The trace context
* The trace location
-* (Optional but recommended) The ''org.eclipse.linuxtools.tmf.ui.tracetype'' plug-in extension point
+* The ''org.eclipse.linuxtools.tmf.core.tracetype'' plug-in extension point
+* (Optional) The ''org.eclipse.linuxtools.tmf.ui.tracetypeui'' plug-in extension point
The '''event type''' must implement an ''ITmfEvent'' or extend a class that implements an ''ITmfEvent''. Typically it will extend ''TmfEvent''. The event type must contain all the data of an event. The '''trace reader''' must be of an ''ITmfTrace'' type. The ''TmfTrace'' class will supply many background operations so that the reader only needs to implement certain functions. The '''trace context''' can be seen as the internals of an iterator. It is required by the trace reader to parse events as it iterates the trace and to keep track of its rank and location. It can have a timestamp, a rank, a file position, or any other element, it should be considered to be ephemeral. The '''trace location''' is an element that is cloned often to store checkpoints, it is generally persistent. It is used to rebuild a context, therefore, it needs to contain enough information to unambiguously point to one and only one event. Finally the ''tracetype'' plug-in extension associates a given trace, non-programmatically to a trace type for use in the UI.
@@ -72,252 +73,23 @@ It will need to implement:
* parseEvent (read the next element in the trace)
-Here is an example implementation of the Nexus Trace file
+For reference, there is an example implementation of the Nexus Trace file in
+org.eclipse.linuxtools.tracing.examples.core.trace.nexus.NexusTrace.java.
-<pre>/*******************************************************************************
- * Copyright (c) 2013 Ericsson
- *
- * All rights reserved. This program and the accompanying materials are
- * made available under the terms of the Eclipse Public License v1.0 which
- * accompanies this distribution, and is available at
- * http://www.eclipse.org/legal/epl-v10.html
- *
- * Contributors:
- * Matthew Khouzam - Initial API and implementation
- *******************************************************************************/
-
-package com.example.nexuslite;
-
-import java.io.BufferedReader;
-import java.io.File;
-import java.io.FileInputStream;
-import java.io.FileNotFoundException;
-import java.io.FileReader;
-import java.io.IOException;
-import java.nio.MappedByteBuffer;
-import java.nio.channels.FileChannel;
-import java.nio.channels.FileChannel.MapMode;
-
-import org.eclipse.core.resources.IProject;
-import org.eclipse.core.resources.IResource;
-import org.eclipse.core.runtime.IStatus;
-import org.eclipse.core.runtime.Status;
-import org.eclipse.linuxtools.tmf.core.event.ITmfEvent;
-import org.eclipse.linuxtools.tmf.core.event.ITmfEventField;
-import org.eclipse.linuxtools.tmf.core.event.TmfEvent;
-import org.eclipse.linuxtools.tmf.core.event.TmfEventField;
-import org.eclipse.linuxtools.tmf.core.event.TmfEventType;
-import org.eclipse.linuxtools.tmf.core.exceptions.TmfTraceException;
-import org.eclipse.linuxtools.tmf.core.timestamp.ITmfTimestamp;
-import org.eclipse.linuxtools.tmf.core.timestamp.TmfTimestamp;
-import org.eclipse.linuxtools.tmf.core.trace.ITmfContext;
-import org.eclipse.linuxtools.tmf.core.trace.ITmfEventParser;
-import org.eclipse.linuxtools.tmf.core.trace.ITmfLocation;
-import org.eclipse.linuxtools.tmf.core.trace.TmfContext;
-import org.eclipse.linuxtools.tmf.core.trace.TmfLongLocation;
-import org.eclipse.linuxtools.tmf.core.trace.TmfTrace;
-
-/**
- * Nexus trace type
- *
- * @author Matthew Khouzam
- */
-public class NexusTrace extends TmfTrace implements ITmfEventParser {
-
- private static final int CHUNK_SIZE = 65536; // seems fast on MY system
- private static final int EVENT_SIZE = 8; // according to spec
-
- private TmfLongLocation fCurrentLocation;
- private static final TmfLongLocation NULLLOCATION = new TmfLongLocation(
- (Long) null);
- private static final TmfContext NULLCONTEXT = new TmfContext(NULLLOCATION,
- -1L);
-
- private long fSize;
- private long fOffset;
- private File fFile;
- private String[] fEventTypes;
- private FileChannel fFileChannel;
- private MappedByteBuffer fMappedByteBuffer;
-
- @Override
- public IStatus validate(@SuppressWarnings("unused") IProject project,
- String path) {
- File f = new File(path);
- if (!f.exists()) {
- return new Status(IStatus.ERROR, Activator.PLUGIN_ID,
- "File does not exist"); //$NON-NLS-1$
- }
- if (!f.isFile()) {
- return new Status(IStatus.ERROR, Activator.PLUGIN_ID, path
- + " is not a file"); //$NON-NLS-1$
- }
- String header = readHeader(f);
- if (header.split(",", 64).length == 64) { //$NON-NLS-1$
- return Status.OK_STATUS;
- }
- return new Status(IStatus.ERROR, Activator.PLUGIN_ID,
- "File does not start as a CSV"); //$NON-NLS-1$
- }
-
- @Override
- public ITmfLocation getCurrentLocation() {
- return fCurrentLocation;
- }
-
- @Override
- public void initTrace(IResource resource, String path,
- Class<? extends ITmfEvent> type) throws TmfTraceException {
- super.initTrace(resource, path, type);
- fFile = new File(path);
- fSize = fFile.length();
- if (fSize == 0) {
- throw new TmfTraceException("file is empty"); //$NON-NLS-1$
- }
- String header = readHeader(fFile);
- if (header == null) {
- throw new TmfTraceException("File does not start as a CSV"); //$NON-NLS-1$
- }
- fEventTypes = header.split(",", 64); // 64 values of types according to //$NON-NLS-1$
- // the 'spec'
- if (fEventTypes.length != 64) {
- throw new TmfTraceException(
- "Trace header does not contain 64 event names"); //$NON-NLS-1$
- }
- if (getNbEvents() < 1) {
- throw new TmfTraceException("Trace does not have any events"); //$NON-NLS-1$
- }
- try {
- fFileChannel = new FileInputStream(fFile).getChannel();
- seek(0);
- } catch (FileNotFoundException e) {
- throw new TmfTraceException(e.getMessage());
- } catch (IOException e) {
- throw new TmfTraceException(e.getMessage());
- }
- }
-
- /**
- * @return
- */
- private String readHeader(File file) {
- String header = new String();
- BufferedReader br;
- try {
- br = new BufferedReader(new FileReader(file));
- header = br.readLine();
- br.close();
- } catch (IOException e) {
- return null;
- }
- fOffset = header.length() + 1;
- setNbEvents((fSize - fOffset) / EVENT_SIZE);
- return header;
- }
-
- @Override
- public double getLocationRatio(ITmfLocation location) {
- return ((TmfLongLocation) location).getLocationInfo().doubleValue()
- / getNbEvents();
- }
-
- @Override
- public ITmfContext seekEvent(ITmfLocation location) {
- TmfLongLocation nl = (TmfLongLocation) location;
- if (location == null) {
- nl = new TmfLongLocation(0L);
- }
- try {
- seek(nl.getLocationInfo());
- } catch (IOException e) {
- return NULLCONTEXT;
- }
- return new TmfContext(nl, nl.getLocationInfo());
- }
-
- @Override
- public ITmfContext seekEvent(double ratio) {
- long rank = (long) (ratio * getNbEvents());
- try {
- seek(rank);
- } catch (IOException e) {
- return NULLCONTEXT;
- }
- return new TmfContext(new TmfLongLocation(rank), rank);
- }
-
- private void seek(long rank) throws IOException {
- final long position = fOffset + (rank * EVENT_SIZE);
- int size = Math.min((int) (fFileChannel.size() - position), CHUNK_SIZE);
- fMappedByteBuffer = fFileChannel.map(MapMode.READ_ONLY, position, size);
- }
-
- @Override
- public ITmfEvent parseEvent(ITmfContext context) {
- if ((context == null) || (context.getRank() == -1)) {
- return null;
- }
- TmfEvent event = null;
- long ts = -1;
- int type = -1;
- int payload = -1;
- long pos = context.getRank();
- if (pos < getNbEvents()) {
- try {
- // if we are approaching the limit size, move to a new window
- if ((fMappedByteBuffer.position() + EVENT_SIZE) > fMappedByteBuffer
- .limit()) {
- seek(context.getRank());
- }
- /*
- * the trace format, is:
- *
- * - 32 bits for the time,
- * - 6 for the event type,
- * - 26 for the data.
- *
- * all the 0x00 stuff are masks.
- */
-
- /*
- * it may be interesting to assume if the ts goes back in time,
- * it actually is rolling over we would need to keep the
- * previous timestamp for that, keep the high bits and increment
- * them if the next int ts read is lesser than the previous one
- */
+In this example, the '''validate''' function checks first checks if the file
+exists, then makes sure that it is really a file, and not a directory. Then we
+attempt to read the file header, to make sure that it is really a Nexus Trace.
+If that check passes, we return a TmfValidationStatus with a confidence of 20.
- ts = 0x00000000ffffffffL & fMappedByteBuffer.getInt();
-
- long data = 0x00000000ffffffffL & fMappedByteBuffer.getInt();
- type = (int) (data >> 26) & (0x03f); // first 6 bits
- payload = (int) (data & 0x003FFFFFFL); // last 26 bits
- // the time is in microseconds.
- TmfTimestamp timestamp = new TmfTimestamp(ts, ITmfTimestamp.MICROSECOND_SCALE);
- final String title = fEventTypes[type];
- // put the value in a field
- final TmfEventField tmfEventField = new TmfEventField(
- "value", payload, null); //$NON-NLS-1$
- // the field must be in an array
- final TmfEventField[] fields = new TmfEventField[1];
- fields[0] = tmfEventField;
- final TmfEventField content = new TmfEventField(
- ITmfEventField.ROOT_FIELD_ID, null, fields);
- // set the current location
-
- fCurrentLocation = new TmfLongLocation(pos);
- // create the event
- event = new TmfEvent(this, pos, timestamp, null,
- new TmfEventType(title, title, null), content, null);
- } catch (IOException e) {
- fCurrentLocation = new TmfLongLocation(-1L);
- }
- }
- return event;
- }
-}
-</pre>
+Typically, TmfValidationStatus confidences should range from 1 to 100. 1 meaning
+"there is a very small chance that this trace is of this type", and 100 meaning
+"it is this type for sure, and cannot be anything else". At run-time, the
+auto-detection will pick the the type which returned the highest confidence. So
+checks of the type "does the file exist?" should not return a too high
+confidence.
-In this example the '''validate''' function checks if the file exists and is not a directory.
+Here we used a confidence of 20, to leave "room" for more specific trace types
+in the Nexus format that could be defined in TMF.
The '''initTrace''' function will read the event names, and find where the data starts. After this, the number of events is known, and since each event is 8 bytes long according to the specs, the seek is then trivial.
@@ -327,6 +99,11 @@ The '''parseEvent''' method needs to parse and return the current event and stor
The '''getNext''' method (in base class) will read the next event and update the context. It calls the '''parseEvent''' method to read the event and update the location. It does not need to be overridden and in this example it is not. The sequence of actions necessary are parse the next event from the trace, create an '''ITmfEvent''' with that data, update the current location, call '''updateAttributes''', update the context then return the event.
+Traces will typically implement an index, to make seeking faster. The index can
+be rebuilt every time the trace is opened. Alternatively, it can be saved to
+disk, to make future openings of the same trace quicker. To do so, the trace
+object can implement the '''ITmfPersistentlyIndexable''' interface.
+
=== Trace Context ===
The trace context will be a '''TmfContext'''
@@ -335,13 +112,14 @@ The trace context will be a '''TmfContext'''
The trace location will be a long, representing the rank in the file. The '''TmfLongLocation''' will be the used, once again, no code is required.
-=== (Optional but recommended) The ''org.eclipse.linuxtools.tmf.ui.tracetype'' plug-in extension point ===
+=== The ''org.eclipse.linuxtools.tmf.core.tracetype'' and ''org.eclipse.linuxtools.tmf.ui.tracetypeui'' plug-in extension point ===
-One can implement the ''tracetype'' extension in their own plug-in. In this example, the ''com.example.nexuslite'' plug-in will be modified.
+One should implement the ''tmf.core.tracetype'' extension in their own plug-in.
+In this example, the Nexus trace plug-in will be modified.
The '''plugin.xml''' file in the ui plug-in needs to be updated if one wants users to access the given event type. It can be updated in the Eclipse plug-in editor.
-# In Extensions tab, add the '''org.eclipse.linuxtools.tmf.ui.tracetype''' extension point.
+# In Extensions tab, add the '''org.eclipse.linuxtools.tmf.core.tracetype''' extension point.
[[Image:images/NTTExtension.png]]<br>
[[Image:images/NTTTraceType.png]]<br>
[[Image:images/NTTExtensionPoint.png]]<br>
@@ -360,7 +138,14 @@ The '''event type''' is the canonical path refering to the class of the events o
The '''category''' (optional) is the container in which this trace type will be stored.
-The '''icon''' (optional) is the image to associate with that trace type.
+# (Optional) To also add UI-specific properties to your trace type, use the '''org.eclipse.linuxtools.tmf.ui.tracetypeui''' extension. To do that,
+'''right click''' on the extension then in the context menu, go to
+'''New >''', '''type'''.
+
+The '''tracetype''' here is the '''id''' of the
+''org.eclipse.linuxtools.tmf.core.tracetype'' mentioned above.
+
+The '''icon''' is the image to associate with that trace type.
In the end, the extension menu should look like this.
@@ -370,27 +155,56 @@ In the end, the extension menu should look like this.
* Do not load the whole trace in RAM, it will limit the size of the trace that can be read.
* Reuse as much code as possible, it makes the trace format much easier to maintain.
-* Use Eclipse's editor instead of editing the xml directly.
+* Use Eclipse's editor instead of editing the XML directly.
* Do not forget Java supports only signed data types, there may be special care needed to handle unsigned data.
-* Keep all the code in the same plug-in as the ''tracetype'' if it makes sense from a design point of view. It will make integration easier.
+* If the support for your trace has custom UI elements (like icons, views, etc.), split the core and UI parts in separate plugins, named identically except for a ''.core'' or ''.ui'' suffix.
+** Implement the ''tmf.core.tracetype'' extension in the core plugin, and the ''tmf.ui.tracetypeui'' extension in the UI plugin if applicable.
== Download the Code ==
-The plug-in is available [http://wiki.eclipse.org/images/3/34/Com.example.nexuslite.zip here] with a trace generator and a quick test case.
+The described example is available in the
+org.eclipse.linuxtools.tracing.examples.(tests.)trace.nexus packages with a
+trace generator and a quick test case.
== Optional Trace Type Attributes ==
+
After defining the trace type as described in the previous chapters it is possible to define optional attributes for the trace type.
=== Default Editor ===
-The attribute '''defaultEditor''' allows for configuring the editor to use for displaying the events. If omitted, the ''TmfEventsEditor'' is used as default. To configure an editor, first add the '''defaultEditor''' attribute to the trace type in the extension definition. This can be done by selecting the trace type in the plug-in manifest editor. Then click the right mouse button and select '''New -> defaultEditor''' in the context sensitive menu. Then select the newly added attribute. Now you can specify the editor id to use on the right side of the manifest editor. For example, this attribute could be used to implement an extension of the class ''org.eclipse.ui.part.MultiPageEditor''. The first page could use the ''TmfEventsEditor''' to display the events in a table as usual and other pages can display other aspects of the trace.
+
+The '''defaultEditor''' attribute of the '''org.eclipse.tmf.ui.tracetypeui'''
+extension point allows for configuring the editor to use for displaying the
+events. If omitted, the ''TmfEventsEditor'' is used as default.
+
+To configure an editor, first add the '''defaultEditor''' attribute to the trace
+type in the extension definition. This can be done by selecting the trace type
+in the plug-in manifest editor. Then click the right mouse button and select
+'''New -> defaultEditor''' in the context sensitive menu. Then select the newly
+added attribute. Now you can specify the editor id to use on the right side of
+the manifest editor. For example, this attribute could be used to implement an
+extension of the class ''org.eclipse.ui.part.MultiPageEditor''. The first page
+could use the ''TmfEventsEditor''' to display the events in a table as usual and
+other pages can display other aspects of the trace.
=== Events Table Type ===
-The attribute '''eventsTableType''' allows for configuring the events table class to use in the default events editor. If omitted, the default events table will be used. To configure a trace type specific events table, first add the '''eventsTableType''' attribute to the trace type in the extension definition. This can be done by selecting the trace type in the plug-in manifest editor. Then click the right mouse button and select '''New -> eventsTableType''' in the context sensitive menu. Then select the newly added attribute and click on ''class'' on the right side of the manifest editor. The new class wizard will open. The ''superclass'' field will be already filled with the class ''org.eclipse.linuxtools.tmf.ui.viewers.events.TmfEventsTable''. Using this attribute a table with different columns than the default columns can be defined. See class org.eclipse.linuxtools.internal.lttng2.kernel.ui.viewers.events.Lttng2EventsTable for an example implementation.
-=== Statistics Viewer Type ===
-The attribute '''statisticsViewerType''' allows for defining trace type specific statistics. If omitted, only the default statistics will be displayed in the ''Statistics'' view (part of the ''Tracing'' view category). By default this view displays the total number of events and the number of events per event type for the whole trace and for the selected time range. To configure trace type specific statistics, first add the '''statisticsViewerType''' attribute to the trace type in the extension definition. This can be done by selecting the trace type in the plug-in manifest editor. Then click the right mouse button and select '''New -> statisticsViewerType''' in the context sensitive menu. Then select the newly added attribute and click on ''class'' on the right side of the manifest editor. The new class wizard will open. The ''superclass'' field will be already filled with the class ''org.eclipse.linuxtools.tmf.ui.viewers.statistics.TmfStatisticsViewer''. Now overwrite the relevant methods to provide the trace specific statistics. When executing the plug-in extension in Eclipse and opening the ''Statistics'' view the ''Statistics'' view will show an additional tab beside the global tab that shows the default statistics. The new tab will display the trace specific statistics provided in the ''TmfStatisticsViewer'' sub-class implementation.
+The '''eventsTableType''' attribute of the '''org.eclipse.tmf.ui.tracetypeui'''
+extension point allows for configuring the events table class to use in the
+default events editor. If omitted, the default events table will be used.
+
+To configure a trace type specific events table, first add the
+'''eventsTableType''' attribute to the trace type in the extension definition.
+This can be done by selecting the trace type in the plug-in manifest editor.
+Then click the right mouse button and select '''New -> eventsTableType''' in the
+context sensitive menu. Then select the newly added attribute and click on
+''class'' on the right side of the manifest editor. The new class wizard will
+open. The ''superclass'' field will be already filled with the class ''org.eclipse.linuxtools.tmf.ui.viewers.events.TmfEventsTable''.
+
+By using this attribute, a table with different columns than the default columns
+can be defined. See the class org.eclipse.linuxtools.internal.lttng2.kernel.ui.viewers.events.Lttng2EventsTable
+for an example implementation.
-= View Tutorial =
+= View Tutorial =
This tutorial describes how to create a simple view using the TMF framework and the SWTChart library. SWTChart is a library based on SWT that can draw several types of charts including a line chart which we will use in this tutorial. We will create a view containing a line chart that displays time stamps on the X axis and the corresponding event values on the Y axis.
@@ -401,6 +215,8 @@ This tutorial will cover concepts like:
* Data requests (TmfEventRequest)
* SWTChart integration
+'''Note''': TMF 3.0.0 provides base implementations for generating SWTChart viewers and views. For more details please refer to chapter [[#TMF Built-in Views and Viewers]].
+
=== Prerequisites ===
The tutorial is based on Eclipse 4.4 (Eclipse Luna), TMF 3.0.0 and SWTChart 0.7.0. If you are using TMF from the source repository, SWTChart is already included in the target definition file (see org.eclipse.linuxtools.lttng.target). You can also install it manually by using the Orbit update site. http://download.eclipse.org/tools/orbit/downloads/
@@ -732,6 +548,33 @@ The view is now ready but we need a proper trace to test it. For this example, a
In summary, we have implemented a simple TMF view using the SWTChart library. We made use of signals and requests to populate the view at the appropriate time and we formated the time stamps nicely. We also made sure that the time stamp format is updated when the preferences change.
+== TMF Built-in Views and Viewers ==
+
+TMF provides base implementations for several types of views and viewers for generating custom X-Y-Charts, Time Graphs, or Trees. They are well integrated with various TMF 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 TMF UI plug-in ''org.eclipse.linuxtools.tmf.ui''. See below for a list of relevant java packages:
+
+* Generic
+** ''org.eclipse.linuxtools.tmf.ui.views'': Common TMF view base classes
+* X-Y-Chart
+** ''org.eclipse.linuxtools.tmf.ui.viewers.xycharts'': Common base classes for X-Y-Chart viewers based on SWTChart
+** ''org.eclipse.linuxtools.tmf.ui.viewers.xycharts.barcharts'': Base classes for bar charts
+** ''org.eclipse.linuxtools.tmf.ui.viewers.xycharts.linecharts'': Base classes for line charts
+* Time Graph View
+** ''org.eclipse.linuxtools.tmf.ui.widgets.timegraph'': Base classes for time graphs e.g. Gantt-charts
+* Tree Viewer
+** ''org.eclipse.linuxtools.tmf.ui.viewers.tree'': Base classes for TMF specific tree viewers
+
+Several features in TMF and the Eclipse LTTng integration are using this framework and can be used as example for further developments:
+* X-Y- Chart
+** ''org.eclipse.linuxtools.internal.lttng2.ust.ui.views.memusage.MemUsageView.java''
+** ''org.eclipse.linuxtools.internal.lttng2.kernel.ui.views.cpuusage.CpuUsageView.java''
+** ''org.eclipse.linuxtools.tracing.examples.ui.views.histogram.NewHistogramView.java''
+* Time Graph View
+** ''org.eclipse.linuxtools.internal.lttng2.kernel.ui.views.controlflow.ControlFlowView.java''
+** ''org.eclipse.linuxtools.internal.lttng2.kernel.ui.views.resources.ResourcesView.java''
+* Tree Viewer
+** ''org.eclipse.linuxtools.tmf.ui.views.statesystem.TmfStateSystemExplorer.java''
+** ''org.eclipse.linuxtools.internal.lttng2.kernel.ui.views.cpuusage.CpuUsageComposite.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.
@@ -4285,4 +4128,4 @@ To add a stream-based View, simply monitor the TmfPacketStreamSelectedSignal in
* Support pcapng. See: http://www.winpcap.org/ntar/draft/PCAP-DumpFileFormat.html for the file format.
* Add SWTBOT tests to org.eclipse.linuxtools.tmf.pcap.ui
* Add a Raw Viewer, similar to Wireshark. We could use the “Show Raw” in the event editor to do that.
-* Externalize strings in org.eclipse.linuxtools.pcap.core. At the moment, all the strings are hardcoded. It would be good to externalize them all. \ No newline at end of file
+* Externalize strings in org.eclipse.linuxtools.pcap.core. At the moment, all the strings are hardcoded. It would be good to externalize them all.
diff --git a/lttng/org.eclipse.linuxtools.tmf.help/doc/images/NTTAddType.png b/lttng/org.eclipse.linuxtools.tmf.help/doc/images/NTTAddType.png
index be334dd590..6f97c5eab5 100644
--- a/lttng/org.eclipse.linuxtools.tmf.help/doc/images/NTTAddType.png
+++ b/lttng/org.eclipse.linuxtools.tmf.help/doc/images/NTTAddType.png
Binary files differ
diff --git a/lttng/org.eclipse.linuxtools.tmf.help/doc/images/NTTExtensionPoint.png b/lttng/org.eclipse.linuxtools.tmf.help/doc/images/NTTExtensionPoint.png
index c3077106ea..20b814fad8 100644
--- a/lttng/org.eclipse.linuxtools.tmf.help/doc/images/NTTExtensionPoint.png
+++ b/lttng/org.eclipse.linuxtools.tmf.help/doc/images/NTTExtensionPoint.png
Binary files differ
diff --git a/lttng/org.eclipse.linuxtools.tmf.help/doc/images/NTTPluginxmlComplete.png b/lttng/org.eclipse.linuxtools.tmf.help/doc/images/NTTPluginxmlComplete.png
index 6f99cdb8ee..d9b12e58e8 100644
--- a/lttng/org.eclipse.linuxtools.tmf.help/doc/images/NTTPluginxmlComplete.png
+++ b/lttng/org.eclipse.linuxtools.tmf.help/doc/images/NTTPluginxmlComplete.png
Binary files differ
diff --git a/lttng/org.eclipse.linuxtools.tmf.help/doc/images/NTTTraceType.png b/lttng/org.eclipse.linuxtools.tmf.help/doc/images/NTTTraceType.png
index 8de66a7c1e..5ba1f8e798 100644
--- a/lttng/org.eclipse.linuxtools.tmf.help/doc/images/NTTTraceType.png
+++ b/lttng/org.eclipse.linuxtools.tmf.help/doc/images/NTTTraceType.png
Binary files differ

Back to the top