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