| 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. |