contents/using-lttng/controlling-tracing/creating-destroying-tracing-sessions.md

   1 ---
   2 id: creating-destroying-tracing-sessions
   3 ---
   4
   5 Whatever you want to do with `lttng`, it has to happen inside a
   6 **tracing session**, created beforehand. A session, in general, is a
   7 per-user container of state. A tracing session is no different; it
   8 keeps a specific state of stuff like:
   9
  10   * session name
  11   * enabled/disabled channels with associated parameters
  12   * enabled/disabled events with associated log levels and filters
  13   * context information added to channels
  14   * tracing activity (started or stopped)
  15
  16 and more.
  17
  18 A single user may have many active tracing sessions. LTTng session
  19 daemons are the ultimate owners and managers of tracing sessions. For
  20 user space tracing, each user has its own session daemon. Since Linux
  21 kernel tracing requires root privileges, only `root`'s session daemon
  22 may enable and trace  kernel events. However, `lttng` has a `--group`
  23 option (which is passed to `lttng-sessiond` when starting it) to
  24 specify the name of a _tracing group_ which selected users may be part
  25 of to be allowed to communicate with `root`'s session daemon. By
  26 default, the tracing group name is `tracing`.
  27
  28 To create a tracing session, do:
  29
  30 <pre class="term">
  31 lttng create my-session
  32 </pre>
  33
  34 This creates a new tracing session named `my-session` and make it
  35 the current one. If you don't specify a name (running only
  36 `lttng create`), your tracing session is named `auto` followed by the
  37 current date and time. Traces
  38 are written in <code>~/lttng-traces/<em>session</em>-</code> followed
  39 by the tracing session's creation date/time by default, where
  40 <code><em>session</em></code> is the tracing session name. To save them
  41 at a different location, use the `--output` option:
  42
  43 <pre class="term">
  44 lttng create --output /tmp/some-directory my-session
  45 </pre>
  46
  47 You may create as many tracing sessions as you wish:
  48
  49 <pre class="term">
  50 lttng create other-session
  51 lttng create yet-another-session
  52 </pre>
  53
  54 You may view all existing tracing sessions using the `list` command:
  55
  56 <pre class="term">
  57 lttng list
  58 </pre>
  59
  60 The state of a _current tracing session_ is kept in `~/.lttngrc`. Each
  61 invocation of `lttng` reads this file to set its current tracing
  62 session name so that you don't have to specify a session name for each
  63 command. You could edit this file manually, but the preferred way to
  64 set the current tracing session is to use the `set-session` command:
  65
  66 <pre class="term">
  67 lttng set-session other-session
  68 </pre>
  69
  70 Most `lttng` commands accept a `--session` option to specify the name
  71 of the target tracing session.
  72
  73 Any existing tracing session may be destroyed using the `destroy`
  74 command:
  75
  76 <pre class="term">
  77 lttng destroy my-session
  78 </pre>
  79
  80 Providing no argument to `lttng destroy` destroys the current
  81 tracing session. Destroying a tracing session stops any tracing
  82 running within the latter. Destroying a tracing session frees resources
  83 acquired by the session daemon and tracer side, making sure to flush
  84 all trace data.
  85
  86 You can't do much with LTTng using only the `create`, `set-session`
  87 and `destroy` commands of `lttng`, but it is essential to know them in
  88 order to control LTTng tracing, which always happen within the scope of
  89 a tracing session.