--- /dev/null
+.TH "LTTNG-SESSIOND" "8" "January 31, 2012" "" ""
+
+.SH "NAME"
+lttng-sessiond \(em LTTng 2.0 central tracing registry session daemon.
+
+.SH "SYNOPSIS"
+
+.PP
+.nf
+lttng-sessiond [OPTIONS]
+.fi
+.SH "DESCRIPTION"
+
+.PP
+The LTTng project aims at providing highly efficient tracing tools for Linux.
+It's tracers help tracking down performance issues and debugging problems
+involving multiple concurrent processes and threads. Tracing across multiple
+systems is also possible.
+
+The session daemon, acting as a tracing registry, allow you to interact with
+multiple tracers (kernel and user-space) inside the same container, a tracing
+session. Trace can be gathered from the kernel and/or instrumented applications
+(lttng-ust(3)). Aggregating those traces is done using the babeltrace(1) text
+viewer.
+
+In order to trace the kernel, the session daemon needs to be running as root.
+LTTng provides the use of a \fBtracing group\fP (default: tracing). Whomever is
+in that group can interact with the root session daemon and thus trace the
+kernel. Session daemons can co-exist meaning that you can have a session daemon
+running as Alice that can be use to trace her applications along side with a
+root daemon or even a Bob daemon. We highly recommand to start the session
+daemon at boot time for stable and long term tracing.
+
+The session daemon is in charge of managing trace data consumers by spawning
+one when the time as come. The user don't need to manage the lttng-consumerd.
+.SH "OPTIONS"
+
+.PP
+This program follow the usual GNU command line syntax with long options starting with
+two dashes. Below is a summary of the available options.
+.PP
+
+.TP
+.BR "-h, --help"
+Show summary of possible options and commands
+.TP
+.BR "-v, --verbose"
+Increase verbosity
+
+There is three debugging level which will print on stderr. Maximum verbosity is
+\fB-vvv\fP.
+.TP
+.BR " --verbose-consumer"
+Verbose mode for consumer. Activate DBG() macro.
+.TP
+.BR "-d, --daemonize"
+Start as a daemon
+.TP
+.BR "-g, --group=NAME"
+Specify the tracing group name. (default: tracing)
+.TP
+.BR "-V, --version"
+Show version number
+.TP
+.BR "-S, --sig-parent"
+Send SIGCHLD to parent pid to notify readiness.
+
+This is used by \fBlttng(1)\fP to get notified when the session daemon is ready
+to accept command. By building a third part tool over liblttng-ctl, this option
+can be very handy to synchronize the control tool and the session daemon.
+.TP
+.BR "-q, --quiet"
+No output at all.
+.TP
+.BR " --no-kernel"
+No kernel tracer support
+.TP
+.BR "-c, --client-sock=PATH"
+Specify path for the client unix socket
+.TP
+.BR "-a, --apps-sock PATH"
+Specify path for apps unix socket
+.TP
+.BR " --kconsumerd-err-sock=PATH"
+Specify path for the kernel consumer error socket
+.TP
+.BR " --kconsumerd-cmd-sock=PATH
+Specify path for the kernel consumer command socket
+.TP
+.BR " --ustconsumerd32-err-sock=PATH
+Specify path for the 32-bit UST consumer error socket
+.TP
+.BR " --ustconsumerd64-err-sock=PATH
+Specify path for the 64-bit UST consumer error socket
+.TP
+.BR " --ustconsumerd32-cmd-sock=PATH
+Specify path for the 32-bit UST consumer command socket
+.TP
+.BR " --ustconsumerd64-cmd-sock=PATH
+Specify path for the 64-bit UST consumer command socket
+.TP
+.BR " --consumerd32-path=PATH
+Specify path for the 32-bit UST consumer daemon binary
+.TP
+.BR " --consumerd32-libdir=PATH
+Specify path for the 32-bit UST consumer daemon libraries
+.TP
+.BR " --consumerd64-path=PATH
+Specify path for the 64-bit UST consumer daemon binary
+.TP
+.BR " --consumerd64-libdir=PATH
+Specify path for the 64-bit UST consumer daemon libraries
+.SH "ENVIRONMENT VARIABLES"
+
+.PP
+Note that all command line options will override environmenal variables.
+.PP
+
+.PP
+.IP "LTTNG_CONSUMERD32_BIN"
+Allow to specify the 32-bit consumer binary path. \fB--consumerd32-path\fP
+override this variable.
+.IP "LTTNG_CONSUMERD64_BIN"
+Allow to specify the 64-bit consumer binary path. \fB--consumerd64-path\fP
+override this variable.
+.IP "LTTNG_CONSUMERD32_LIBDIR"
+Allow to specifiy the 64-bit library path containing libconsumer.so.
+\fB--consumerd32-libdir\fP override this variable.
+.IP "LTTNG_CONSUMERD64_LIBDIR"
+Allow to specifiy the 32-bit library path containing libconsumer.so.
+\fB--consumerd64-libdir\fP override this variable.
+.SH "SEE ALSO"
+
+.PP
+babeltrace(1), lttng-ust(3), lttng(1)
+.PP
+.SH "BUGS"
+
+.PP
+No show stopper bugs known yet at this stable version.
+
+If you encounter any issues or usability problem, please report it on our
+mailing list <lttng-dev@lists.lttng.org> to help improve this project.
+.SH "CREDITS"
+
+.PP
+lttng-sessiond is distributed under the GNU public license version 2. See the
+file COPYING for details.
+.PP
+A Web site is available at http://lttng.org for more information on the LTTng
+project.
+.PP
+You can also find our git tree at http://git.lttng.org.
+.PP
+Mailing lists for support and development: <lttng-dev@lists.lttng.org>.
+.PP
+You can find us on IRC server irc.oftc.net (OFTC) in #lttng.
+.PP
+.SH "THANKS"
+
+.PP
+Thanks to Yannick Brosseau without whom this project would never have been so
+lean and mean! Also thanks to the Ericsson teams working on tracing which help
+us greatly with detailled bug reports and unsual use cases.
+
+Thanks to our beloved packager Alexandre Montplaisir-Goncalves (Ubuntu and PPA
+maintainer) and Jon Bernard for our Debian packages.
+
+Special thanks to Michel Dagenais and the DORSAL laboratory at Polytechnique de
+Montreal for the LTTng journey.
+.pp
+.SH "AUTHORS"
+
+.PP
+lttng-tools was originally written by Mathieu Desnoyers, Julien Desfossez and
+David Goulet. More people have since contributed to it. It is currently
+maintained by David Goulet <dgoulet@efficios.com>.
+.PP
--- /dev/null
+.TH "LTTNG" "1" "February 9, 2012" "" ""
+
+.SH "NAME"
+lttng \(em LTTng 2.0 tracer control command line tool
+
+.SH "SYNOPSIS"
+
+.PP
+.nf
+lttng [OPTIONS] <COMMAND>
+.fi
+.SH "DESCRIPTION"
+
+.PP
+The LTTng project aims at providing highly efficient tracing tools for Linux.
+It's tracers help tracking down performance issues and debugging problems
+involving multiple concurrent processes and threads. Tracing across multiple
+systems is also possible.
+
+The \fBlttng\fP command line tool from lttng-tools package is used to control
+both kernel and user-space tracing. Every interactions with the tracer should
+be done by this tool or by the liblttng-ctl provided with the lttng-tools
+package.
+
+LTTng uses a session daemon (lttng-sessiond(8)), acting as a tracing registry,
+which permits you to interact with multiple tracers (kernel and user-space)
+inside the same container, a tracing session. Traces can be gathered from the
+kernel and/or instrumented applications (lttng-ust(3)). Aggregating and reading
+those traces is done using the babeltrace(1) text viewer.
+
+In order to trace the kernel, the session daemon needs to be running as root.
+LTTng provides the use of a \fBtracing group\fP (default: tracing). Whomever is
+in that group can interact with the root session daemon and thus trace the
+kernel. Session daemons can co-exist meaning that you can have a session daemon
+running as Alice that can be use to trace her applications along side with a
+root daemon or even a Bob daemon. We highly recommand to start the session
+daemon at boot time for stable and long term tracing.
+
+Every user-space applications instrumented with lttng-ust(3), will
+automatically register to the session daemon. This feature gives you the
+ability to list available traceable applications and tracepoints on a per user
+basis. (See \fBlist\fP command).
+.SH "OPTIONS"
+
+.PP
+This program follow the usual GNU command line syntax with long options starting with
+two dashes. Below is a summary of the available options.
+.PP
+
+.TP
+.BR "-h, --help"
+Show summary of possible options and commands.
+.TP
+.BR "-v, --verbose"
+Increase verbosity.
+FIXME : details (-v : sessiond verbose, -vv : consumerd verbose, etc) ?
+.TP
+.BR "-q, --quiet"
+Suppress all messages (even errors).
+.TP
+.BR "-g, --group NAME"
+Set unix tracing group name. (default: tracing)
+.TP
+.BR "-n, --no-sessiond"
+Don't automatically spawn a session daemon.
+.TP
+.BR "--sessiond-path"
+Set session daemon full binary path.
+.TP
+.BR "--list-options"
+Simple listing of lttng options.
+.TP
+.BR "--list-commands"
+Simple listing of lttng commands.
+.SH "COMMANDS"
+
+.TP
+\fBadd-context\fP
+.nf
+Add context to event(s) and/or channel(s).
+
+A context is basically extra information appended to a channel or event. For
+instance, you could ask the tracer to add the PID information within the
+"sched_switch" kernel event. You can also add performance monitoring unit
+counters (perf PMU) using the perf kernel API).
+
+For example, this command will add the context information 'prio' and two perf
+counters (hardware branch misses and cache misses), to all events in the trace
+data output:
+
+# lttng add-context -k -t prio -t perf:branch-misses -t perf:cache-misses
+
+Please take a look at the help (-h/--help) for a detailed list of available
+contexts.
+
+If no channel and no event is given (-c/-e), the context is added to all
+channels (which applies automatically to all events in that channel). Otherwise
+the context will be added only to the channel (-c) and/or event (-e) indicated.
+
+If \fB-s, --session\fP is omitted, the session name is taken from the .lttngrc
+file.
+.fi
+
+.B OPTIONS:
+
+.nf
+-h, --help
+ Show summary of possible options and commands.
+-s, --session NAME
+ Apply on session name.
+-c, --channel NAME
+ Apply on channel name.
+-e, --event NAME
+ Apply on event name.
+-k, --kernel
+ Apply for the kernel tracer
+-u, --userspace
+ Apply for the user-space tracer
+-t, --type TYPE
+ Context type. You can repeat this option on the command line. Please
+ use "lttng add-context -h" to list all available types.
+.fi
+
+.IP
+
+.IP "\fBcalibrate\fP"
+.nf
+Quantify LTTng overhead
+
+The LTTng calibrate command can be used to find out the combined average
+overhead of the LTTng tracer and the instrumentation mechanisms used. This
+overhead can be calibrated in terms of time or using any of the PMU performance
+counter available on the system.
+
+For now, the only calibration implemented is that of the kernel function
+instrumentation (kretprobes).
+
+* Calibrate kernel function instrumentation
+
+Let's use an example to show this calibration. We use an i7 processor with 4
+general-purpose PMU registers. This information is available by issuing dmesg,
+looking for "generic registers".
+
+This sequence of commands will gather a trace executing a kretprobe hooked on
+an empty function, gathering PMU counters LLC (Last Level Cache) misses
+information (see lttng add-context --help to see the list of available PMU
+counters).
+
+# lttng create calibrate-function
+# lttng enable-event calibrate --kernel --function lttng_calibrate_kretprobe
+# lttng add-context --kernel -t perf:LLC-load-misses -t perf:LLC-store-misses \\
+ -t perf:LLC-prefetch-misses
+# lttng start
+# for a in $(seq 1 10); do \\
+ lttng calibrate --kernel --function;
+ done
+# lttng destroy
+# babeltrace $(ls -1drt ~/lttng-traces/calibrate-function-* | tail -n 1)
+
+The output from babeltrace can be saved to a text file and opened in a
+spreadsheet (e.g. oocalc) to focus on the per-PMU counter delta between
+consecutive "calibrate_entry" and "calibrate_return" events. Note that these
+counters are per-CPU, so scheduling events would need to be present to account
+for migration between CPU. Therefore, for calibration purposes, only events
+staying on the same CPU must be considered.
+
+The average result, for the i7, on 10 samples:
+
+ Average Std.Dev.
+perf_LLC_load_misses: 5.0 0.577
+perf_LLC_store_misses: 1.6 0.516
+perf_LLC_prefetch_misses: 9.0 14.742
+
+As we can notice, the load and store misses are relatively stable across runs
+(their standard deviation is relatively low) compared to the prefetch misses.
+We can conclude from this information that LLC load and store misses can be
+accounted for quite precisely, but prefetches within a function seems to behave
+too erratically (not much causality link between the code executed and the CPU
+prefetch activity) to be accounted for.
+.fi
+
+.B OPTIONS:
+
+.nf
+-h, --help
+ Show summary of possible options and commands.
+-k, --kernel
+ Apply for the kernel tracer
+-u, --userspace
+ Apply for the user-space tracer
+--function
+ Dynamic function entry/return probe (default)
+.fi
+
+.IP
+
+.IP "\fBcreate\fP [OPTIONS] [NAME]
+.nf
+Create tracing session.
+
+A tracing session contains channel(s) which contains event(s). It is domain
+agnostic meaning that you can enable channels and events for either the
+user-space tracer and/or the kernel tracer. It acts like a container
+aggregating multiple tracing sources.
+
+On creation, a \fB.lttngrc\fP file is created in your $HOME directory
+containing the current session name. If NAME is omitted, a session name is
+automatically created having this form: 'auto-yyyymmdd-hhmms'.
+
+If no \fB-o, --output\fP is specified, the traces will be written in
+$HOME/lttng-traces.
+.fi
+
+.B OPTIONS:
+
+.nf
+-h, --help
+ Show summary of possible options and commands.
+--list-options
+ Simple listing of options
+-o, --output PATH
+ Specify output path for traces
+.fi
+
+.IP
+
+.IP "\fBdestroy\fP [OPTIONS] [NAME]"
+.nf
+Teardown tracing session
+
+Free memory on the session daemon and tracer side. It's gone!
+
+If NAME is omitted, the session name is taken from the .lttngrc file.
+.fi
+
+.B OPTIONS:
+
+.nf
+-h, --help
+ Show summary of possible options and commands.
+--list-options
+ Simple listing of options
+.fi
+
+.IP
+
+.IP "\fBenable-channel\fP NAME[,NAME2,...] [-k|-u] [OPTIONS]"
+.nf
+Enable tracing channel
+
+If \fB-s, --session\fP is omitted, the session name is taken from the .lttngrc
+file.
+.fi
+
+.B OPTIONS:
+
+.nf
+-h, --help
+ Show this help
+--list-options
+ Simple listing of options
+-s, --session
+ Apply on session name
+-k, --kernel
+ Apply to the kernel tracer
+-u, --userspace
+ Apply to the user-space tracer
+
+--discard
+ Discard event when subbuffers are full (default)
+--overwrite
+ Flight recorder mode : overwrites events when subbuffers are full
+--subbuf-size
+ Subbuffer size in bytes (default: 4096, kernel default: 262144)
+--num-subbuf
+ Number of subbufers (default: 8, kernel default: 4)
+--switch-timer
+ Switch subbuffer timer interval in usec (default: 0)
+--read-timer
+ Read timer interval in usec (default: 200)
+.fi
+
+.IP
+
+.IP "\fBenable-event\fP NAME[,NAME2,...] [-k|-u] [OPTIONS]"
+.nf
+Enable tracing event
+
+A tracing event is always assigned to a channel. If \fB-c, --channel\fP is
+omitted, a default channel named '\fBchannel0\fP' is created and the event is
+added to it. For the user-space tracer, using \fB-a, --all\fP is the same as
+using the wildcard "*".
+
+If \fB-s, --session\fP is omitted, the session name is taken from the .lttngrc
+file.
+.fi
+
+.B OPTIONS:
+
+.nf
+-h, --help
+ Show summary of possible options and commands.
+--list-options
+ Simple listing of options
+-s, --session
+ Apply on session name
+-c, --channel
+ Apply on channel name
+-a, --all
+ Enable all tracepoints
+-k, --kernel
+ Apply for the kernel tracer
+-u, --userspace
+ Apply for the user-space tracer
+
+--tracepoint
+ Tracepoint event (default)
+ - userspace tracer supports wildcards at end of string. Don't forget to
+ quote to deal with bash expansion.
+ e.g.:
+ "*"
+ "app_component:na*"
+--loglevel
+ Tracepoint loglevel
+--probe [addr | symbol | symbol+offset]
+ Dynamic probe. Addr and offset can be octal (0NNN...), decimal (NNN...)
+ or hexadecimal (0xNNN...)
+--function [addr | symbol | symbol+offset]
+ Dynamic function entry/return probe. Addr and offset can be octal
+ (0NNN...), decimal (NNN...) or hexadecimal (0xNNN...)
+--syscall
+ System call event
+ Enabling syscalls tracing (kernel tracer), you will not be able to disable them
+ with disable-event. This is a known limitation. You can disable the entire
+ channel to do the trick.
+.fi
+
+.IP "\fBdisable-channel\fP NAME[,NAME2,...] [-k|-u] [OPTIONS]"
+.nf
+Disable tracing channel
+
+Disabling a channel makes all event(s) in that channel to stop tracing. You can
+enable it back by calling \fBlttng enable-channel NAME\fP again.
+
+If \fB-s, --session\fP is omitted, the session name is taken from the .lttngrc
+file.
+.fi
+
+.B OPTIONS:
+
+.nf
+-h, --help
+ Show summary of possible options and commands.
+--list-options
+ Simple listing of options
+-s, --session
+ Apply on session name
+-k, --kernel
+ Apply for the kernel tracer
+-u, --userspace
+ Apply for the user-space tracer
+.fi
+
+.IP "\fBdisable-event\fP NAME[,NAME2,...] [-k|-u] [OPTIONS]"
+.nf
+Disable tracing event
+
+The event, once disabled, can be re-enabled by calling \fBlttng enable-event
+NAME\fP again.
+
+If \fB-s, --session\fP is omitted, the session name is taken from the .lttngrc
+file.
+.fi
+
+.B OPTIONS:
+
+.nf
+-h, --help
+ Show summary of possible options and commands.
+--list-options
+ Simple listing of options
+-s, --session
+ Apply on session name
+-k, --kernel
+ Apply for the kernel tracer
+-u, --userspace
+ Apply for the user-space tracer
+.fi
+
+.IP "\fBlist\fP [-k|-u] [SESSION [SESSION_OPTIONS]]"
+.nf
+List tracing session informations.
+
+With no arguments, it will list available tracing session(s).
+
+With -k alone, it will list all available kernel events (except the system
+calls events).
+With -u alone, it will list all available user-space events from registered
+applications. Here is an example of 'lttng list -u':
+
+PID: 7448 - Name: /tmp/lttng-ust/tests/hello/.libs/lt-hello
+ ust_tests_hello:tptest_sighandler (type: tracepoint)
+ ust_tests_hello:tptest (type: tracepoint)
+
+You can now enable any event listed by using the name :
+\fBust_tests_hello:tptest\fP.
+.fi
+
+.B OPTIONS:
+
+.nf
+-h, --help
+ Show summary of possible options and commands.
+--list-options
+ Simple listing of options
+-k, --kernel
+ Select kernel domain (FIXME : apparition de la notion de "domain" ici)
+-u, --userspace
+ Select user-space domain.
+
+Session options:
+-c, --channel NAME
+ List details of a channel
+-d, --domain
+ List available domain(s)
+.fi
+
+.IP "\fBset-session\fP NAME"
+.nf
+Set current session name
+
+Will change the session name in the .lttngrc file.
+.fi
+
+.B OPTIONS:
+
+.nf
+-h, --help
+ Show summary of possible options and commands.
+--list-options
+ Simple listing of options
+.fi
+
+.IP
+
+.IP "\fBstart\fP [OPTIONS] [NAME]"
+.nf
+Start tracing
+
+It will start tracing for all tracers for a specific tracing session.
+
+If NAME is omitted, the session name is taken from the .lttngrc file.
+.fi
+
+.B OPTIONS:
+
+.nf
+-h, --help
+ Show summary of possible options and commands.
+--list-options
+ Simple listing of options
+.fi
+
+.IP
+
+.IP "\fBstop\fP [OPTIONS] [NAME]"
+.nf
+Stop tracing
+
+It will stop tracing for all tracers for a specific tracing session.
+
+If NAME is omitted, the session name is taken from the .lttngrc file.
+.fi
+
+.B OPTIONS:
+
+.nf
+-h, --help
+ Show summary of possible options and commands.
+--list-options
+ Simple listing of options
+.fi
+
+.IP
+
+.IP "\fBversion\fP"
+.nf
+Show version information
+.fi
+
+.B OPTIONS:
+
+.nf
+-h, --help
+ Show summary of possible options and commands.
+--list-options
+ Simple listing of options
+.fi
+
+.IP
+
+.IP "\fBview\fP [SESSION_NAME] [OPTIONS]"
+.nf
+View traces of a tracing session
+
+By default, the babeltrace viewer will be used for text viewing.
+
+The SESSION_NAME is an optional session name. If not specified, lttng will get
+it from the configuration file (.lttngrc).
+.fi
+
+.B OPTIONS:
+
+.nf
+-h, --help
+ Show this help
+--list-options
+ Simple listing of options
+-t, --trace-path PATH
+ Trace directory path for the viewer
+-e, --viewer CMD
+ Specify viewer and/or options to use
+ This will completely override the default viewers so
+ please make sure to specify the full command. The trace
+ directory path of the session will be appended at the end
+ to the arguments
+.fi
+
+.SH "ENVIRONMENT VARIABLES"
+
+.PP
+Note that all command line options override environment variables.
+.PP
+
+.PP
+.IP "LTTNG_SESSIOND_PATH_ENV"
+Allows to specify the full session daemon binary path to lttng command line
+tool. You can also use --sessiond-path option having the same effect.
+.SH "SEE ALSO"
+
+.PP
+babeltrace(1), lttng-ust(3), lttng-sessiond(8)
+.PP
+.SH "BUGS"
+
+.PP
+No show stopper bugs known yet at this stable version.
+
+If you encounter any issues or usability problem, please report it on our
+mailing list <lttng-dev@lists.lttng.org> to help improve this project.
+.SH "CREDITS"
+
+.PP
+lttng is distributed under the GNU public license version 2. See the file
+COPYING for details.
+.PP
+A Web site is available at http://lttng.org for more information on the LTTng
+project.
+.PP
+You can also find our git tree at http://git.lttng.org.
+.PP
+Mailing lists for support and development: <lttng-dev@lists.lttng.org>.
+.PP
+You can find us on IRC server irc.oftc.net (OFTC) in #lttng.
+.PP
+.SH "THANKS"
+
+.PP
+Thanks to Yannick Brosseau without whom this project would never have been so
+lean and mean! Also thanks to the Ericsson teams working on tracing which
+helped us greatly with detailled bug reports and unusual test cases.
+
+Thanks to our beloved packager Alexandre Montplaisir-Goncalves (Ubuntu and PPA
+maintainer) and Jon Bernard for our Debian packages.
+
+Special thanks to Michel Dagenais and the DORSAL laboratory at Polytechnique de
+Montreal for the LTTng journey.
+.pp
+.SH "AUTHORS"
+
+.PP
+lttng-tools was originally written by Mathieu Desnoyers, Julien Desfossez and
+David Goulet. More people have since contributed to it. It is currently
+maintained by David Goulet <dgoulet@efficios.com>.
+.PP
projects / lttng-tools.git / commitdiff
