[deliverable/tracecompass.git] / doc / org.eclipse.tracecompass.gdbtrace.doc.user / doc / User-Guide.mediawiki


= Table of Contents =

__TOC__

= Overview =

The GDB Tracepoint Analysis feature is an extension to the Tracing and Monitoring Framework that allows the visualization and analysis of C/C++ tracepoint data collected by GDB and stored to a log file.

= Getting Started =

The feature can be installed from the Eclipse update site by selecting '''Linux Tools''' > '''GDB Tracepoint Analysis'''.

The feature requires GDB version 7.2 or later to be installed on the local host. The executable program 'gdb' must be found in the path.

= GDB Trace Perspective =

To open the perspective, select '''Window''' > '''Open Perspective''' > '''Other...''' > '''GDB Trace'''.

The perspective includes the following views by default:

* '''Project Explorer''': This view shows the projects in the workspace and is used to create and manage Tracing projects.
* '''Debug''': This view shows the running C/C++ Postmortem Debugger instances and displays the thread and stack trace associated with a tracepoint.
* '''Trace Control''': This view shows the status of the debugger and allows navigation of trace records.
* '''Console''': This view displays console output of the C/C++ Postmortem Debugger.

The editor area contains the '''Events''' and '''C/C++''' editors when a GDB Trace is opened.

[[Image:images/GDBTracePerspective.png]]

= Collecting Tracepoint Data =

