Fix and update content of doc/ directory
authorDavid Goulet <dgoulet@efficios.com>
Mon, 23 Jul 2012 13:42:13 +0000 (09:42 -0400)
committerDavid Goulet <dgoulet@efficios.com>
Mon, 23 Jul 2012 13:42:13 +0000 (09:42 -0400)
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 <dgoulet@efficios.com>
doc/Makefile.am
doc/dev/lttng-cli.txt [deleted file]
doc/man/Makefile.am
doc/proposals/0001-session-daemon-architecture.txt [new file with mode: 0644]
doc/proposals/0002-lttng-command-line-UI.txt [new file with mode: 0644]
doc/proposals/0003-network.consumer.txt [new file with mode: 0644]
doc/session-daemon-model.txt [deleted file]

index 23d93ed70b9724307cbec8b52b77777e4354dfbb..954c67ab314c4011ef37d80fc9525a7e254f3757 100644 (file)
@@ -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 (file)
index f8fa172..0000000
+++ /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 <david.goulet@polymtl.ca>
-Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
-
-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
index 83a115dc0ebd1240c6be9b605b2be696f5e3003d..d91a91a8822675664c865b8a5ab9a64225d530bd 100644 (file)
@@ -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 (file)
index 0000000..411d148
--- /dev/null
@@ -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 <david.goulet@polymtl.ca>
+
+Contributors:
+    * Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
+    * Yannick Brosseau <yannick.brosseau@polymtl.ca>
+    * Nils Carlson <nils.carlson@ericsson.com>
+    * Michel Dagenais <michel.dagenais@polymtl.ca>
+    * Stefan Hajnoczi <stefanha@gmail.com>
+
+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 (file)
index 0000000..2c83b76
--- /dev/null
@@ -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 <david.goulet@polymtl.ca>
+Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
+
+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 (file)
index 0000000..a832d18
--- /dev/null
@@ -0,0 +1,202 @@
+RFC - Network consumer
+
+Author: David Goulet <david.goulet@efficios.com>
+
+Contributors:
+    * Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
+    * Julien Desfossez <julien.desfossez@efficios.com>
+
+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 (file)
index da42e27..0000000
+++ /dev/null
@@ -1,505 +0,0 @@
-RFC - New processes model for UST and LTTng
-
-Author: David Goulet <david.goulet@polymtl.ca>
-
-Contributors:
-    * Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
-    * Yannick Brosseau <yannick.brosseau@polymtl.ca>
-    * Nils Carlson <nils.carlson@ericsson.com>
-    * Michel Dagenais <michel.dagenais@polymtl.ca>
-    * Stefan Hajnoczi <stefanha@gmail.com>
-
-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.
This page took 0.059967 seconds and 4 git commands to generate.