| 1 | --- |
| 2 | id: tracing-session |
| 3 | --- |
| 4 | |
| 5 | A _tracing session_ is—like any session—a container of |
| 6 | state. Anything that is done when tracing using LTTng happens in the |
| 7 | scope of a tracing session. In this regard, it is analogous to a bank |
| 8 | website's session: you can't interact online with your bank account |
| 9 | unless you are logged in a session, except for reading a few static |
| 10 | webpages (LTTng, too, can report some static information that does not |
| 11 | need a created tracing session). |
| 12 | |
| 13 | A tracing session holds the following attributes and objects (some of |
| 14 | which are described in the following sections): |
| 15 | |
| 16 | * a name |
| 17 | * the tracing state (tracing started or stopped) |
| 18 | * the trace data output path/URL (local path or sent over the network) |
| 19 | * a mode (normal, snapshot or live) |
| 20 | * the snapshot output paths/URLs (if applicable) |
| 21 | * for each [domain](#doc-domain), a list of [channels](#doc-channel) |
| 22 | * for each channel: |
| 23 | * a name |
| 24 | * the channel state (enabled or disabled) |
| 25 | * its parameters (event loss mode, sub-buffers size and count, |
| 26 | timer periods, output type, trace files size and count, etc.) |
| 27 | * a list of added context information |
| 28 | * a list of [events](#doc-event) |
| 29 | * for each event: |
| 30 | * its state (enabled or disabled) |
| 31 | * a list of instrumentation points (tracepoints, system calls, |
| 32 | dynamic probes, etc.) |
| 33 | * associated log levels |
| 34 | * a filter expression |
| 35 | |
| 36 | All this information is completely isolated between tracing sessions. |
| 37 | |
| 38 | Conceptually, a tracing session is a per-user object; the |
| 39 | [Plumbing](#doc-plumbing) section shows how this is actually |
| 40 | implemented. Any user may create as many concurrent tracing sessions |
| 41 | as desired. As you can see in the list above, even the tracing state |
| 42 | is a per-tracing session attribute, so that you may trace your target |
| 43 | system/application in a given tracing session with a specific |
| 44 | configuration while another one stays inactive. |
| 45 | |
| 46 | The trace data generated in a tracing session may be either saved |
| 47 | to disk, sent over the network or not saved at all (in which case |
| 48 | snapshots may still be saved to disk or sent to a remote machine). |