X-Git-Url: https://git.lttng.org/?p=lttng-tools.git;a=blobdiff_plain;f=doc%2Fquickstart.txt;h=9bcb8460469505f8834b86cce940111ca8bd0aa2;hp=a979f5bfe8b00f8195aaf4e793b17a77eb9e19fe;hb=ae403e46640d0614bd6e7df6a04b19093c770124;hpb=6f8eb30473ece47ca4bad68d3f4da2ea7a63e6a4 diff --git a/doc/quickstart.txt b/doc/quickstart.txt index a979f5bfe..9bcb84604 100644 --- a/doc/quickstart.txt +++ b/doc/quickstart.txt @@ -1,7 +1,10 @@ NOTES: -------------- -2011-07-21 : User-space tracer is not released. Tracing in user-space at this -point is not possible with lttng-tools. + +2011-12-12: For user-space tracing, only the global UST domain ("-u" alone) is +supported meaning that if you enable a tracepoint for user-space it will be +enabled for all applications for the current tracing session you are working +on. QUICKSTART -------------- @@ -10,44 +13,53 @@ This is a quick start guide for the complete LTTng tool chain. This is divided in three sections respectively kernel tracing, user-space tracing and reading a trace. -See the README file for installation procedure or use the various Linux +See the README.adoc file for installation procedure or use the various Linux distribution packages. -In order to trace the kernel, you'll need the lttng-modules >= 2.0 compiled and -installed. See http://lttng.org/lttng2.0 for more instructions for that part. -For user-space tracing, you'll need an instrumented application, please see -http://lttng.org/ust. +In order to trace the kernel, you'll need the lttng-modules 2.0 compiled and +installed. See https://lttng.org/lttng2.0 for more instructions for that part. +For user-space tracing, you'll need an instrumented application with lttng-ust +2.0. -lttng-tools provide a session daemon (ltt-sessiond) that acts as a tracing +lttng-tools provide a session daemon (lttng-sessiond) that acts as a tracing registry. To trace any instrumented applications or the kernel, a registered tracing session is needed beforehand. To interact with the session daemon and a -tracing session, you should use the lttng command line UI (lttng). +tracing session, you should use the lttng command line UI (lttng). It is also +possible to use the liblttngctl library for tracing control (lttng.h). -Here is a list of some new powerful features the LTTng 2.0 kernel tracer -offers: +Here is a list of some powerful features the LTTng 2.0 kernel tracer offers: * Kprobes support * Function Tracer support * Context information support (add context data to an event) * Perf counter support + * Tracepoint support + +And for the LTTng UST 2.0 tracer: + + * Applications registration + * Automatic tracepoints activation upon app. registration + * Context information support + * Safe buffers after application crash + * Per-user tracing (root access *not* mandatory) -The next sections explain how to do tracing :) +The next sections explains how to do tracing :) Kernel Tracing -------------- -You have to modprobe the lttng-modules manually or the session daemon will do -it for you if those modules can be found on your system. +You can start the session daemon by invoking the command "lttng-sessiond", or +let the lttng command line tool do it for you. The session daemon loads the +LTTng tracer modules for you if those modules can be found on your system. If +they are not found, the kernel tracing feature will be unavailable. -Again, you can then start the session daemon (ltt-sessiond) by hand or the -lttng command line tool will do it for you. - -List possible kernel events: +List available kernel events: # lttng list -k -1) Create a tracing session. A .lttngrc will be created in $HOME containing -the session name (here 'mysession') you are working on. +1) Create a tracing session. The .lttng directory will be created with .lttngrc +file in $HOME containing the session name (here 'mysession') you are working +on. # lttng create mysession @@ -55,73 +67,84 @@ If you have multiple sessions, you can change the current session by using # lttng set-session myothersession -2) Enable event(s). Here for example, we want only 'sched_switch' and -'sys_enter' events for the kernel (-k/--kernel). +2) Enable all tracepoints and all system call events. -# lttng enable-event sched_switch,sys_enter -k +# lttng enable-event -a -k -or enable ALL events (-a/--all): +3) Enable tracepoint event(s). Here for example, we want only +'sched_switch' and 'sched_wakeup' events for the kernel (-k/--kernel). -# lttng enable-event -a -k +# lttng enable-event sched_switch,sched_wakeup -k -3) Enable kprobes and/or the function tracer with lttng +or enable ALL tracepoint events: + +# lttng enable-event -a -k --tracepoint + +4) Enable all system call event(s). + +# lttng enable-event -a -k --syscall + +5) Enable kprobes and/or the function tracer with lttng This is a new feature made possible by the new LTTng 2.0 kernel tracer. You can -enable a Kprobe (by Masami Hiramatsu) and data will be output in the trace -along side with your tracing data. +enable a dynamic probe and data will be output in the trace along side with +your tracing data. -# lttng enable-event aname --kprobe symbol+0xffff7260695 +# lttng enable-event aname -k --probe symbol+0x0 or -# lttng enable-event aname --kprobe 0xffff7260695 +# lttng enable-event aname -k --probe 0xffff7260695 -Either an
or a can be used for kprobes. +Either an
or a can be used for probes. -You can also enable function tracer, which uses the ftrace API (by Steven +You can also enable function tracer, which uses the Ftrace API (by Steven Rostedt). Again, data will be output in the trace. -# lttng enable-event aname --function +# lttng enable-event aname -k --function -4) Enable context information for an event: +6) Enable context information for an event: This is also a new feature which allows you to add context information to an event. For example, you can add the PID along with the event information: -# lttng add-context -k -e sched_switch -t 0 +# lttng add-context -k -e sched_switch -t pid At this point, you will have to look at 'lttng add-context --help' for all -possible context type which are integer values. +possible context type. You can on the same line activate multiple context: -# lttng add-context -k -e sched_switch -t 0 -t 2 -t 4 +# lttng add-context -k -e sched_switch -t pid -t nice -t tid -5) Enable perf counter for an event: +7) Enable perf counter for an event: Again, a new powerful feature is the possibility to add perf counter data -(using the perf API by Ingo Molnar) to the trace on a per event basis. Let say -we want to get the CPU cycles at each define event: +(using the perf API by Ingo Molnar and Thomas Gleixner) to the trace on a per +event basis. Let say we want to get the CPU cycles at each event: -# lttng add-context -k -e sched_switch --perf-name aname --perf-type 0 --perf-id 0 +# lttng add-context -k -e sched_switch -t perf:cpu-cycles You'll have to use the add-context help for all possible perf counter values. -6) Start tracing: +8) Start tracing: # lttng start Tracing is in progress at this point and traces will be written in $HOME/lttng-traces/mysession--