Commit | Line | Data |
---|---|---|
5e0cbfb0 PP |
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 | ||
47bfcb75 PP |
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 | |
5e0cbfb0 PP |
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 | ||
47bfcb75 PP |
80 | Providing no argument to `lttng destroy` destroys the current |
81 | tracing session. Destroying a tracing session stops any tracing | |
5e0cbfb0 PP |
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. |