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 will create a new tracing session named `my-session` and make it
  35 the current one. If you don't specify any name (calling only
  36 `lttng create`), your tracing session will be named `auto`. Traces
  37 are written in <code>~/lttng-traces/<em>session</em>-</code> followed
  38 by the tracing session's creation date/time by default, where
  39 <code><em>session</em></code> is the tracing session name. To save them
  40 at a different location, use the `--output` option:
  41
  42 <pre class="term">
  43 lttng create --output /tmp/some-directory my-session
  44 </pre>
  45
  46 You may create as many tracing sessions as you wish:
  47
  48 <pre class="term">
  49 lttng create other-session
  50 lttng create yet-another-session
  51 </pre>
  52
  53 You may view all existing tracing sessions using the `list` command:
  54
  55 <pre class="term">
  56 lttng list
  57 </pre>
  58
  59 The state of a _current tracing session_ is kept in `~/.lttngrc`. Each
  60 invocation of `lttng` reads this file to set its current tracing
  61 session name so that you don't have to specify a session name for each
  62 command. You could edit this file manually, but the preferred way to
  63 set the current tracing session is to use the `set-session` command:
  64
  65 <pre class="term">
  66 lttng set-session other-session
  67 </pre>
  68
  69 Most `lttng` commands accept a `--session` option to specify the name
  70 of the target tracing session.
  71
  72 Any existing tracing session may be destroyed using the `destroy`
  73 command:
  74
  75 <pre class="term">
  76 lttng destroy my-session
  77 </pre>
  78
  79 Providing no argument to `lttng destroy` will destroy the current
  80 tracing session. Destroying a tracing session will stop any tracing
  81 running within the latter. Destroying a tracing session frees resources
  82 acquired by the session daemon and tracer side, making sure to flush
  83 all trace data.
  84
  85 You can't do much with LTTng using only the `create`, `set-session`
  86 and `destroy` commands of `lttng`, but it is essential to know them in
  87 order to control LTTng tracing, which always happen within the scope of
  88 a tracing session.