Collecting the C/C++ tracepoint data is outside the scope of this feature. It can be done from the GDB command line or by using the CDT debug component within Eclipse. See the CDT FAQ entry in the [[#References | References]] section.

= Importing Tracepoint Data =

Some information in this section is redundant with the LTTng User Guide. For further details, see the LTTng User Guide entry in the [[#References | References]] section.

== Creating a Tracing Project ==

In the '''Project Explorer''' view, right-click and select '''New''' > '''Project...''' from the context menu. In the '''New Project''' dialog, select '''Tracing''' > '''Tracing Project''', click '''Next''', name your project and click '''Finish'''.

== Importing a GDB Trace ==

In your tracing project, right-click on the '''Traces''' folder and select '''Import...'''. Browse to, or enter, a source directory. Select the trace file in the tree. Optionally set the trace type to '''GDB : GDB Trace'''. Click '''Finish'''.

Alternatively, the trace can be drag & dropped to the '''Traces''' folder from any external file manager.

== Selecting the GDB Trace Type ==

Right-click the imported trace in the '''Traces''' folder and choose '''Select Trace Type...''' > '''GDB''' > '''GDB Trace''' from the context menu. This step can be omitted if the trace type was selected at import.

The trace will be updated with the GDB icon [[Image:images/gdb_icon16.png]].

== Selecting the Trace Executable ==

The executable file that created the tracepoint data must be identified so that the C/C++ Postmortem Debugger can be launched properly.

Right-click the GDB trace in the '''Traces''' folder and choose '''Select Trace Executable...''' from the context menu. Browse to, or enter, the path of the executable file and press '''OK'''.

The selected file must be recognized by GDB as an executable.

= Visualizing Tracepoint Data =

== Opening a GDB Trace ==

In the '''Traces''' folder, double-click the GDB trace or right-click it and select '''Open''' from the context menu.

The tracepoint data will be opened in an Events editor, and a C/C++ Postmortem Debugger instance will be launched.

If available in the workspace, the source code corresponding to the first trace record will also be opened in a C/C++ editor.

At this point it is recommended to relocate the Events editor outside of the default editor area, so that it is not hidden by the C/C++ editor.

== Viewing Trace Data ==

In the Events editor, a table is shown with one row for each trace record. The '''Trace Frame''' column shows the sequential trace record number. The '''Tracepoint''' column shows the number assigned by GDB at collection time for this tracepoint. The '''File''' column shows the file name, line number and method where the tracepoint was set. The '''Content''' column shows the data collected at run-time by the tracepoint.

Searching and filtering can be done on any column by entering a regular expression in the column header.

== Navigating the GDB Trace ==

Trace records can be selected in the Events editor using the keyboard or mouse. The C/C++ Postmortem Debugger in the '''Debug''' view will be updated to show the stack trace of the current trace record.

The trace can also be navigated from the '''Trace Control''' view by clicking the '''Next Trace Record''' or '''Previous Trace Record''' buttons. The Events editor and '''Debug''' views will be updated.

= References =

* [http://wiki.eclipse.org/index.php/Linux_Tools_Project/LTTng2/User_Guide LTTng User Guide]
* [http://wiki.eclipse.org/CDT/User/FAQ#How_can_I_trace_my_application_using_C.2FC.2B.2B_Tracepoints.3F CDT FAQ - How can I trace my application using C/C++ Tracepoints?]

= Updating This Document =

This document is maintained in a collaborative wiki.  If you wish to update or modify this document please visit [http://wiki.eclipse.org/index.php/Linux_Tools_Project/GDB_Tracepoint_Analysis/User_Guide http://wiki.eclipse.org/Linux_Tools_Project/GDB_Tracepoint_Analysis/User_Guide]
Commit	Line	Data
6de2f761	1
39191d76 AM	2	= Table of Contents =
	3
	4	__TOC__
	5
6de2f761 PT	6	= Overview =
6de2f761 PT	7
f900ecbf PT	8	The GDB Tracepoint Analysis feature is an extension to the Tracing and Monitoring Framework that allows the visualization and analysis of C/C++ tracepoint data collected by GDB and stored to a log file.
	9
	10	= Getting Started =
	11
	12	The feature can be installed from the Eclipse update site by selecting '''Linux Tools''' > '''GDB Tracepoint Analysis'''.
	13
	14	The feature requires GDB version 7.2 or later to be installed on the local host. The executable program 'gdb' must be found in the path.
	15
	16	= GDB Trace Perspective =
	17
	18	To open the perspective, select '''Window''' > '''Open Perspective''' > '''Other...''' > '''GDB Trace'''.
	19
	20	The perspective includes the following views by default:
	21
	22	* '''Project Explorer''': This view shows the projects in the workspace and is used to create and manage Tracing projects.
	23	* '''Debug''': This view shows the running C/C++ Postmortem Debugger instances and displays the thread and stack trace associated with a tracepoint.
	24	* '''Trace Control''': This view shows the status of the debugger and allows navigation of trace records.
	25	* '''Console''': This view displays console output of the C/C++ Postmortem Debugger.
	26
	27	The editor area contains the '''Events''' and '''C/C++''' editors when a GDB Trace is opened.
	28
	29	[[Image:images/GDBTracePerspective.png]]
	30
	31	= Collecting Tracepoint Data =
	32
	33	Collecting the C/C++ tracepoint data is outside the scope of this feature. It can be done from the GDB command line or by using the CDT debug component within Eclipse. See the CDT FAQ entry in the [[#References \| References]] section.
	34
	35	= Importing Tracepoint Data =
	36
	37	Some information in this section is redundant with the LTTng User Guide. For further details, see the LTTng User Guide entry in the [[#References \| References]] section.
	38
	39	== Creating a Tracing Project ==
	40
	41	In the '''Project Explorer''' view, right-click and select '''New''' > '''Project...''' from the context menu. In the '''New Project''' dialog, select '''Tracing''' > '''Tracing Project''', click '''Next''', name your project and click '''Finish'''.
	42
	43	== Importing a GDB Trace ==
	44
	45	In your tracing project, right-click on the '''Traces''' folder and select '''Import...'''. Browse to, or enter, a source directory. Select the trace file in the tree. Optionally set the trace type to '''GDB : GDB Trace'''. Click '''Finish'''.
	46
	47	Alternatively, the trace can be drag & dropped to the '''Traces''' folder from any external file manager.
	48
	49	== Selecting the GDB Trace Type ==
	50
	51	Right-click the imported trace in the '''Traces''' folder and choose '''Select Trace Type...''' > '''GDB''' > '''GDB Trace''' from the context menu. This step can be omitted if the trace type was selected at import.
	52
	53	The trace will be updated with the GDB icon [[Image:images/gdb_icon16.png]].
	54
	55	== Selecting the Trace Executable ==
	56
	57	The executable file that created the tracepoint data must be identified so that the C/C++ Postmortem Debugger can be launched properly.
	58
50cd55be	59	Right-click the GDB trace in the '''Traces''' folder and choose '''Select Trace Executable...''' from the context menu. Browse to, or enter, the path of the executable file and press '''OK'''.
f900ecbf PT	60
	61	The selected file must be recognized by GDB as an executable.
	62
	63	= Visualizing Tracepoint Data =
	64
	65	== Opening a GDB Trace ==
	66
	67	In the '''Traces''' folder, double-click the GDB trace or right-click it and select '''Open''' from the context menu.
	68
	69	The tracepoint data will be opened in an Events editor, and a C/C++ Postmortem Debugger instance will be launched.
	70
	71	If available in the workspace, the source code corresponding to the first trace record will also be opened in a C/C++ editor.
	72
	73	At this point it is recommended to relocate the Events editor outside of the default editor area, so that it is not hidden by the C/C++ editor.
	74
	75	== Viewing Trace Data ==
	76
	77	In the Events editor, a table is shown with one row for each trace record. The '''Trace Frame''' column shows the sequential trace record number. The '''Tracepoint''' column shows the number assigned by GDB at collection time for this tracepoint. The '''File''' column shows the file name, line number and method where the tracepoint was set. The '''Content''' column shows the data collected at run-time by the tracepoint.
	78
	79	Searching and filtering can be done on any column by entering a regular expression in the column header.
	80
	81	== Navigating the GDB Trace ==
	82
	83	Trace records can be selected in the Events editor using the keyboard or mouse. The C/C++ Postmortem Debugger in the '''Debug''' view will be updated to show the stack trace of the current trace record.
	84
	85	The trace can also be navigated from the '''Trace Control''' view by clicking the '''Next Trace Record''' or '''Previous Trace Record''' buttons. The Events editor and '''Debug''' views will be updated.
6de2f761 PT	86
	87	= References =
	88
	89	* [http://wiki.eclipse.org/index.php/Linux_Tools_Project/LTTng2/User_Guide LTTng User Guide]
	90	* [http://wiki.eclipse.org/CDT/User/FAQ#How_can_I_trace_my_application_using_C.2FC.2B.2B_Tracepoints.3F CDT FAQ - How can I trace my application using C/C++ Tracepoints?]
	91
	92	= Updating This Document =
	93
	94	This document is maintained in a collaborative wiki. If you wish to update or modify this document please visit [http://wiki.eclipse.org/index.php/Linux_Tools_Project/GDB_Tracepoint_Analysis/User_Guide http://wiki.eclipse.org/Linux_Tools_Project/GDB_Tracepoint_Analysis/User_Guide]