From: David Goulet Date: Mon, 23 Jul 2012 13:42:13 +0000 (-0400) Subject: Fix and update content of doc/ directory X-Git-Url: http://git.efficios.com/?p=lttng-tools.git;a=commitdiff_plain;h=fa8f9c825308ce02d5409979895c104cf9b6364c Fix and update content of doc/ directory Add lttng-relayd.8 to the Makefile.am Create the proposals/ directory which contains pas and current proposals (RFC) for any features/changes in lttng-tools code tree. Add the streaming-howto.txt to the dist data. Rename and update old RFCs and move them to proposals/ directory. Incidently, remove the dev/ directory. Signed-off-by: David Goulet --- diff --git a/doc/Makefile.am b/doc/Makefile.am index 23d93ed70..954c67ab3 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,4 +1,4 @@ SUBDIRS = man -EXTRA_DIST = quickstart.txt session-daemon-model.txt +EXTRA_DIST = quickstart.txt streaming-howto.txt -dist_doc_DATA = quickstart.txt +dist_doc_DATA = quickstart.txt streaming-howto.txt diff --git a/doc/dev/lttng-cli.txt b/doc/dev/lttng-cli.txt deleted file mode 100644 index f8fa17263..000000000 --- a/doc/dev/lttng-cli.txt +++ /dev/null @@ -1,103 +0,0 @@ - -******** DEPRECATED ********** -* Kept for historic purposes * -******** DEPRECATED ********** - -lttng-tools command line interface - -(Note: as of June 8th, 2011, this document is at [RFC] stage.) - -This document describes the "lttng" command line interface. - -Authors: -David Goulet -Mathieu Desnoyers - -We plan to go for a git-alike UI: - - lttng command [options] - -Where command can be one of the following, and the options are -per-command: - -(note: in this description, options between [ ] are optional) - -* Basic options - - -v, --verbose # Verbose mode - -q, --quiet # Quiet mode - --help # Show help - --group NAME # Unix tracing group name. (default: tracing) - --no-sessiond # Don't spawn a session daemon - --sessiond-path # Session daemon full path - help/--help/-h # list LTTng commands - -* List interfaces: - -lttng list [--help] # show list options -lttng list --events # list all available instrumentation -lttng list --kernel # list kernel instrumentation -lttng list --pid n # list userspace app instrumentation by pid -lttng list command_name # list userspace app instrumentation by command -lttng list --app # list traceable user-space applications/pids -lttng list --sessions # list tracing sessions - -* Show version - -lttng version [--help] # show lttng-tools version and version options -lttng version --kernel # show kernel lttng version -lttng version --pid n # show kernel lttng version -lttng version command_name # show lttng versions for app by command - -* Tracing session control - -lttng create [--session] name # create a tracing session (default name provided) - [--output path] # optionally specify the output path - ----> This command prints - "Working directory of created session is /path/to/name. Change your" - "current working directory to interact with this session." - ----> All the following commands use the current working directory - .lttng/config file to keep track of the session on which actions - should be applied. - -lttng destroy [--session] name # teardown a tracing session -lttng start [--session] name # start tracing for a session -lttng stop [--session] name # stop tracing for a session - - -(note in manpage (warning) about --all and cmd_name: -"WARNING: this may noticeably slow down your system!") -lttng add-channel name --kernel [options] -lttng add-channel name --userspace [--all/--pid n/cmd_name] [options] - available options: - --discard (default) - --overwrite - --subbuf_size - --num_subbuf - --switch_timer_interval - --read_timer_interval - -lttng config --kernel --channel name -lttng config --channel name [--all/--pid n/cmd_name] - -(note: no channel name specified creates a "default" channel) -lttng add-event name --kernel [--channel name] -lttng add-event name --userspace [--channel name] [--all/--pid n/cmd_name] - available options, either: - --tracepoint (default) - --marker - --kprobe address - --function - (support list of names: name1,name2,name3... all with the same - options) -lttng enable-event name --kernel [--channel name] -lttng disable-event name --kernel [--channel name] -lttng enable-event name --userspace [--channel name] [--all/--pid n/cmd_name] -lttng disable-event name --userspace [--channel name] [--all/--pid n/cmd_name] - -lttng add-context name --kernel [--event name] [--channel name] --type context_type [context options] -lttng add-context name --userspace [--event name] [--channel name] [--all/--pid n/cmd_name] --type context_type [context options] - -lttng consume [PATH] --continue --snapshot --stop diff --git a/doc/man/Makefile.am b/doc/man/Makefile.am index 83a115dc0..d91a91a88 100644 --- a/doc/man/Makefile.am +++ b/doc/man/Makefile.am @@ -1,2 +1,2 @@ dist_man1_MANS = lttng.1 -dist_man8_MANS = lttng-sessiond.8 +dist_man8_MANS = lttng-sessiond.8 lttng-relayd.8 diff --git a/doc/proposals/0001-session-daemon-architecture.txt b/doc/proposals/0001-session-daemon-architecture.txt new file mode 100644 index 000000000..411d148d8 --- /dev/null +++ b/doc/proposals/0001-session-daemon-architecture.txt @@ -0,0 +1,513 @@ +RFC - LTTng session daemon architecture + +WARNING: + Parts of the proposal are obselete but we keep this version for historical + purposes. + +Author: David Goulet + +Contributors: + * Mathieu Desnoyers + * Yannick Brosseau + * Nils Carlson + * Michel Dagenais + * Stefan Hajnoczi + +Version: + - v0.1: 17/01/2011 + * Initial proposal + + - v0.2: 19/01/2011 + After multiple reply from all the contributors above, here is the list + of what has changed: + * Change/Add Terminology elements from the initial model + * New figures for four new scenarios + * Add inprocess library section + * LTTng kernel tracer support proposition + * More details for the Model and Components + * Improve the basic model. Quite different from the last one + + - v0.3: 28/01/2011 + In response from Michel Dagenais and Nils Carlson comments: + * Add scaling to reasons of this re-engineering + * Purpose of the session ID + * Explain why ltt-sessiond creates the tracing buffers + * ust-consumerd interaction schema + * Clarify inprocess library behavior + + - v0.4: 01/02/2011 + After Mathieu Desnoyers and Michel Dagenais comments: + * Add section Introduction + * Define the global and per-user ltt-sessiond + * Add details for ltt-sessiond in the inprocess lib section + * Session ID are now UUID + * Add buffer snapshot schema for ust-consumerd + * ltt-sessiond validate inprocess lib version + * ltt-sessiond socket validation by the inprocess lib. + * Add lttng definition + * Add consumer to the Model section + - v0.5: 23/07/2012 + * Please refer to the thesis of David Goulet for the complete + and up to date specifications of the architecture and algorithms used. + (http://publications.polymtl.ca/842/1/2012_DavidGoulet.pdf) + +Terminology +----------------- + +ltt-sessiond - Main daemon for trace session registry for UST and LTTng +NOTE: Changed to lttng-sessiond in the git tree + +ust-consumerd - Daemon that consume UST buffers for a specific application + +ltt-consumerd - Daemon that consume LTTng buffers + +tracing session - A trace linked to a set of specific tracepoints and to a set + of tracing buffers + +tracing buffers - Buffers containing tracing data + +tracing data - Data created by tracing an application + +inprocess library - UST library linked with the application + +shared memory - system V shared memory + +application common named pipe - Global named pipe that triggers application + registration, on pipe event, to ltt-sessiond + +lttng - New command line tool for LTTng and UST tracing control + +Introduction +----------------- + +This RFC propose a brand new UST and LTTng daemon model. This re-engineering +was mostly driven by the need of: + + * Better security in terms of access rights on tracing data + * Manage tracing session + * Scaling in terms of thread/processes needed to perform tracing + * LTTng and UST integration in terms of merging traces and session control + * Networking such as streaming and remote control over different traces + +The new model follows the basic principles of having a session registry +(ltt-sessiond) and consumers for each tracing session (ust-consumerd and +ltt-consumerd). + +With this proposal, LTTng and UST will share the same tracing session, be +managed by the same tool and bring a complete integration between these two +powerful tools. + +NOTE: This proposal does NOT makes UST dependent on LTTng and vice versa. + +Model +----------------- + +A global and/or per-user registry keeps track of all tracing sessions. Any user +that wants to manage either a kernel trace using LTTng or an application trace +with UST must interact with that registry for any possible actions. + +The model address multiple tracing use cases based on the fact that we +introduce a tracing Unix group (tracing group). Only users in that group or +root can use the global registry. Other users will create a local registry +(per-user registry) that will be completely independent from the global one. + +Two cases: + + 1) Users in the tracing group, it's tracing session can consume all tracing + buffers from all applications and the kernel. + + 2) Users NOT in the tracing group, it's tracing session can only consume + data from its own applications' buffers hence tracing his applications. + +A session stored by the registry consist of: + + * Session name (given by the user or automatically assigned) + * List of traces (LTTng or UST) + * Tracepoints/markers associated to a trace of that session + * UUID + * Associated user (UID) + +Then, consumers are used to extract data from tracing buffers. These consumers +are daemon consuming either UST or/and LTTng buffers. For a single session, +only one UST consumer and one LTTng consumer is necessary. The daemon CAN +handle multiple tracing buffers for network streaming by example or for quick +snapshot. These consumers are told by the inprocess library or the kernel to +start getting out data on disk or network. + +For the next subsections, every components of this new proposal is explained +from the global and per-user registry perspective. + +LTT-SESSIOND: + +The ltt-sessiond daemon acts as a session registry i.e. by keeping reference to +all active session and, by active, it means a session in any state other than +destroyed. Each entity we are keeping track of, here session, will have a +universal unique identifier (UUID) assigned to it. The purpose of this UUID is +to track a session in order to apply any kind of actions (Ex: Attach, Destroy). +A human readable version SHOULD be consider in order to facilitate the session +identification when listed by lttng. + +The daemon creates two local Unix sockets (AF_UNIX). The first one is for what +we call client communication i.e. interaction with lttng (or any other +compatible tools). That socket is set with the ltt-sessiond credentials with +read-write mode for both user and group. The second one is a global socket for +application registration for the UST case (see inprocess lib subsection below). + +This daemon is also responsible for tracing buffers creation. Two main reasons +motivate this design: + + * The ltt-sessiond needs to keep track of all the shared memory segments in + order to be able to give reference to any other possible consumer. + + * For the case of sharing tracing buffers between all userspace + applications, having the registry allocating them will allow that but, if + the inprocess library was allocating them, we will need to redesign the + whole model. + +For all tracing actions either to interact with a session or a specific trace, +the lttng client MUST go through ltt-sessiond. The daemon will take care of +routing the command to the write inprocess library or the kernel. + +Global registry: + +A global registry SHOULD be started, idealy at boot, with credentials UID root +and GID of the tracing group. Only user within the tracing group will be able +to interact with that registry. All applications will try to register to that +registry using the global socket (second one discuss above). + +Per-user registry: + +This type of registry address two use cases. The first one is when a session +creation is requested from lttng but no global ltt-sessiond exist. So, a +ltt-sessiond will be spawned in order to manage the tracing of that user. The +second use case is when a user is not in the tracing group thus he cannot +communication with the global registry. + +However, care MUST be put in order to manage the socket's daemon. They are not +global anymore so they should be created in the home directory of the user +requesting tracing. + +In both cases, for global and per-user registry, all applications MUST try to +register to both ltt-sessiond. (see inprocess library subsection for details) + +The trace roles of ltt-sessiond: + + Trace interaction - Create, Destroy, Pause, Stop, Start, Set options + + Registry - keep track of trace's information: + * shared memory location (only the keyid) + * application PID (UST) + * type (kernel or UST) + * session name + * UID + + Buffers creation - creates shared memory for the tracing buffers. + +UST-CONSUMERD: + +The purpose of this daemon is to consume the UST trace buffers for only a +specific session. The session MAY have several traces for example two different +applications. The client tool, lttng has to create the ust-consumerd if NONE +is available for that session. It is very important to understand that for a +tracing session, there is only one ust-consumerd for all the traced +applications. + +This daemon basically empty the tracing buffers when asked for and writes that +data to disk for future analysis using LTTv or/and TMF (Tracing Monitoring +Frameworks). The inprocess library is the one that tells the ust-consumerd +daemon that the buffers are ready for consumption. + +Here is a flow of action to illustrate the ust-consumerd life span: + +1) ++-----------+ ops +--------------+ +| lttng A |<---------->| ltt-sessiond | ++-----------+ +--------------+ + +lttng ask for tracing an application using the PID and the session UUID. The +shared memory reference is given to lttng and the ust-consumerd communication +socket if ust-consumerd already exist. + +2a) If ust-consumerd EXIST + ++-----------+ +| lttng A | ++-----------+ + | mem ref. + | +---------------+ read +------------+ + +-->| ust-consumerd |--------->| shared mem | + +---------------+ +------------+ + +In that case, lttng only ask ust-consumerd to consume the buffers using +the reference it previously got from ltt-sessiond. + +2b) If ust-consumerd DOES NOT EXIST + ++-----------+ +--------------+ +| lttng A | +---->| ltt-sessiond | ++-----------+ | +--------------+ + | ID | + | mem ref. | register + | +---------------+ + +-->| ust-consumerd | + +---------------+ + +lttng spawns the ust-consumerd for the session using the session UUID in +order for the daemon to register as a consumer to ltt-sessiond for that +session. + +Quick buffer snapshot: + +1) Here, lttng will request a buffer snapshot for an already running session. + ++-----------+ +--------------+ +| lttng A |-------- ops ------->| ltt-sessiond | ++-----------+ +--------------+ + | | command + | +-----------------+ +-------+<--+ + | | ust-consumerd 1 |<----| app_1 |-+ + | +-----------------+ +-------+ | write + | 1 | v + | | +-------------+ + | +--- read ----->| shared mem. | + | +-------------+ + | ^ + | +-----------------+ | + +->| ust-consumerd 2 |----------+ + +-----------------+ snapshot + | write + | + +---> disk/network + +The first ust-consumerd (1) was already consuming buffers for the current +session. So, lttng ask for a live snapshot. A new ust-consumerd (2) is +spawned, snapshot the buffers using the shared memory reference from +ltt-sessiond, writes date to disk and die after all. + +On the security side, the ust-consumerd gets UID/GID from the lttng +credentials since it was spawned by lttng and so the files containing the +tracing data will also be set to UID/GID of the lttng client. No setuid or +setgid is used, we only use the credentials of the user. + +The roles of ust-consumerd: + + Register to ltt-sessiond - Using a session UUID and credentials (UID/GID) + + Consume buffers - Write data to a file descriptor (on disk, network, ...) + +Buffer consumption is triggered by the inprocess library which tells +ust-consumerd when to consume. + +LTT-CONSUMERD: + +The purpose of this daemon is to consume the LTTng trace buffers for only a +specific session. + +For that kernel consumer, ltt-sessiond will pass different anonymous file +descriptors to the ltt-consumerd using a Unix socket. From these file +desriptors, it will be able to get the data from a special function export by +the LTTng kernel. + +ltt-consumerd will be managed by the exact same way as ust-consumerd. However, +in order to trace the kernel, you are either root (UID=0) or in the tracing +group. + +The roles of ltt-consumerd: + + Register to ltt-sessiond - Using a session UUID and credentials (UID/GID) + + Consume buffers - Write data to a file descriptor (on disk, network, ...) + +Kernel triggers ltt-consumerd for buffer consumption. + +UST INPROCESS LIBRARY: + +When the application starts, this library will check for the global named pipe +of ltt-sessiond. If present, it MUST validate that root is the owner. This +check is very important to prevent ltt-sessiond spoofing. If the pipe is root, +we are certain that it's the privileged user that operates tracing. Then, using +it's UID, the application will try to register to the per-user ltt-sessiond +again verifying before the owner ship of the named pipe that should match the +UID. + +Before registration, the inprocess library MUST validate with the ltt-sessiond +the library version for compatibility reason. This is mechanism is useful for +library compatibility but also to see if ltt-sessiond socket is valid (means +that an actual ltt-sessiond is listening on the other side). Having no response +for over 10 seconds, the application will cut communication on that socket and +fallback to the application common named pipe (explain below). + +If the socket is valid, it will register as a traceable application using the +apps credentials and will open a local Unix socket, passed to ltt-sessiond, in +order to receive an eventual shared memory reference. It will then wait on it +if any other command are given by the lttng client. This socket becomes the +only channel of communication between the registry and the application. + +If no ltt-sessiond is present at registration, the application tries to open +the application common named pipe or create it if it does not exist and wait on +it (using poll or epoll Linux API). Having any type of event on that pipe, the +inprocess library will then try to register to the global and per-user +ltt-sessiond. If it fails again, it goes back again to wait on that pipe. + +SHARED MEMORY + +For UST, this is the memory area where the tracing buffers will be held and +given access in read-write mode for the inprocess library of the application. + +On the LTTng side (for ltt-consumerd), these buffers are in the kernel space +and given access by opening a file in the debugfs file system. With an +anonymous file desriptor, this consumer will be able to extract the data. + +This memory is ONLY used for the tracing data. No communication between +components is done using that memory. + +A shared memory segment for tracing MUST be set with the tracing group GID for +the UST buffers. This is the job of ltt-sessiond. + +PREREQUISITES: + +The global ltt-sessiond daemon MUST always be running as "root" or an +equivalent user having the same privilege as root (UID = 0). + +The ltt-sessiond daemon SHOULD be up and running at all time in order to trace +a tracable application. + +The new lttng library API MUST be used to interact with the +ltt-sessiond registry daemon for every trace action needed by the user. + +A tracing group MUST be created. Whoever is in that group is able to access the +tracing data of any buffers and is able to trace any application or the kernel. + +WARNING: The tracing group name COULD interfere with other already existing +groups. Care should be put at install time for that (from source and packages) + +The next section illustrates different use cases using that new model. + +Use Cases +----------------- + +Each case considers these : + +* user A - UID: A; GID: A, tracing +* user B - UID: B; GID: B, tracing + +Scenario 1 - Single user tracing app_1 +------ + +This first scenario shows how user A will start a trace for application app_1 +that is not running. + +1) lttng ask ltt-sessiond for a new session through a Unix socket. If +allowed, ltt-sessiond returns a session UUID to the client. +(Ex: ops --> new session) + ++-----------+ ops +--------------+ +| lttng A |<---------->| ltt-sessiond | ++-----------+ +--------------+ + +2) The app_1 is spawned by lttng having the user A credentials. Then, app_1 +automatically register to ltt-sessiond has a "tracable apps" through the global +named pipe of ltt-sessiond using the UID/GID and session UUID. + +The shared memory is created with the app_1 UID (rw-) and tracing group GID +(r--) and a reference is given back to app_1 + ++-----------+ +--------------+ +| lttng A | | ltt-sessiond | ++-----------+ +--------------+ + | ^ | + | +-------+ | | +-------------+ + +-->| app_1 |<--------+ +-->| shared mem. | + +-------+ +-------------+ + +3) app_1 connect to the shared memory and ust-consumerd is spawned with the +session UUID and lttng credentials (user A). It then register to ltt-sessiond +for a valid session to consume using the previous session UUID and credentials. + ++-----------+ +--------------+ +| lttng A | +-->| ltt-sessiond |----------+ ++-----------+ | +--------------+ | + | | | + | +---------------+ read | commands + +-->| ust-consumerd |---------+ | and + +---------------+ v | options + ^ | +-------------+ | + | v +------>| shared mem. | | + +-------+ | +-------------+ | + | app_1 |-------- | + +-------+ write | + ^ | + +--------------------------------------- + +Scenario 2 - Single user tracing already running app_1 +------ + +1) lttng ask ltt-sessiond for a new session through a Unix socket. If allowed +(able to write on socket), ltt-sessiond returns a session UUID to the client. + ++-----------+ ops +--------------+ +| lttng A |<---------->| ltt-sessiond | ++-----------+ +--------------+ + ^ + +-------+ read | + | app_1 |----------+ + +-------+ + +NOTE: At this stage, since app_1 is already running, the registration of app_1 +to ltt-sessiond has already been done. However, the shared memory segment is +not allocated yet until a trace session is initiated. Having no shared memory, +the inprocess library of app_1 will wait on the local Unix socket connected to +ltt-sessiond for the reference. + ++-----------+ +--------------+ +| lttng A | | ltt-sessiond | ++-----------+ +--------------+ + ^ | + +-------+ | | +-------------+ + | app_1 |<--------+ +-->| shared mem. | + +-------+ commands +-------------+ + | ^ + +---------- write ----------+ + +2) lttng spawns a ust-consumerd for the session. We get the same figure as +step 3 in the first scenario. + +There is a small difference though. The application MAY NOT be using the same +credentials as user A (lttng). However, the shared memory is always GID of +the tracing group. So, in order for user A to trace app_1, is MUST be in the +tracing group otherwise, if the application is not set with the user +credentials, user A will not be able to trace app_1 + +Scenario 3 - Multiple users tracing the same running application +------ + +1) Session are created for the two users. Using the same exact mechanism as +before, the shared memory and consumers are created. Two users, two sessions, +two consumers and two shared memories for the same application. + ++-----------+ +--------------+ +| lttng A |-------- ops ------->| ltt-sessiond | ++-----------+ ^ +--------------+ + | ^ commands ++-----------+ | +-------+<--+ +| lttng B |------+ +--->| app_1 |------- write -----+ ++-----------+ | +-------+ | + | | + +-----------------+ | +-------------+ | + | ust-consumerd A |--O--- read ----->| shared mem. |<-+ + +-----------------+ | +-------------+ | + | | + +-----------------+ v +-------------+ | + | ust-consumerd B |--+--- read ----->| shared mem. |<-+ + +-----------------+ +-------------+ + +ust-consumerd A - UID: user A (rw-), GID: tracing (r--) +ust-consumerd B - UID: user B (rw-), GID: tracing (r--) + +Scenario 4 - User not in the tracing group +------ + +For this particular case, it's all goes back to the first scenario. The user +MUST start the application using his credentials. The session will be created +by the per-user ltt-sessiond but he will not be able to trace anything that the +user does not owned. diff --git a/doc/proposals/0002-lttng-command-line-UI.txt b/doc/proposals/0002-lttng-command-line-UI.txt new file mode 100644 index 000000000..2c83b769a --- /dev/null +++ b/doc/proposals/0002-lttng-command-line-UI.txt @@ -0,0 +1,103 @@ + +******** DEPRECATED ************ +* Kept for historical purposes * +******** DEPRECATED ************ + +lttng-tools command line interface + +(Note: as of June 8th, 2011, this document is at [RFC] stage.) + +This document describes the "lttng" command line interface. + +Authors: +David Goulet +Mathieu Desnoyers + +We plan to go for a git-alike UI: + + lttng command [options] + +Where command can be one of the following, and the options are +per-command: + +(note: in this description, options between [ ] are optional) + +* Basic options + + -v, --verbose # Verbose mode + -q, --quiet # Quiet mode + --help # Show help + --group NAME # Unix tracing group name. (default: tracing) + --no-sessiond # Don't spawn a session daemon + --sessiond-path # Session daemon full path + help/--help/-h # list LTTng commands + +* List interfaces: + +lttng list [--help] # show list options +lttng list --events # list all available instrumentation +lttng list --kernel # list kernel instrumentation +lttng list --pid n # list userspace app instrumentation by pid +lttng list command_name # list userspace app instrumentation by command +lttng list --app # list traceable user-space applications/pids +lttng list --sessions # list tracing sessions + +* Show version + +lttng version [--help] # show lttng-tools version and version options +lttng version --kernel # show kernel lttng version +lttng version --pid n # show kernel lttng version +lttng version command_name # show lttng versions for app by command + +* Tracing session control + +lttng create [--session] name # create a tracing session (default name provided) + [--output path] # optionally specify the output path + +---> This command prints + "Working directory of created session is /path/to/name. Change your" + "current working directory to interact with this session." + +---> All the following commands use the current working directory + .lttng/config file to keep track of the session on which actions + should be applied. + +lttng destroy [--session] name # teardown a tracing session +lttng start [--session] name # start tracing for a session +lttng stop [--session] name # stop tracing for a session + + +(note in manpage (warning) about --all and cmd_name: +"WARNING: this may noticeably slow down your system!") +lttng add-channel name --kernel [options] +lttng add-channel name --userspace [--all/--pid n/cmd_name] [options] + available options: + --discard (default) + --overwrite + --subbuf_size + --num_subbuf + --switch_timer_interval + --read_timer_interval + +lttng config --kernel --channel name +lttng config --channel name [--all/--pid n/cmd_name] + +(note: no channel name specified creates a "default" channel) +lttng add-event name --kernel [--channel name] +lttng add-event name --userspace [--channel name] [--all/--pid n/cmd_name] + available options, either: + --tracepoint (default) + --marker + --kprobe address + --function + (support list of names: name1,name2,name3... all with the same + options) +lttng enable-event name --kernel [--channel name] +lttng disable-event name --kernel [--channel name] +lttng enable-event name --userspace [--channel name] [--all/--pid n/cmd_name] +lttng disable-event name --userspace [--channel name] [--all/--pid n/cmd_name] + +lttng add-context name --kernel [--event name] [--channel name] --type context_type [context options] +lttng add-context name --userspace [--event name] [--channel name] [--all/--pid n/cmd_name] --type context_type [context options] + +lttng consume [PATH] --continue --snapshot --stop diff --git a/doc/proposals/0003-network.consumer.txt b/doc/proposals/0003-network.consumer.txt new file mode 100644 index 000000000..a832d18db --- /dev/null +++ b/doc/proposals/0003-network.consumer.txt @@ -0,0 +1,202 @@ +RFC - Network consumer + +Author: David Goulet + +Contributors: + * Mathieu Desnoyers + * Julien Desfossez + +Version: + - v0.1: 16/04/2012 + * Initial proposal + - v0.2: 04/05/2012 + * Add snapshot description + * Propose a new API and lttng cli command + - v0.3: 23/07/2012 + * Remove snapshot and focus only on network consumer for straming. + +Introduction +----------------- + +This RFC proposes a way for the lttng 2.0 session daemon to handle network +session for streaming purposes and eventually remote control. + +The next sections introduce the concept of network session and how it is +envisioned in the lttng 2.0 toolchain. + +Please note that this RFC is neither final nor complete without the community +feedbacks. The text below is a proposal. + +Network consumer +----------------- + +For version 2.1 of lttngt-tools, we propose to add a network consumer which will +be used for streaming. + +We allow to pass a full URI to the enable consumer command to override the +current consumer or define a new one. + +We should at least support the following protocols: + +* net://HOST[:PORT_CTRL[:PORT_DATA]] +* tcp://HOST:PORT +* tcp6://HOST:PORT +* udp://HOST:PORT +* udp6://HOST:PORT +* file:// + +The net:// URI scheme makes the control and data stream use the default +transport protocol which is TCP. The same remote host is also +used for both. The ports can be specified and if not the defaults are used which +are 5342 for control and 5343 for data. + +If URI not recognized, we use the arguments as a file name (same behavior as +using file:///). + +The control and data stream are two separate arguments of the API since we allow +the user to control the protocol and path (address). However, for a transfer to +succeed, the lttng-sessiond and the remote end must establish a session for the +control _and_ data path. If one fails to do so, the procedure is aborted. Thus, +a different address for the control path from the data path is allowed but the +user has to make sure that both communication channels end up at the same +physical destination. + +Note that the control path is a crucial and high priority channel of +communication so for now we only allow it to use the TCP protocol. + +Session with Network Transport +----------------- + +In order to tell the session daemon where to send the data for streaming, a +tracing session has to be aware of some information of the remote target. + + * Remote end network address (Ex: IP or Hostname) + * Destination control port + * Destination data port + +Streaming can be initiated by telling the session daemon that a specific session +is set for network streaming. This will make the session daemon establish a +connection with the remote end. Once tracing starts, the local consumer will be +made aware of this information and will start sending data following a strict +protocol defined in the streaming RFC written by Julien Desfossez. + +Finally, a trace received by a network consumer will have a new "namespace" +prepended to the trace output directory hierarchy: the hostname from _where_ the +trace is coming from. + +host01 +\-- my_session1 + \-- ust + \-- my_app1[...] + \-- trace data... + \-- kernel + \-- trace data... + +Client API integration +----------------- + +Adding an API call to set attributes such as network information to a session. +Since lttng_create_session only takes a name and a path, a new call is required +to pass this information. The naming convention is NOT final and can be +improved. + +struct lttng_handle handle; + +enum lttng_dst_type { + LTTNG_DST_IPV4, + LTTNG_DST_IPV6, + LTTNG_DST_HOST, + LTTNG_DST_PATH, +}; + +enum lttng_uri_type { + LTTNG_URI_HOP, + LTTNG_URI_DST, +}; + +enum lttng_stream_type { + LTTNG_STREAM_CONTROL, + LTTNG_STREAM_DATA +}; + +enum lttng_proto_type { + LTTNG_UDP, + LTTNG_TCP, +}; + +#define LTTNG_NETWORK_PADDING1_LEN 32 +#define LTTNG_NETWORK_PADDING2_LEN 128 +struct lttng_uri { + enum lttng_dst_type dtype; + enum lttng_uri_type utype; + enum lttng_stream_type stype; + enum lttng_proto proto; + in_port_t port; + char padding[LTTNG_NETWORK_PADDING1_LEN]; + char subdir[PATH_MAX]; + union { + char ipv4[INET_ADDRSTRLEN]; + char ipv6[INET6_ADDRSTRLEN]; + char path[PATH_NAME]; + char padding[LTTNG_NETWORK_PADDING2_LEN]; + } dst; +}; + +/* Set URI in the consumer template*/ +lttng_set_consumer_uri(handle, struct lttng_uri *u); + + +/* + * Enable consumer template for the session. Once enabled, no more URI setting + * are possible for that specific consumer. + */ +lttng_enable_consumer(handle); + +/* + * Disable the consumer means that the consumer will stop consuming but will + * still be exist. Executing the enable_consumer call again will simply re + * enable it. + */ +lttng_disable_consumer(handle); + +If lttng_set_consumer_uri is executed on a session which already has a network +consumer attached to it, the present consumer is freed and a new template is +added. + +We propose to add two commands to the lttng command line actions: + +i) lttng enable-consumer [URI] [OPTIONS] + -s SESSION_NAME + -C, --control-uri=[HOP1,]URI + -D, --data-uri=[HOP1,]URI + +ii) lttng disable-consumer + -s SESSION_NAME + +Each option defining URI(s) can contains a list of hops preceeding the final +destination. However, the proxy feature is still not supported but we prefer to +inform the community of is future existence. + +So, the regular chain of command to enable a network consumer would be: + +# lttng create session1 +// The command sets the destination but uses the default protocols and ports. +# lttng enable-consumer net://192.168.1.10 +# lttng enable-event -a -k +# lttng start +(tracing...) +# lttng stop + +(This example considers that there is a lttng-relayd on the remote end.) + +Session daemon integration +----------------- + +As mentioned earlier, the session daemon will be in charge of establishing a +streaming session with the target over the network i.e. creating the control and +data path bidirectional socket. Once done, a network consumer is spawned and +those sockets are passed over. + +From there, the session daemon can interact with the consumer by stopping the +network streaming or re-establishing a local trace collection with a non network +consumer. diff --git a/doc/session-daemon-model.txt b/doc/session-daemon-model.txt deleted file mode 100644 index da42e276d..000000000 --- a/doc/session-daemon-model.txt +++ /dev/null @@ -1,505 +0,0 @@ -RFC - New processes model for UST and LTTng - -Author: David Goulet - -Contributors: - * Mathieu Desnoyers - * Yannick Brosseau - * Nils Carlson - * Michel Dagenais - * Stefan Hajnoczi - -Version: - - v0.1: 17/01/2011 - * Initial proposal - - - v0.2: 19/01/2011 - After multiple reply from all the contributors above, here is the list - of what has changed: - * Change/Add Terminology elements from the initial model - * New figures for four new scenarios - * Add inprocess library section - * LTTng kernel tracer support proposition - * More details for the Model and Components - * Improve the basic model. Quite different from the last one - - - v0.3: 28/01/2011 - In response from Michel Dagenais and Nils Carlson comments: - * Add scaling to reasons of this re-engineering - * Purpose of the session ID - * Explain why ltt-sessiond creates the tracing buffers - * ust-consumerd interaction schema - * Clarify inprocess library behavior - - - v0.4: 01/02/2011 - After Mathieu Desnoyers and Michel Dagenais comments: - * Add section Introduction - * Define the global and per-user ltt-sessiond - * Add details for ltt-sessiond in the inprocess lib section - * Session ID are now UUID - * Add buffer snapshot schema for ust-consumerd - * ltt-sessiond validate inprocess lib version - * ltt-sessiond socket validation by the inprocess lib. - * Add lttng definition - * Add consumer to the Model section - -Terminology ------------------ - -ltt-sessiond - Main daemon for trace session registry for UST and LTTng -NOTE: Changed to lttng-sessiond in the git tree - -ust-consumerd - Daemon that consume UST buffers for a specific application - -ltt-consumerd - Daemon that consume LTTng buffers - -tracing session - A trace linked to a set of specific tracepoints and to a set - of tracing buffers - -tracing buffers - Buffers containing tracing data - -tracing data - Data created by tracing an application - -inprocess library - UST library linked with the application - -shared memory - system V shared memory - -application common named pipe - Global named pipe that triggers application - registration, on pipe event, to ltt-sessiond - -lttng - New command line tool for LTTng and UST tracing control - -Introduction ------------------ - -This RFC propose a brand new UST and LTTng daemon model. This re-engineering -was mostly driven by the need of: - - * Better security in terms of access rights on tracing data - * Manage tracing session - * Scaling in terms of thread/processes needed to perform tracing - * LTTng and UST integration in terms of merging traces and session control - * Networking such as streaming and remote control over different traces - -The new model follows the basic principles of having a session registry -(ltt-sessiond) and consumers for each tracing session (ust-consumerd and -ltt-consumerd). - -With this proposal, LTTng and UST will share the same tracing session, be -managed by the same tool and bring a complete integration between these two -powerful tools. - -NOTE: This proposal does NOT makes UST dependent on LTTng and vice versa. - -Model ------------------ - -A global and/or per-user registry keeps track of all tracing sessions. Any user -that wants to manage either a kernel trace using LTTng or an application trace -with UST must interact with that registry for any possible actions. - -The model address multiple tracing use cases based on the fact that we -introduce a tracing Unix group (tracing group). Only users in that group or -root can use the global registry. Other users will create a local registry -(per-user registry) that will be completely independent from the global one. - -Two cases: - - 1) Users in the tracing group, it's tracing session can consume all tracing - buffers from all applications and the kernel. - - 2) Users NOT in the tracing group, it's tracing session can only consume - data from its own applications' buffers hence tracing his applications. - -A session stored by the registry consist of: - - * Session name (given by the user or automatically assigned) - * List of traces (LTTng or UST) - * Tracepoints/markers associated to a trace of that session - * UUID - * Associated user (UID) - -Then, consumers are used to extract data from tracing buffers. These consumers -are daemon consuming either UST or/and LTTng buffers. For a single session, -only one UST consumer and one LTTng consumer is necessary. The daemon CAN -handle multiple tracing buffers for network streaming by example or for quick -snapshot. These consumers are told by the inprocess library or the kernel to -start getting out data on disk or network. - -For the next subsections, every components of this new proposal is explained -from the global and per-user registry perspective. - -LTT-SESSIOND: - -The ltt-sessiond daemon acts as a session registry i.e. by keeping reference to -all active session and, by active, it means a session in any state other than -destroyed. Each entity we are keeping track of, here session, will have a -universal unique identifier (UUID) assigned to it. The purpose of this UUID is -to track a session in order to apply any kind of actions (Ex: Attach, Destroy). -A human readable version SHOULD be consider in order to facilitate the session -identification when listed by lttng. - -The daemon creates two local Unix sockets (AF_UNIX). The first one is for what -we call client communication i.e. interaction with lttng (or any other -compatible tools). That socket is set with the ltt-sessiond credentials with -read-write mode for both user and group. The second one is a global socket for -application registration for the UST case (see inprocess lib subsection below). - -This daemon is also responsible for tracing buffers creation. Two main reasons -motivate this design: - - * The ltt-sessiond needs to keep track of all the shared memory segments in - order to be able to give reference to any other possible consumer. - - * For the case of sharing tracing buffers between all userspace - applications, having the registry allocating them will allow that but, if - the inprocess library was allocating them, we will need to redesign the - whole model. - -For all tracing actions either to interact with a session or a specific trace, -the lttng client MUST go through ltt-sessiond. The daemon will take care of -routing the command to the write inprocess library or the kernel. - -Global registry: - -A global registry SHOULD be started, idealy at boot, with credentials UID root -and GID of the tracing group. Only user within the tracing group will be able -to interact with that registry. All applications will try to register to that -registry using the global socket (second one discuss above). - -Per-user registry: - -This type of registry address two use cases. The first one is when a session -creation is requested from lttng but no global ltt-sessiond exist. So, a -ltt-sessiond will be spawned in order to manage the tracing of that user. The -second use case is when a user is not in the tracing group thus he cannot -communication with the global registry. - -However, care MUST be put in order to manage the socket's daemon. They are not -global anymore so they should be created in the home directory of the user -requesting tracing. - -In both cases, for global and per-user registry, all applications MUST try to -register to both ltt-sessiond. (see inprocess library subsection for details) - -The trace roles of ltt-sessiond: - - Trace interaction - Create, Destroy, Pause, Stop, Start, Set options - - Registry - keep track of trace's information: - * shared memory location (only the keyid) - * application PID (UST) - * type (kernel or UST) - * session name - * UID - - Buffers creation - creates shared memory for the tracing buffers. - -UST-CONSUMERD: - -The purpose of this daemon is to consume the UST trace buffers for only a -specific session. The session MAY have several traces for example two different -applications. The client tool, lttng has to create the ust-consumerd if NONE -is available for that session. It is very important to understand that for a -tracing session, there is only one ust-consumerd for all the traced -applications. - -This daemon basically empty the tracing buffers when asked for and writes that -data to disk for future analysis using LTTv or/and TMF (Tracing Monitoring -Frameworks). The inprocess library is the one that tells the ust-consumerd -daemon that the buffers are ready for consumption. - -Here is a flow of action to illustrate the ust-consumerd life span: - -1) -+-----------+ ops +--------------+ -| lttng A |<---------->| ltt-sessiond | -+-----------+ +--------------+ - -lttng ask for tracing an application using the PID and the session UUID. The -shared memory reference is given to lttng and the ust-consumerd communication -socket if ust-consumerd already exist. - -2a) If ust-consumerd EXIST - -+-----------+ -| lttng A | -+-----------+ - | mem ref. - | +---------------+ read +------------+ - +-->| ust-consumerd |--------->| shared mem | - +---------------+ +------------+ - -In that case, lttng only ask ust-consumerd to consume the buffers using -the reference it previously got from ltt-sessiond. - -2b) If ust-consumerd DOES NOT EXIST - -+-----------+ +--------------+ -| lttng A | +---->| ltt-sessiond | -+-----------+ | +--------------+ - | ID | - | mem ref. | register - | +---------------+ - +-->| ust-consumerd | - +---------------+ - -lttng spawns the ust-consumerd for the session using the session UUID in -order for the daemon to register as a consumer to ltt-sessiond for that -session. - -Quick buffer snapshot: - -1) Here, lttng will request a buffer snapshot for an already running session. - -+-----------+ +--------------+ -| lttng A |-------- ops ------->| ltt-sessiond | -+-----------+ +--------------+ - | | command - | +-----------------+ +-------+<--+ - | | ust-consumerd 1 |<----| app_1 |-+ - | +-----------------+ +-------+ | write - | 1 | v - | | +-------------+ - | +--- read ----->| shared mem. | - | +-------------+ - | ^ - | +-----------------+ | - +->| ust-consumerd 2 |----------+ - +-----------------+ snapshot - | write - | - +---> disk/network - -The first ust-consumerd (1) was already consuming buffers for the current -session. So, lttng ask for a live snapshot. A new ust-consumerd (2) is -spawned, snapshot the buffers using the shared memory reference from -ltt-sessiond, writes date to disk and die after all. - -On the security side, the ust-consumerd gets UID/GID from the lttng -credentials since it was spawned by lttng and so the files containing the -tracing data will also be set to UID/GID of the lttng client. No setuid or -setgid is used, we only use the credentials of the user. - -The roles of ust-consumerd: - - Register to ltt-sessiond - Using a session UUID and credentials (UID/GID) - - Consume buffers - Write data to a file descriptor (on disk, network, ...) - -Buffer consumption is triggered by the inprocess library which tells -ust-consumerd when to consume. - -LTT-CONSUMERD: - -The purpose of this daemon is to consume the LTTng trace buffers for only a -specific session. - -For that kernel consumer, ltt-sessiond will pass different anonymous file -descriptors to the ltt-consumerd using a Unix socket. From these file -desriptors, it will be able to get the data from a special function export by -the LTTng kernel. - -ltt-consumerd will be managed by the exact same way as ust-consumerd. However, -in order to trace the kernel, you are either root (UID=0) or in the tracing -group. - -The roles of ltt-consumerd: - - Register to ltt-sessiond - Using a session UUID and credentials (UID/GID) - - Consume buffers - Write data to a file descriptor (on disk, network, ...) - -Kernel triggers ltt-consumerd for buffer consumption. - -UST INPROCESS LIBRARY: - -When the application starts, this library will check for the global named pipe -of ltt-sessiond. If present, it MUST validate that root is the owner. This -check is very important to prevent ltt-sessiond spoofing. If the pipe is root, -we are certain that it's the privileged user that operates tracing. Then, using -it's UID, the application will try to register to the per-user ltt-sessiond -again verifying before the owner ship of the named pipe that should match the -UID. - -Before registration, the inprocess library MUST validate with the ltt-sessiond -the library version for compatibility reason. This is mechanism is useful for -library compatibility but also to see if ltt-sessiond socket is valid (means -that an actual ltt-sessiond is listening on the other side). Having no response -for over 10 seconds, the application will cut communication on that socket and -fallback to the application common named pipe (explain below). - -If the socket is valid, it will register as a traceable application using the -apps credentials and will open a local Unix socket, passed to ltt-sessiond, in -order to receive an eventual shared memory reference. It will then wait on it -if any other command are given by the lttng client. This socket becomes the -only channel of communication between the registry and the application. - -If no ltt-sessiond is present at registration, the application tries to open -the application common named pipe or create it if it does not exist and wait on -it (using poll or epoll Linux API). Having any type of event on that pipe, the -inprocess library will then try to register to the global and per-user -ltt-sessiond. If it fails again, it goes back again to wait on that pipe. - -SHARED MEMORY - -For UST, this is the memory area where the tracing buffers will be held and -given access in read-write mode for the inprocess library of the application. - -On the LTTng side (for ltt-consumerd), these buffers are in the kernel space -and given access by opening a file in the debugfs file system. With an -anonymous file desriptor, this consumer will be able to extract the data. - -This memory is ONLY used for the tracing data. No communication between -components is done using that memory. - -A shared memory segment for tracing MUST be set with the tracing group GID for -the UST buffers. This is the job of ltt-sessiond. - -PREREQUISITES: - -The global ltt-sessiond daemon MUST always be running as "root" or an -equivalent user having the same privilege as root (UID = 0). - -The ltt-sessiond daemon SHOULD be up and running at all time in order to trace -a tracable application. - -The new lttng library API MUST be used to interact with the -ltt-sessiond registry daemon for every trace action needed by the user. - -A tracing group MUST be created. Whoever is in that group is able to access the -tracing data of any buffers and is able to trace any application or the kernel. - -WARNING: The tracing group name COULD interfere with other already existing -groups. Care should be put at install time for that (from source and packages) - -The next section illustrates different use cases using that new model. - -Use Cases ------------------ - -Each case considers these : - -* user A - UID: A; GID: A, tracing -* user B - UID: B; GID: B, tracing - -Scenario 1 - Single user tracing app_1 ------- - -This first scenario shows how user A will start a trace for application app_1 -that is not running. - -1) lttng ask ltt-sessiond for a new session through a Unix socket. If -allowed, ltt-sessiond returns a session UUID to the client. -(Ex: ops --> new session) - -+-----------+ ops +--------------+ -| lttng A |<---------->| ltt-sessiond | -+-----------+ +--------------+ - -2) The app_1 is spawned by lttng having the user A credentials. Then, app_1 -automatically register to ltt-sessiond has a "tracable apps" through the global -named pipe of ltt-sessiond using the UID/GID and session UUID. - -The shared memory is created with the app_1 UID (rw-) and tracing group GID -(r--) and a reference is given back to app_1 - -+-----------+ +--------------+ -| lttng A | | ltt-sessiond | -+-----------+ +--------------+ - | ^ | - | +-------+ | | +-------------+ - +-->| app_1 |<--------+ +-->| shared mem. | - +-------+ +-------------+ - -3) app_1 connect to the shared memory and ust-consumerd is spawned with the -session UUID and lttng credentials (user A). It then register to ltt-sessiond -for a valid session to consume using the previous session UUID and credentials. - -+-----------+ +--------------+ -| lttng A | +-->| ltt-sessiond |----------+ -+-----------+ | +--------------+ | - | | | - | +---------------+ read | commands - +-->| ust-consumerd |---------+ | and - +---------------+ v | options - ^ | +-------------+ | - | v +------>| shared mem. | | - +-------+ | +-------------+ | - | app_1 |-------- | - +-------+ write | - ^ | - +--------------------------------------- - -Scenario 2 - Single user tracing already running app_1 ------- - -1) lttng ask ltt-sessiond for a new session through a Unix socket. If allowed -(able to write on socket), ltt-sessiond returns a session UUID to the client. - -+-----------+ ops +--------------+ -| lttng A |<---------->| ltt-sessiond | -+-----------+ +--------------+ - ^ - +-------+ read | - | app_1 |----------+ - +-------+ - -NOTE: At this stage, since app_1 is already running, the registration of app_1 -to ltt-sessiond has already been done. However, the shared memory segment is -not allocated yet until a trace session is initiated. Having no shared memory, -the inprocess library of app_1 will wait on the local Unix socket connected to -ltt-sessiond for the reference. - -+-----------+ +--------------+ -| lttng A | | ltt-sessiond | -+-----------+ +--------------+ - ^ | - +-------+ | | +-------------+ - | app_1 |<--------+ +-->| shared mem. | - +-------+ commands +-------------+ - | ^ - +---------- write ----------+ - -2) lttng spawns a ust-consumerd for the session. We get the same figure as -step 3 in the first scenario. - -There is a small difference though. The application MAY NOT be using the same -credentials as user A (lttng). However, the shared memory is always GID of -the tracing group. So, in order for user A to trace app_1, is MUST be in the -tracing group otherwise, if the application is not set with the user -credentials, user A will not be able to trace app_1 - -Scenario 3 - Multiple users tracing the same running application ------- - -1) Session are created for the two users. Using the same exact mechanism as -before, the shared memory and consumers are created. Two users, two sessions, -two consumers and two shared memories for the same application. - -+-----------+ +--------------+ -| lttng A |-------- ops ------->| ltt-sessiond | -+-----------+ ^ +--------------+ - | ^ commands -+-----------+ | +-------+<--+ -| lttng B |------+ +--->| app_1 |------- write -----+ -+-----------+ | +-------+ | - | | - +-----------------+ | +-------------+ | - | ust-consumerd A |--O--- read ----->| shared mem. |<-+ - +-----------------+ | +-------------+ | - | | - +-----------------+ v +-------------+ | - | ust-consumerd B |--+--- read ----->| shared mem. |<-+ - +-----------------+ +-------------+ - -ust-consumerd A - UID: user A (rw-), GID: tracing (r--) -ust-consumerd B - UID: user B (rw-), GID: tracing (r--) - -Scenario 4 - User not in the tracing group ------- - -For this particular case, it's all goes back to the first scenario. The user -MUST start the application using his credentials. The session will be created -by the per-user ltt-sessiond but he will not be able to trace anything that the -user does not owned.