From e971184584781f70bbbfc52bbede8b9abf0436e5 Mon Sep 17 00:00:00 2001 From: Philippe Proulx Date: Mon, 14 Jun 2021 22:52:02 -0400 Subject: [PATCH] Rename "tracing session" -> "recording session" MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit Starting from LTTng 2.13, _tracing_ is defined as attempting to execute one or more actions when emitting an event, which is very close to the trigger definition. To highlight that a tracing session is only about event recording, rename this concept to _recording session_. This patch mostly changes the manual pages, although I also updated some C source and other files which contain user-facing text to use the new term. I didn't update logging messages because debugging scripts could still refer to "tracing sessions". The lttng-concepts(7) manual page mentions that the "recording session" term was "tracing session" before LTTng 2.13. Signed-off-by: Philippe Proulx Signed-off-by: Jérémie Galarneau Change-Id: I620d6b6be9e0f1dac14c0bc5e26094c3b3711c75 --- configure.ac | 30 ++-- doc/man/common-lttng-cmd-after-options.txt | 10 +- doc/man/lttng-add-context.1.txt | 31 ++-- doc/man/lttng-add-trigger.1.txt | 39 ++--- doc/man/lttng-clear.1.txt | 49 +++--- doc/man/lttng-concepts.7.txt | 155 +++++++++--------- doc/man/lttng-crash.1.txt | 4 +- doc/man/lttng-create.1.txt | 120 +++++++------- doc/man/lttng-destroy.1.txt | 54 +++--- doc/man/lttng-disable-channel.1.txt | 19 ++- doc/man/lttng-disable-event.1.txt | 26 +-- doc/man/lttng-disable-rotation.1.txt | 20 +-- doc/man/lttng-enable-channel.1.txt | 32 ++-- doc/man/lttng-enable-event.1.txt | 42 ++--- doc/man/lttng-enable-rotation.1.txt | 34 ++-- doc/man/lttng-list.1.txt | 35 ++-- doc/man/lttng-load.1.txt | 70 ++++---- doc/man/lttng-metadata.1.txt | 10 +- doc/man/lttng-regenerate.1.txt | 47 +++--- doc/man/lttng-relayd.8.txt | 16 +- doc/man/lttng-rotate.1.txt | 44 ++--- doc/man/lttng-save.1.txt | 40 ++--- doc/man/lttng-sessiond.8.txt | 38 ++--- doc/man/lttng-set-session.1.txt | 13 +- doc/man/lttng-snapshot.1.txt | 86 +++++----- doc/man/lttng-start.1.txt | 24 +-- doc/man/lttng-status.1.txt | 10 +- doc/man/lttng-stop.1.txt | 50 +++--- doc/man/lttng-track.1.txt | 42 ++--- doc/man/lttng-untrack.1.txt | 38 ++--- doc/man/lttng-view.1.txt | 16 +- doc/man/lttng.1.txt | 10 +- doc/python-howto.txt | 4 +- doc/quickstart.txt | 10 +- doc/streaming-howto.txt | 6 +- extras/bindings/swig/python/lttng.i.in | 6 +- src/bin/lttng/commands/list.c | 6 +- src/bin/lttng/lttng.c | 4 +- src/common/error.c | 6 +- src/lib/lttng-ctl/lttng-ctl.pc.in | 2 +- .../tools/trigger/start-stop/test_start_stop | 4 +- tests/utils/test_utils.py | 2 +- 42 files changed, 655 insertions(+), 649 deletions(-) diff --git a/configure.ac b/configure.ac index 194736bd6..0da5a04e4 100644 --- a/configure.ac +++ b/configure.ac @@ -426,28 +426,28 @@ _AC_DEFINE_AND_SUBST([DEFAULT_EVENT_NOTIFIER_ERROR_COUNT_MAP_SIZE], [4096]) # Command short descriptions _AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_ADD_CONTEXT], [Add context fields to be recorded]) _AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_ADD_TRIGGER], [Add a trigger]) -_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_CLEAR], [Clear a tracing session]) -_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_CREATE], [Create a tracing session]) -_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_DESTROY], [Destroy tracing sessions]) +_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_CLEAR], [Clear a recording session]) +_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_CREATE], [Create a recording session]) +_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_DESTROY], [Destroy recording sessions]) _AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_DISABLE_CHANNEL], [Disable channels]) _AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_DISABLE_EVENT], [Disable recording event rules]) -_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_DISABLE_ROTATION], [Unset a tracing session rotation schedule]) +_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_DISABLE_ROTATION], [Unset a recording session rotation schedule]) _AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_ENABLE_CHANNEL], [Create or enable a channel]) _AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_ENABLE_EVENT], [Create or enable recording event rules]) -_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_ENABLE_ROTATION], [Set a tracing session rotation schedule]) +_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_ENABLE_ROTATION], [Set a recording session rotation schedule]) _AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_HELP], [Show the help of a command]) -_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_LIST], [List tracing sessions and instrumentation points]) +_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_LIST], [List recording sessions and instrumentation points]) _AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_LIST_TRIGGERS], [List triggers]) -_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_LOAD], [Load tracing session configurations]) -_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_REGENERATE], [Regenerate specific tracing session data]) +_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_LOAD], [Load recording session configurations]) +_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_REGENERATE], [Regenerate specific recording session data]) _AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_REMOVE_TRIGGER], [Remove a trigger]) -_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_ROTATE], [Archive the current trace chunk of a tracing session]) -_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_SAVE], [Save tracing session configurations]) -_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_SET_SESSION], [Set the current tracing session]) -_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_SNAPSHOT], [Take a tracing session snapshot]) -_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_START], [Start a tracing session]) -_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_STATUS], [Show the status of the current tracing session]) -_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_STOP], [Stop a tracing session]) +_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_ROTATE], [Archive the current trace chunk of a recording session]) +_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_SAVE], [Save recording session configurations]) +_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_SET_SESSION], [Set the current recording session]) +_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_SNAPSHOT], [Take a recording session snapshot]) +_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_START], [Start a recording session]) +_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_STATUS], [Show the status of the current recording session]) +_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_STOP], [Stop a recording session]) _AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_TRACK], [Allow specific processes to record events]) _AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_UNTRACK], [Disallow specific processes to record events]) _AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_VERSION], [Show LTTng-tools version information]) diff --git a/doc/man/common-lttng-cmd-after-options.txt b/doc/man/common-lttng-cmd-after-options.txt index 82db25a95..24ebbfb40 100644 --- a/doc/man/common-lttng-cmd-after-options.txt +++ b/doc/man/common-lttng-cmd-after-options.txt @@ -36,7 +36,7 @@ directory. nloption:--help option) instead of `/usr/bin/man`. `LTTNG_SESSION_CONFIG_XSD_PATH`:: - Path to the directory containing the `session.xsd` tracing session + Path to the directory containing the `session.xsd` recording session configuration XML schema. `LTTNG_SESSIOND_PATH`:: @@ -53,9 +53,9 @@ FILES `$LTTNG_HOME/.lttngrc`:: Unix user's LTTng runtime configuration. + -This is where LTTng stores the name of the Unix user's current tracing +This is where LTTng stores the name of the Unix user's current recording session between executions of man:lttng(1). man:lttng-create(1) and -man:lttng-set-session(1) set the current tracing session. +man:lttng-set-session(1) set the current recording session. `$LTTNG_HOME/lttng-traces`:: Default output directory of LTTng traces in local and snapshot @@ -68,11 +68,11 @@ man:lttng-create(1) command. Unix user's LTTng runtime and configuration directory. `$LTTNG_HOME/.lttng/sessions`:: - Default directory containing the Unix user's saved tracing session + Default directory containing the Unix user's saved recording session configurations (see man:lttng-save(1) and man:lttng-load(1)). +{system_sessions_dir}+:: - Directory containing the system-wide saved tracing session + Directory containing the system-wide saved recording session configurations (see man:lttng-save(1) and man:lttng-load(1)). NOTE: `$LTTNG_HOME` defaults to the value of the `HOME` environment diff --git a/doc/man/lttng-add-context.1.txt b/doc/man/lttng-add-context.1.txt index 38b77617e..49f0a7b03 100644 --- a/doc/man/lttng-add-context.1.txt +++ b/doc/man/lttng-add-context.1.txt @@ -1,6 +1,6 @@ lttng-add-context(1) ==================== -:revdate: 6 May 2021 +:revdate: 14 June 2021 NAME @@ -34,22 +34,22 @@ Without the option:--list option:: records of: + With the option:--session='SESSION' option::: - The tracing session named 'SESSION'. + The recording session named 'SESSION'. Without the option:--session option::: - The current tracing session (see man:lttng-concepts(7) to learn more - about the current tracing session). + The current recording session (see man:lttng-concepts(7) to learn + more about the current recording session). With the option:--channel='CHANNEL'::: The channel named 'CHANNEL'. Without the option:--channel option::: - *All* the channels of the selected tracing session. + *All* the channels of the selected recording session. With the option:--list option:: List the available context field types. -See man:lttng-concepts(7) to learn more about tracing sessions and +See man:lttng-concepts(7) to learn more about recording sessions and channels. Repeat the option:--type='TYPE' option to add more than one context @@ -109,8 +109,9 @@ IMPORTANT: Make sure to **single-quote** 'TYPE' when you run the variable substitution in most shells. NOTE: As of LTTng{nbsp}{lttng_version}, you may :not: add context fields -to be recorded to the event records of a given channel once its tracing -session has been started (see man:lttng-start(1)) at least once. +to be recorded to the event records of a given channel once its +recording session has been started (see man:lttng-start(1)) at least +once. See the ``<>'' section below for usage examples. @@ -144,12 +145,12 @@ Recording target option:-c 'CHANNEL', option:--channel='CHANNEL':: Add context fields to be recorded to the event records of a channel named 'CHANNEL' instead of all the channels of the selected - tracing session. + recording session. option:-s 'SESSION', option:--session='SESSION':: Add context fields to be recorded to the event records of one or - more channels of the tracing session named 'SESSION' instead of the - current tracing session. + more channels of the recording session named 'SESSION' instead of + the current recording session. Context field type @@ -185,7 +186,7 @@ $ lttng add-context --list ---- ==== -.Add a single statically-known context field to be recorded to all the Linux kernel channels of the current tracing session. +.Add a single statically-known context field to be recorded to all the Linux kernel channels of the current recording session. ==== [role="term"] ---- @@ -193,7 +194,7 @@ $ lttng add-context --kernel --type=pid ---- ==== -.Add three statically-known context fields to be recorded to a specific user space channel of a specific tracing session. +.Add three statically-known context fields to be recorded to a specific user space channel of a specific recording session. ==== See the option:--session and option:--channel options. @@ -205,7 +206,7 @@ $ lttng add-context --userspace --session=my-session \ ---- ==== -.Add a perf counter context field to be recorded to a specific Linux kernel channel of the current tracing session. +.Add a perf counter context field to be recorded to a specific Linux kernel channel of the current recording session. ==== See the option:--channel option. @@ -216,7 +217,7 @@ $ lttng add-context --kernel --channel=my-channel \ ---- ==== -.Add an LTTng application-specific context field to be recorded to all the JUL channels of the current tracing session. +.Add an LTTng application-specific context field to be recorded to all the JUL channels of the current recording session. ==== [role="term"] ---- diff --git a/doc/man/lttng-add-trigger.1.txt b/doc/man/lttng-add-trigger.1.txt index 092163cfc..656f87b4e 100644 --- a/doc/man/lttng-add-trigger.1.txt +++ b/doc/man/lttng-add-trigger.1.txt @@ -1,6 +1,6 @@ lttng-add-trigger(1) ==================== -:revdate: 18 May 2021 +:revdate: 14 June 2021 NAME @@ -178,65 +178,66 @@ to receive LTTng notifications (see the liblttng-ctl C{nbsp}headers). + See below for the nloption:--rate-policy option. -Start a tracing session:: +Start a recording session:: Synopsis: + [verse] option:--action=**start-session** 'SESSION' [nloption:--rate-policy='POLICY'] {nbsp} + -Starts the tracing session named 'SESSION' like man:lttng-start(1) +Starts the recording session named 'SESSION' like man:lttng-start(1) would. + -If no tracing session has the name 'SESSION' when LTTng is ready to +If no recording session has the name 'SESSION' when LTTng is ready to execute the action, LTTng does nothing. + See below for the nloption:--rate-policy option. -Stop a tracing session:: +Stop a recording session:: Synopsis: + [verse] option:--action=**stop-session** 'SESSION' [nloption:--rate-policy='POLICY'] {nbsp} + -Stops the tracing session named 'SESSION' like man:lttng-stop(1) would. +Stops the recording session named 'SESSION' like man:lttng-stop(1) +would. + -If no tracing session has the name 'SESSION' when LTTng is ready to +If no recording session has the name 'SESSION' when LTTng is ready to execute the action, LTTng does nothing. + See below for the nloption:--rate-policy option. -Rotate a tracing session:: +Rotate a recording session:: Synopsis: + [verse] option:--action=**rotate-session** 'SESSION' [nloption:--rate-policy='POLICY'] {nbsp} + -Archives the current trace chunk of the tracing session named 'SESSION' -like man:lttng-rotate(1) would. +Archives the current trace chunk of the recording session named +'SESSION' like man:lttng-rotate(1) would. + -If no tracing session has the name 'SESSION' when LTTng is ready to +If no recording session has the name 'SESSION' when LTTng is ready to execute the action, LTTng does nothing. + See below for the nloption:--rate-policy option. -Take a tracing session snapshot:: +Take a recording session snapshot:: Synopsis: + [verse] option:--action=**snapshot-session** 'SESSION' [nloption:--rate-policy='POLICY'] {nbsp} + -Takes a snapshot of the tracing session named 'SESSION' like +Takes a snapshot of the recording session named 'SESSION' like man:lttng-snapshot(1) would. + -When the condition of the trigger is satisfied, the tracing session -named 'SESSION', if any, must be a snapshot-mode tracing session +When the condition of the trigger is satisfied, the recording session +named 'SESSION', if any, must be a snapshot-mode recording session (see man:lttng-create(1)). + -If no tracing session has the name 'SESSION' when LTTng is ready to +If no recording session has the name 'SESSION' when LTTng is ready to execute the action, LTTng does nothing. + See below for the nloption:--rate-policy option. @@ -327,7 +328,7 @@ $ lttng add-trigger --condition=event-rule-matches \ ---- ==== -.Add an ``event rule matches'' trigger of which the action is to stop a tracing session and then rotate it. +.Add an ``event rule matches'' trigger of which the action is to stop a recording session and then rotate it. ==== The `event-rule-matches` trigger condition below specifies an event rule which matches any user space tracepoint event with a name starting with @@ -344,7 +345,7 @@ $ lttng add-trigger --condition=event-rule-matches \ --action=rotate-session my-session ---- -See man:lttng-concepts(7) to learn more about tracing sessions and +See man:lttng-concepts(7) to learn more about recording sessions and rotations. ==== @@ -401,7 +402,7 @@ $ lttng add-trigger --condition=event-rule-matches \ ---- ==== -.Add an ``event rule matches'' trigger with a tracing session starting action to be executed a single time after 40{nbsp}times. +.Add an ``event rule matches'' trigger with a recording session starting action to be executed a single time after 40{nbsp}times. ==== The `event-rule-matches` trigger condition below specifies an event rule which matches any Linux system call event (entry and exit) of which the diff --git a/doc/man/lttng-clear.1.txt b/doc/man/lttng-clear.1.txt index e2b878cf3..3d125a672 100644 --- a/doc/man/lttng-clear.1.txt +++ b/doc/man/lttng-clear.1.txt @@ -1,10 +1,10 @@ lttng-clear(1) ============== -:revdate: 17 May 2021 +:revdate: 14 June 2021 NAME ---- -lttng-clear - Clear an LTTng tracing session +lttng-clear - Clear an LTTng recording session SYNOPSIS @@ -15,44 +15,45 @@ SYNOPSIS DESCRIPTION ----------- -The `lttng clear` command clears one or more tracing sessions, that is, -it deletes the contents of their tracing buffers and of all their local -and streamed trace data. +The `lttng clear` command clears one or more recording sessions, that +is, it deletes the contents of their recording buffers and of all their +local and streamed trace data. -See man:lttng-concepts(7) to learn more about tracing sessions. +See man:lttng-concepts(7) to learn more about recording sessions. The `clear` command clears: Without any option:: - The current tracing session. + The current recording session. + -See man:lttng-concepts(7) to learn more about the current tracing +See man:lttng-concepts(7) to learn more about the current recording session. With the 'SESSION' argument:: - The tracing session named 'SESSION'. + The recording session named 'SESSION'. With the option:--all option:: - *All* the tracing sessions of the connected session daemon for your - Unix user, or for all users if your Unix user is `root`, as listed - in the output of `lttng list` (see man:lttng-list(1)). + *All* the recording sessions of the connected session daemon for + your Unix user, or for all users if your Unix user is `root`, as + listed in the output of `lttng list` (see man:lttng-list(1)). + See the ``Session daemon connection'' section of man:lttng(1) to learn how a user application connects to a session daemon. -If a tracing session is configured in snapshot mode (see the +If a recording session is configured in snapshot mode (see the nloption:--snapshot option of the man:lttng-create(1) command), the -`clear` command only clears the tracing buffers. +`clear` command only clears the recording buffers. -For a given tracing session, if at least one rotation occurred (see -man:lttng-concepts(7)), the `clear` command only clears its tracing +For a given recording session, if at least one rotation occurred (see +man:lttng-concepts(7)), the `clear` command only clears its recording buffers and its current trace chunk, :not: its archived trace chunks. NOTE: The nloption:--disallow-clear option and the `LTTNG_RELAYD_DISALLOW_CLEAR` environment variable of man:lttng-relayd(8) can disable remote clearing operations. If LTTng -sends tracing data over the network for the selected tracing session(s) -to an LTTng relay daemon configured as such, the `clear` command fails. +sends recording data over the network for the selected recording +session(s) to an LTTng relay daemon configured as such, the `clear` +command fails. See the ``<>'' section below for usage examples. @@ -63,10 +64,10 @@ include::common-lttng-cmd-options-head.txt[] Recording target ~~~~~~~~~~~~~~~~ option:-a, option:--all:: - Clear all the tracing sessions of your Unix user, or of all users if + Clear all the recording sessions of your Unix user, or of all users if your Unix user is `root`, as listed in the output of - man:lttng-list(1), instead of the current tracing session or the - tracing session named 'SESSION'. + man:lttng-list(1), instead of the current recording session or the + recording session named 'SESSION'. include::common-lttng-cmd-help-options.txt[] @@ -78,7 +79,7 @@ include::common-lttng-cmd-after-options.txt[] [[examples]] EXAMPLES -------- -.Clear the current tracing session. +.Clear the current recording session. ==== [role="term"] ---- @@ -86,7 +87,7 @@ $ lttng clear ---- ==== -.Clear a specific tracing session. +.Clear a specific recording session. ==== [role="term"] ---- @@ -94,7 +95,7 @@ $ lttng clear my-session ---- ==== -.Clear all tracing sessions. +.Clear all recording sessions. ==== See the option:--all option. diff --git a/doc/man/lttng-concepts.7.txt b/doc/man/lttng-concepts.7.txt index 463d957e2..a1bea3b9c 100644 --- a/doc/man/lttng-concepts.7.txt +++ b/doc/man/lttng-concepts.7.txt @@ -1,8 +1,8 @@ lttng-concepts(7) ================= -:revdate: 18 May 2021 +:revdate: 14 June 2021 :sect-event-rule: INSTRUMENTATION POINT, EVENT RULE, AND EVENT -:sect-session: TRACING SESSION +:sect-session: RECORDING SESSION :sect-domain: TRACING DOMAIN :sect-channel: CHANNEL AND RING BUFFER :sect-recording-event-rule: RECORDING EVENT RULE AND EVENT RECORD @@ -25,7 +25,7 @@ The concepts of LTTng{nbsp}{lttng_version} are: * Instrumentation point, event rule, and event * Trigger -* Tracing session +* Recording session * Tracing domain * Channel and ring buffer * Recording event rule and event record @@ -80,7 +80,7 @@ properties are: ** The status of the rule itself. ** The status of the channel (see the ``<>'' section below). -** The activity of the tracing session (started or stopped; see +** The activity of the recording session (started or stopped; see the ``<>'' section below). ** Whether or not the process for which LTTng would create the event is allowed to record events (see man:lttng-track(1)). @@ -104,14 +104,14 @@ below. Create or enable a recording event rule with the man:lttng-enable-event(1) command. + -List the recording event rules of a specific tracing session +List the recording event rules of a specific recording session and/or channel with the man:lttng-list(1) and man:lttng-status(1) commands. ``Event rule matches'' <> condition (since LTTng{nbsp}2.13):: When the event rule of the trigger condition matches an event, LTTng can execute user-defined actions such as sending an LTTng - notification, starting a tracing session, and more. + notification, starting a recording session, and more. + See man:lttng-add-trigger(1) and man:lttng-event-rule(7). @@ -223,7 +223,7 @@ actions are: Conditions:: + -* The consumed buffer size of a given tracing +* The consumed buffer size of a given recording session (see the ``<>'' section below) becomes greater than some value. @@ -233,10 +233,10 @@ Conditions:: * The buffer usage of a given channel becomes less than some value. -* There's an ongoing tracing session rotation (see the - ``<>'' section below). +* There's an ongoing recording session rotation (see the + ``<>'' section below). -* A tracing session rotation becomes completed. +* A recording session rotation becomes completed. * An event rule matches an event. + @@ -247,15 +247,15 @@ other ones are available through the liblttng-ctl C{nbsp}API. Actions:: + * Send a notification to a user application. -* Start a given tracing session, like man:lttng-start(1) would do. -* Stop a given tracing session, like man:lttng-stop(1) would do. -* Archive the current trace chunk of a given tracing session (rotate), +* Start a given recording session, like man:lttng-start(1) would do. +* Stop a given recording session, like man:lttng-stop(1) would do. +* Archive the current trace chunk of a given recording session (rotate), like man:lttng-rotate(1) would do. -* Take a snapshot of a given tracing session, like man:lttng-snapshot(1) - would do. +* Take a snapshot of a given recording session, like + man:lttng-snapshot(1) would do. A trigger belongs to a session daemon (see man:lttng-sessiond(8)), not -to a specific tracing session. For a given session daemon, each Unix +to a specific recording session. For a given session daemon, each Unix user has its own, private triggers. Note, however, that the `root` Unix user may, for the root session daemon: @@ -279,12 +279,12 @@ Remove a trigger with the man:lttng-remove-trigger(1) command. [[session]] {sect-session} -------------- -A _tracing session_ is a stateful dialogue between you and a session -daemon (see man:lttng-sessiond(8)) for everything related to event -recording. +A _recording session_ (named ``tracing session'' prior to +LTTng{nbsp}2.13) is a stateful dialogue between you and a session daemon +(see man:lttng-sessiond(8)) for everything related to event recording. Everything that you do when you control LTTng tracers to record events -happens within a tracing session. In particular, a tracing session: +happens within a recording session. In particular, a recording session: * Has its own name, unique for a given session daemon. @@ -292,13 +292,13 @@ happens within a tracing session. In particular, a tracing session: * Has its own state of activity (started or stopped). + -An active tracing session is an implicit recording event rule condition -(see the ``<>'' -section below). +An active recording session is an implicit recording event rule +condition (see the +``<>'' section below). * Has its own mode (local, network streaming, snapshot, or live). + -See the ``<>'' section below to +See the ``<>'' section below to learn more. * Has its own channels (see the ``<>'' section @@ -307,49 +307,49 @@ learn more. * Has its own process attribute inclusion sets (see man:lttng-track(1)). Those attributes and objects are completely isolated between different -tracing sessions. +recording sessions. -A tracing session is like an ATM session: the operations you do on the +A recording session is like an ATM session: the operations you do on the banking system through the ATM don't alter the data of other users of the same system. In the case of the ATM, a session lasts as long as your -bank card is inside. In the case of LTTng, a tracing session lasts from +bank card is inside. In the case of LTTng, a recording session lasts from the man:lttng-create(1) command to the man:lttng-destroy(1) command. -A tracing session belongs to a session daemon (see +A recording session belongs to a session daemon (see man:lttng-sessiond(8)). For a given session daemon, each Unix user has -its own, private tracing sessions. Note, however, that the `root` Unix -user may operate on or destroy another user's tracing session. +its own, private recording sessions. Note, however, that the `root` Unix +user may operate on or destroy another user's recording session. -Create a tracing session with the man:lttng-create(1) command. +Create a recording session with the man:lttng-create(1) command. -List the tracing sessions of the connected session daemon with +List the recording sessions of the connected session daemon with the man:lttng-list(1) command. -Start and stop a tracing session with the man:lttng-start(1) and +Start and stop a recording session with the man:lttng-start(1) and man:lttng-stop(1) commands. -Save and load a tracing session with the man:lttng-save(1) and +Save and load a recording session with the man:lttng-save(1) and man:lttng-load(1) commands. -Archive the current trace chunk of (rotate) a tracing session with the +Archive the current trace chunk of (rotate) a recording session with the man:lttng-rotate(1) command. -Destroy a tracing session with the man:lttng-destroy(1) command. +Destroy a recording session with the man:lttng-destroy(1) command. -Current tracing session +Current recording session ~~~~~~~~~~~~~~~~~~~~~~~ When you run the man:lttng-create(1) command, LTTng creates the `$LTTNG_HOME/.lttngrc` file if it doesn't exist (`$LTTNG_HOME` defaults to `$HOME`). -`$LTTNG_HOME/.lttngrc` contains the name of the _current tracing +`$LTTNG_HOME/.lttngrc` contains the name of the _current recording session_. -When you create a new tracing session with the `create` command, LTTng -updates the current tracing session. +When you create a new recording session with the `create` command, LTTng +updates the current recording session. -The following man:lttng(1) commands select the current tracing session +The following man:lttng(1) commands select the current recording session if you don't specify one: * man:lttng-add-context(1) @@ -372,15 +372,15 @@ if you don't specify one: * man:lttng-untrack(1) * man:lttng-view(1) -Set the current tracing session manually with the +Set the current recording session manually with the man:lttng-set-session(1) command, without having to edit the `.lttngrc` file. [[session-modes]] -Tracing session modes -~~~~~~~~~~~~~~~~~~~~~ -LTTng offers four tracing session modes: +Recording session modes +~~~~~~~~~~~~~~~~~~~~~~~ +LTTng offers four recording session modes: Local mode:: Write the trace data to the local file system. @@ -397,7 +397,7 @@ Snapshot mode:: LTTng forces all the channels (see the ``<>'' section below) to be created to be configured to be snapshot-ready. + -LTTng takes a snapshot of such a tracing session when: +LTTng takes a snapshot of such a recording session when: + -- * You run the man:lttng-snapshot(1) command. @@ -411,15 +411,15 @@ Live mode:: (see man:lttng-relayd(8)) for live reading. + An LTTng live reader (for example, man:babeltrace2(1)) can connect to -the same relay daemon to receive trace data while the tracing session is +the same relay daemon to receive trace data while the recording session is active. [[rotation]] -Tracing session rotation -~~~~~~~~~~~~~~~~~~~~~~~~ -A _tracing session rotation_ is the action of archiving the current -trace chunk of the tracing session to the file system. +Recording session rotation +~~~~~~~~~~~~~~~~~~~~~~~~~~ +A _recording session rotation_ is the action of archiving the current +trace chunk of the recording session to the file system. Once LTTng archives a trace chunk, it does :not: manage it anymore: you can read it, modify it, move it, or remove it. @@ -429,13 +429,13 @@ files which form a self-contained LTTng trace. See the ``<>'' section below to learn how LTTng names a trace chunk archive directory. -The _current trace chunk_ of a given tracing session includes: +The _current trace chunk_ of a given recording session includes: * The stream files which LTTng already wrote to the file system, and which are not part of a previously archived trace chunk, since the most recent event amongst: -** The first time the tracing session was started, either with the +** The first time the recording session was started, either with the man:lttng-start(1) command or with a `start-session` trigger action (see the ``<>'' section above). @@ -450,14 +450,14 @@ The _current trace chunk_ of a given tracing session includes: ``<>'' section above). * The content of all the non-flushed sub-buffers of the channels of the - tracing session. + recording session. [[trace-chunk-naming]] Trace chunk archive naming ~~~~~~~~~~~~~~~~~~~~~~~~~~ A trace chunk archive is a subdirectory of the `archives` subdirectory -within the output directory of a tracing session (see the +within the output directory of a recording session (see the nloption:--output option of the man:lttng-create(1) command and of man:lttng-relayd(8)). @@ -469,15 +469,15 @@ A trace chunk archive is, at the same time: * A self-contained LTTng trace. * A member of a set of trace chunk archives which form the complete - trace of a tracing session. + trace of a recording session. -In other words, an LTTng trace reader can read both the tracing +In other words, an LTTng trace reader can read both the recording session output directory (all the trace chunk archives), or a single trace chunk archive. -When LTTng performs a tracing session rotation, it names the resulting +When LTTng performs a recording session rotation, it names the resulting trace chunk archive as such, relative to the output directory of the -tracing session: +recording session: [verse] archives/__BEGIN__-__END__-__ID__ @@ -499,7 +499,7 @@ __END__:: Example: `20180118T152407+0930` __ID__:: - Unique numeric identifier of the trace chunk within its tracing + Unique numeric identifier of the trace chunk within its recording session. Trace chunk archive name example: @@ -618,7 +618,7 @@ which you can't configure. A channel owns recording event rules. -List the channels of a given tracing session with the +List the channels of a given recording session with the man:lttng-list(1) and man:lttng-status(1) commands. Disable an enabled channel with the man:lttng-disable-channel(1) @@ -718,11 +718,12 @@ similar to the roll mode of an oscilloscope. + Since LTTng{nbsp}2.8, with this mode, LTTng writes to a given sub-buffer its sequence number within its data stream. With a local, network -streaming, or live tracing session (see the ``<>'' section above), a trace reader can use such sequence -numbers to report lost packets. A trace reader can use the saved -discarded sub-buffer (packet) count of the trace to decide whether or -not to perform some analysis even if trace data is known to be missing. +streaming, or live recording session (see the +``<>'' section above), a trace +reader can use such sequence numbers to report lost packets. A trace +reader can use the saved discarded sub-buffer (packet) count of the +trace to decide whether or not to perform some analysis even if trace +data is known to be missing. + With this mode, LTTng doesn't write to the trace the exact number of lost event records in the lost sub-buffers. @@ -845,14 +846,14 @@ file. This mechanism is called _trace file rotation_. [IMPORTANT] ==== Even if you don't limit the trace file count, always assume that LTTng -manages all the trace files of the tracing session. +manages all the trace files of the recording session. In other words, there's no safe way to know if LTTng still holds a given trace file open with the trace file rotation feature. The only way to obtain an unmanaged, self-contained LTTng trace before -you destroy the tracing session is with the tracing session rotation -feature (see the ``<>'' section +you destroy the recording session is with the recording session rotation +feature (see the ``<>'' section above), which is available since LTTng{nbsp}2.11. ==== @@ -900,7 +901,7 @@ Monitor timer:: statistics to evaluate the following trigger conditions: + -- -. The consumed buffer size of a given tracing session becomes greater +. The consumed buffer size of a given recording session becomes greater than some value. . The buffer usage of a given channel becomes greater than some value. . The buffer usage of a given channel becomes less than some value. @@ -909,7 +910,7 @@ Monitor timer:: If you disable the monitor timer of a channel{nbsp}__C__: + -- -* The consumed buffer size value of the tracing session of{nbsp}__C__ +* The consumed buffer size value of the recording session of{nbsp}__C__ could be wrong for trigger condition type{nbsp}1: the consumed buffer size of{nbsp}__C__ won't be part of the grand total. @@ -947,16 +948,16 @@ A channel is enabled on creation. + See the ``<>'' section above. -* The tracing session of the recording event rule is active (started). +* The recording session of the recording event rule is active (started). + -A tracing session is inactive (stopped) on creation. +A recording session is inactive (stopped) on creation. + See the ``<>'' section above. * The process for which LTTng creates an event to match is allowed to record events. + -All processes are allowed to record events on tracing session +All processes are allowed to record events on recording session creation. + Use the man:lttng-track(1) and man:lttng-untrack(1) commands to select @@ -964,7 +965,7 @@ which processes are allowed to record events based on specific process attributes. You always attach a recording event rule to a channel, which belongs to -a tracing session, when you create it. +a recording session, when you create it. When a recording event rule{nbsp}__ER__ matches an event{nbsp}__E__, LTTng attempts to serialize and record{nbsp}__E__ to one of the @@ -981,7 +982,7 @@ $ lttng enable-event --userspace hello:world $ lttng enable-event --userspace hello:world --loglevel=INFO ---- -List the recording event rules of a specific tracing session +List the recording event rules of a specific recording session and/or channel with the man:lttng-list(1) and man:lttng-status(1) commands. @@ -989,7 +990,7 @@ Disable a recording event rule with the man:lttng-disable-event(1) command. As of LTTng{nbsp}{lttng_version}, you cannot remove a recording event -rule: it exists as long as its tracing session exists. +rule: it exists as long as its recording session exists. include::common-footer.txt[] diff --git a/doc/man/lttng-crash.1.txt b/doc/man/lttng-crash.1.txt index dd8c6c701..e48da4188 100644 --- a/doc/man/lttng-crash.1.txt +++ b/doc/man/lttng-crash.1.txt @@ -1,6 +1,6 @@ lttng-crash(1) ============== -:revdate: 3 May 2021 +:revdate: 14 June 2021 NAME @@ -34,7 +34,7 @@ With the option:--extract='DIR' option:: 'SHMDIR' is the directory specified as the argument of the nloption:--shm-path option of the man:lttng-create(1) command used to -create the tracing session for which to recover the traces. +create the recording session for which to recover the traces. OPTIONS diff --git a/doc/man/lttng-create.1.txt b/doc/man/lttng-create.1.txt index 4e997e1d1..ea19a159d 100644 --- a/doc/man/lttng-create.1.txt +++ b/doc/man/lttng-create.1.txt @@ -1,35 +1,35 @@ lttng-create(1) =============== -:revdate: 17 May 2021 +:revdate: 14 June 2021 NAME ---- -lttng-create - Create an LTTng tracing session +lttng-create - Create an LTTng recording session SYNOPSIS -------- -Create a local mode tracing session: +Create a local mode recording session: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] [option:--shm-path='DIR'] [option:--no-output | option:--output='DIR' | option:--set-url=**file://**__DIR__] -Create a network streaming mode tracing session: +Create a network streaming mode recording session: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] [option:--shm-path='DIR'] (option:--set-url='URL' | option:--ctrl-url='URL' option:--data-url='URL') -Create a snapshot mode tracing session: +Create a snapshot mode recording session: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] option:--snapshot [option:--shm-path='DIR'] [option:--no-output | option:--output='DIR' | option:--set-url='URL' | option:--ctrl-url='URL' option:--data-url='URL'] -Create a live mode tracing session: +Create a live mode recording session: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] option:--live[='DELAYUS'] @@ -37,14 +37,14 @@ Create a live mode tracing session: DESCRIPTION ----------- -The `lttng create` command creates a new tracing session for your Unix +The `lttng create` command creates a new recording session for your Unix user within the connected session daemon (see the ``Session daemon connection'' section of man:lttng(1) to learn how a user application connects to a session daemon). -See man:lttng-concepts(7) to learn more about tracing sessions. +See man:lttng-concepts(7) to learn more about recording sessions. -Without the 'SESSION' argument, LTTng automatically generates a tracing +Without the 'SESSION' argument, LTTng automatically generates a recording session name having the ++auto-++__YYYYmmdd__++-++__HHMMSS__ form, where 'YYYYmmdd' and 'HHMMSS' are the creation date and time. 'SESSION' may :not: contain the character `/`. @@ -88,37 +88,37 @@ In this case, the `create` command spawns a relay daemon as such: Override the path of the relay daemon binary to spawn with the general genoption:--relayd-path option. -On success, the `create` command sets the current tracing session (see -man:lttng-concepts(7) to learn more) to the created tracing session. +On success, the `create` command sets the current recording session (see +man:lttng-concepts(7) to learn more) to the created recording session. See the ``<>'' section below for usage examples. -Show the status of the current tracing session with the +Show the status of the current recording session with the man:lttng-status(1) command. -List the tracing sessions of your Unix user, or of all users if +List the recording sessions of your Unix user, or of all users if your Unix user is `root`, within the connected session daemon with the man:lttng-list(1) command. -Start and stop a tracing session with the man:lttng-start(1) and +Start and stop a recording session with the man:lttng-start(1) and man:lttng-stop(1) commands. -Save and load a tracing session with the man:lttng-save(1) and +Save and load a recording session with the man:lttng-save(1) and man:lttng-load(1) commands. Allow and disallow specific processes to record events with the man:lttng-track(1) and man:lttng-untrack(1) commands. -Archive the current trace chunk of (rotate) a tracing session with the +Archive the current trace chunk of (rotate) a recording session with the man:lttng-rotate(1) command. -Destroy a tracing session with the man:lttng-destroy(1) command. +Destroy a recording session with the man:lttng-destroy(1) command. [[modes]] -Tracing session modes -~~~~~~~~~~~~~~~~~~~~~ -As documented in man:lttng-concepts(7), LTTng offers four tracing +Recording session modes +~~~~~~~~~~~~~~~~~~~~~~~ +As documented in man:lttng-concepts(7), LTTng offers four recording session modes: [[local-mode]]Local mode:: @@ -135,7 +135,7 @@ With the option:--output='DIR' or option:--set-url=++file://++__DIR__ option::: Otherwise::: A subdirectory, under the `$LTTNG_HOME/lttng-traces` (`$LTTNG_HOME` defaults to `$HOME`) directory, of which the name contains the - tracing session name and the date/time. + recording session name and the date/time. [[network-streaming-mode]]Network streaming mode:: Send the trace data over the network to a listening relay daemon @@ -153,20 +153,20 @@ with the option:--ctrl-url and option:--data-url options (see the With this mode, LTTng: + With the option:--no-output option::: - Does :not: add any snapshot output to the created tracing + Does :not: add any snapshot output to the created recording session. With the option:--output option, the option:--set-url option, or the option:--ctrl-url and option:--data-url options::: Adds a snapshot output named `snapshot-1` using the provided - path or URL(s) to the created tracing session. + path or URL(s) to the created recording session. Otherwise::: Adds an automatic snapshot output named `snapshot-1` to the created - tracing session. + recording session. + The automatic snapshot output is a subdirectory, under the `$LTTNG_HOME/lttng-traces` (`$LTTNG_HOME` defaults to `$HOME`) -directory, of which the name contains the tracing session name and the +directory, of which the name contains the recording session name and the date/time. [[live-mode]]Live mode (option:--live option):: @@ -194,9 +194,9 @@ file://'TRACEDIR' {nbsp} + The `file://` protocol targets the *local file system*: you may only use -such an URL with the option:--set-url option when you create the tracing -session in local or snapshot mode (see the ``<>'' section above). +such an URL with the option:--set-url option when you create the +recording session in local or snapshot mode (see the ``<>'' section above). + 'TRACEDIR'::: Absolute path to the directory containing the trace data on the @@ -208,9 +208,9 @@ Network format:: 'NETPROTO'://('HOST' | 'IPADDR')[:__CTRLPORT__[:__DATAPORT__]][/'TRACEDIR'] {nbsp} + -This format is only available when you create the tracing session in +This format is only available when you create the recording session in network streaming, snapshot (option:--snapshot), or live (option:--live) -mode (see the ``<>'' section above). +mode (see the ``<>'' section above). + 'NETPROTO'::: Network protocol, amongst: @@ -268,12 +268,12 @@ include::common-lttng-cmd-options-head.txt[] Mode selection ~~~~~~~~~~~~~~ -See the ``<>'' section above. +See the ``<>'' section above. At most one of: option:--live[='DELAYUS']:: - Create the tracing session in live mode. + Create the recording session in live mode. + The optional 'DELAYUS' argument is the maximum time (in µs) you can wait for the data to be flushed (sent to the connected LTTng relay daemon). @@ -287,7 +287,7 @@ The session daemon must be able to connect to a listening relay daemon (see man:lttng-relayd(8)). option:--snapshot:: - Create the tracing session in snapshot mode. + Create the recording session in snapshot mode. + This is equivalent to: + @@ -295,24 +295,24 @@ This is equivalent to: + -- With the option:--no-output option:: - Not adding any snapshot output after LTTng creates the tracing + Not adding any snapshot output after LTTng creates the recording session. With the option:--output option, the option:--set-url option, or the option:--ctrl-url and option:--data-url options:: Adding a snapshot output named `snapshot-1` using the provided path - or URL(s) immediately after LTTng creates the tracing session. + or URL(s) immediately after LTTng creates the recording session. Otherwise:: Adding an automatic snapshot output named `snapshot-1` immediately - after LTTng creates the tracing session. + after LTTng creates the recording session. + The automatic snapshot output is a subdirectory, under the `$LTTNG_HOME/lttng-traces` (`$LTTNG_HOME` defaults to `$HOME`) -directory, of which the name contains the tracing session name and the +directory, of which the name contains the recording session name and the date/time. -- -* Forcing all the channels to be created for the tracing session to be +* Forcing all the channels to be created for the recording session to be configured with the nloption:--override and nloption:--output=++mmap++ options (see man:lttng-enable-channel(1)). @@ -320,14 +320,14 @@ date/time. Output ~~~~~~ option:--no-output:: - Depending on the tracing session mode (see the ``<>'' section above): + Local mode::: Disable the file system output. Snapshot mode (option:--snapshot option)::: - Do :not: add a snapshot output after creating the tracing session. + Do :not: add a snapshot output after creating the recording session. option:-o 'DIR', option:--output='DIR':: Equivalent to option:--set-url=++file://++__DIR__. @@ -347,32 +347,32 @@ option:-C 'URL', option:--ctrl-url='URL':: + You must also use the option:--data-url option. + -Not available in local mode (see the ``<>'' -section above). +Not available in local mode (see the ``<>'' section above). + In snapshot mode, this is equivalent to using the nloption:--ctrl-url option of the `add-output` action of the man:lttng-snapshot(1) command -immediately after creating the tracing session. +immediately after creating the recording session. option:-D 'URL', option:--data-url='URL':: Set the trace data path URL to 'URL'. + You must also use the option:--ctrl-url option. + -Not available in local mode (see the ``<>'' -section above). +Not available in local mode (see the ``<>'' section above). + In snapshot mode, this is equivalent to using the nloption:--data-url option of the `add-output` action of the man:lttng-snapshot(1) command -immediately after creating the tracing session. +immediately after creating the recording session. option:-U 'URL', option:--set-url='URL':: Set the destination URL of the control path and trace data to 'URL'. + -This URL remains unchanged as long as the tracing session exists. +This URL remains unchanged as long as the recording session exists. + -Depending on the tracing session mode (see the ``<>'' section above): +Depending on the recording session mode (see the ``<>'' section above): + Local mode::: 'URL' must start with `file://`, followed with the destination @@ -385,7 +385,7 @@ Network streaming and live modes::: Snapshot mode (option:--snapshot option)::: Equivalent to using the 'URL' non-option argument of the `add-output` action of the man:lttng-snapshot(1) command immediately - after creating the tracing session. + after creating the recording session. include::common-lttng-cmd-help-options.txt[] @@ -397,7 +397,7 @@ include::common-lttng-cmd-after-options.txt[] [[examples]] EXAMPLES -------- -.Create a normal mode tracing session with a generated name. +.Create a normal mode recording session with a generated name. ==== [role="term"] ---- @@ -405,7 +405,7 @@ $ lttng create ---- ==== -.Create a normal mode tracing session with a custom name. +.Create a normal mode recording session with a custom name. ==== [role="term"] ---- @@ -413,7 +413,7 @@ $ lttng create my-session ---- ==== -.Create a normal mode tracing session with a specific output directory. +.Create a normal mode recording session with a specific output directory. ==== See the option:--output option. @@ -423,7 +423,7 @@ $ lttng create --output=/path/to/traces ---- ==== -.Create a network streaming mode tracing session. +.Create a network streaming mode recording session. ==== See the ``Output directory'' section of man:lttng-relayd(8) to understand where the relay daemon to connect to (`10.0.0.242`) writes @@ -437,7 +437,7 @@ $ lttng create --set-url=net://10.0.0.242/inv4 ---- ==== -.Create a snapshot mode tracing session with a default snapshot output. +.Create a snapshot mode recording session with a default snapshot output. ==== See the option:--snapshot option. @@ -447,7 +447,7 @@ $ lttng create --snapshot ---- ==== -.Create a snapshot mode tracing session with a custom snapshot output. +.Create a snapshot mode recording session with a custom snapshot output. ==== See the option:--snapshot and option:--set-url options. @@ -458,7 +458,7 @@ $ lttng create --snapshot \ ---- ==== -.Create a snapshot mode tracing session with no snapshot output. +.Create a snapshot mode recording session with no snapshot output. ==== See the option:--snapshot and option:--no-output options. @@ -468,7 +468,7 @@ $ lttng create --snapshot --no-output ---- ==== -.Create an LTTng live mode tracing session with a default relay daemon URL. +.Create an LTTng live mode recording session with a default relay daemon URL. ==== See the option:--live option. @@ -478,7 +478,7 @@ $ lttng create --live ---- ==== -.Create an LTTng live mode tracing session with a custom live timer period and relay daemon URL. +.Create an LTTng live mode recording session with a custom live timer period and relay daemon URL. ==== See the option:--live and option:--set-url options. @@ -489,7 +489,7 @@ $ lttng create --live=250000 \ ---- ==== -.Create a normal mode tracing session with a custom directory containing the ring buffer shared memory files. +.Create a normal mode recording session with a custom directory containing the ring buffer shared memory files. ==== See the option:--shm-path option. diff --git a/doc/man/lttng-destroy.1.txt b/doc/man/lttng-destroy.1.txt index 048809a52..457808dab 100644 --- a/doc/man/lttng-destroy.1.txt +++ b/doc/man/lttng-destroy.1.txt @@ -1,11 +1,11 @@ lttng-destroy(1) ================ -:revdate: 17 May 2021 +:revdate: 14 June 2021 NAME ---- -lttng-destroy - Destroy LTTng tracing sessions +lttng-destroy - Destroy LTTng recording sessions SYNOPSIS @@ -19,47 +19,47 @@ DESCRIPTION The `lttng destroy` command destroys: With the 'SESSION' argument:: - The tracing session named 'SESSION'. + The recording session named 'SESSION'. With the option:--all option:: - *All* the tracing sessions of the connected session daemon for your - Unix user, or for all users if your Unix user is `root`, as listed - in the output of `lttng list` (see man:lttng-list(1)). + *All* the recording sessions of the connected session daemon for + your Unix user, or for all users if your Unix user is `root`, as + listed in the output of `lttng list` (see man:lttng-list(1)). + See the ``Session daemon connection'' section of man:lttng(1) to learn how a user application connects to a session daemon. Otherwise:: - The current tracing session (see man:lttng-concepts(7) to learn more - about the current tracing session). + The current recording session (see man:lttng-concepts(7) to learn + more about the current recording session). + -In that case, the current tracing session becomes nonexistent. +In that case, the current recording session becomes nonexistent. -See man:lttng-concepts(7) to learn more about tracing sessions. +See man:lttng-concepts(7) to learn more about recording sessions. -``Destroying'' a tracing session means freeing the resources which the +``Destroying'' a recording session means freeing the resources which the LTTng daemons and tracers acquired for it, also making sure to flush all the recorded trace data to either the local file system or the connected -LTTng relay daemon (see man:lttng-relayd(8)), depending on the tracing +LTTng relay daemon (see man:lttng-relayd(8)), depending on the recording session mode. -The `destroy` command stops any tracing activity within the selected -tracing session(s). By default, the command runs an implicit -man:lttng-stop(1) command to ensure that the trace data of the tracing +The `destroy` command stops any recording activity within the selected +recording session(s). By default, the command runs an implicit +man:lttng-stop(1) command to ensure that the trace data of the recording session(s) is valid before it exits. Make the command exit immediately with the option:--no-wait option. In this case, however, the traces(s) might not be valid when the command exits, and there's no way to know when it/they become valid. -If, for a tracing session{nbsp}__TS__ to destroy with the `destroy` +If, for a recording session{nbsp}__RS__ to destroy with the `destroy` command, the following statements are true: * You don't specify the option:--no-wait option. * LTTng archived the current trace chunk (see man:lttng-concepts(7)) - of{nbsp}__TS__ at least once during its lifetime. + of{nbsp}__RS__ at least once during its lifetime. -Then all the subdirectories of the output directory of{nbsp}__TS__ +Then all the subdirectories of the output directory of{nbsp}__RS__ (local or remote) are considered trace chunk archives once the `destroy` command exits. In other words, it's safe to read them, modify them, move them, or remove then. @@ -71,13 +71,13 @@ include::common-lttng-cmd-options-head.txt[] option:-a, option:--all:: - Destroy all the tracing sessions of your Unix user, or of all users - if your Unix user is `root`, as listed in the output of - man:lttng-list(1), instead of the current tracing session or the - tracing session named 'SESSION'. + Destroy all the recording sessions of your Unix user, or of all + users if your Unix user is `root`, as listed in the output of + man:lttng-list(1), instead of the current recording session or the + recording session named 'SESSION'. option:-n, option:--no-wait:: - Do :not: ensure that the trace data of the tracing session(s) to + Do :not: ensure that the trace data of the recording session(s) to destroy is valid before exiting. @@ -90,7 +90,7 @@ include::common-lttng-cmd-after-options.txt[] [[examples]] EXAMPLES -------- -.Destroy the current tracing session. +.Destroy the current recording session. ==== [role="term"] ---- @@ -98,7 +98,7 @@ $ lttng destroy ---- ==== -.Destroy the current tracing session without waiting for completion. +.Destroy the current recording session without waiting for completion. ==== See the option:--no-wait option. @@ -108,7 +108,7 @@ $ lttng destroy --no-wait ---- ==== -.Destroy a specific tracing session. +.Destroy a specific recording session. ==== [role="term"] ---- @@ -116,7 +116,7 @@ $ lttng destroy my-session ---- ==== -.Destroy all tracing sessions. +.Destroy all recording sessions. ==== See the option:--all option. diff --git a/doc/man/lttng-disable-channel.1.txt b/doc/man/lttng-disable-channel.1.txt index 60ad93647..244e9c4b1 100644 --- a/doc/man/lttng-disable-channel.1.txt +++ b/doc/man/lttng-disable-channel.1.txt @@ -1,6 +1,7 @@ lttng-disable-channel(1) ======================== -:revdate: 17 May 2021 +:revdate: 14 June 2021 + NAME ---- @@ -21,11 +22,11 @@ previously enabled with the man:lttng-enable-channel(1) command which belong to: With the option:--session='SESSION' option:: - The tracing session named 'SESSION'. + The recording session named 'SESSION'. Without the option:--session option:: - The current tracing session (see man:lttng-concepts(7) to learn more - about the current tracing session). + The current recording session (see man:lttng-concepts(7) to learn + more about the current recording session). See man:lttng-concepts(7) to learn more about channels. @@ -33,7 +34,7 @@ The `disable-channel` command disables one channel per 'CHANNEL' argument. As of LTTng{nbsp}{lttng_version}, you may :not: enable a disabled -channel once its tracing session has been started (see +channel once its recording session has been started (see man:lttng-start(1)) at least once. See the ``<>'' section below for usage examples. @@ -56,8 +57,8 @@ option:-u, option:--userspace:: Recording target ~~~~~~~~~~~~~~~~ option:-s 'SESSION', option:--session='SESSION':: - Disable one or more channels of the tracing session named 'SESSION' - instead of the current tracing session. + Disable one or more channels of the recording session named + 'SESSION' instead of the current recording session. include::common-lttng-cmd-help-options.txt[] @@ -69,7 +70,7 @@ include::common-lttng-cmd-after-options.txt[] [[examples]] EXAMPLES -------- -.Disable one Linux kernel channel of the current tracing session. +.Disable one Linux kernel channel of the current recording session. ==== [role="term"] ---- @@ -77,7 +78,7 @@ $ lttng disable-channel --kernel my-channel ---- ==== -.Disable two user space channels of a specific tracing session. +.Disable two user space channels of a specific recording session. ==== See the option:--session option. diff --git a/doc/man/lttng-disable-event.1.txt b/doc/man/lttng-disable-event.1.txt index 710e6d9dc..da6eb2d21 100644 --- a/doc/man/lttng-disable-event.1.txt +++ b/doc/man/lttng-disable-event.1.txt @@ -1,6 +1,6 @@ lttng-disable-event(1) ====================== -:revdate: 17 May 2021 +:revdate: 14 June 2021 NAME @@ -36,11 +36,11 @@ event rules previously created with the man:lttng-enable-event(1) command which belong to: With the option:--session='SESSION' option:: - The tracing session named 'SESSION'. + The recording session named 'SESSION'. Without the option:--session option:: - The current tracing session (see man:lttng-concepts(7) to learn more - about the current tracing session). + The current recording session (see man:lttng-concepts(7) to learn + more about the current recording session). With the option:--channel='CHANNEL' option:: The channel named 'CHANNEL'. @@ -48,7 +48,7 @@ With the option:--channel='CHANNEL' option:: Without the option:--channel option:: The channel named `channel0`. + -If there's more than one channel for the selected tracing session and +If there's more than one channel for the selected recording session and domain, the `disable-event` command fails. See man:lttng-concepts(7) to learn more about recording event rules. @@ -64,7 +64,7 @@ condition option, the `disable-event` command disables one or more Linux kernel recording event rules regardless of their instrumentation point type. -List the recording event rules of a given tracing session +List the recording event rules of a given recording session and/or channel with the man:lttng-list(1) command. Without the option:--all-events option, the `disable-event` command @@ -74,7 +74,7 @@ disable, as listed in the output of `lttng list` (see man:lttng-list(1)). You may disable an enabled recording event rule regardless of the -activity (started or stopped) of its tracing session (see +activity (started or stopped) of its recording session (see man:lttng-start(1) and man:lttng-stop(1)). See the ``<>'' section below for usage examples. @@ -111,8 +111,8 @@ option:-c 'CHANNEL', option:--channel='CHANNEL':: 'CHANNEL' instead of `channel0`. option:-s 'SESSION', option:--session='SESSION':: - Disable recording event rules in the tracing session named 'SESSION' - instead of the current tracing session. + Disable recording event rules in the recording session named + 'SESSION' instead of the current recording session. Instrumentation point type condition @@ -163,7 +163,7 @@ include::common-lttng-cmd-after-options.txt[] [[examples]] EXAMPLES -------- -.Disable all Linux kernel tracepoint recording event rules in the default channel of the current tracing session. +.Disable all Linux kernel tracepoint recording event rules in the default channel of the current recording session. ==== See the option:--all-events option. @@ -173,7 +173,7 @@ $ lttng disable-event --kernel --tracepoint --all-events ---- ==== -.Disable specific Apache log4j recording event rules in the default channel of a specific tracing session. +.Disable specific Apache log4j recording event rules in the default channel of a specific recording session. ==== See the option:--session option. @@ -184,7 +184,7 @@ $ lttng disable-event --session=my-session --log4j \ ---- ==== -.Disable all user space recording event rules in a specific channel of the current tracing session. +.Disable all user space recording event rules in a specific channel of the current recording session. ==== See the option:--channel option. @@ -195,7 +195,7 @@ $ lttng disable-event --channel=my-channel --userspace \ ---- ==== -.Disable specific Linux kernel system call recording event rules in the default channel of the current tracing session. +.Disable specific Linux kernel system call recording event rules in the default channel of the current recording session. ==== [role="term"] ---- diff --git a/doc/man/lttng-disable-rotation.1.txt b/doc/man/lttng-disable-rotation.1.txt index b088c94f2..d719072e0 100644 --- a/doc/man/lttng-disable-rotation.1.txt +++ b/doc/man/lttng-disable-rotation.1.txt @@ -1,11 +1,11 @@ lttng-disable-rotation(1) ========================= -:revdate: 17 May 2021 +:revdate: 14 June 2021 NAME ---- -lttng-disable-rotation - Unset an LTTng tracing session rotation schedule +lttng-disable-rotation - Unset an LTTng recording session rotation schedule SYNOPSIS @@ -21,13 +21,13 @@ The `lttng disable-rotation` command unsets a rotation schedule, previously set with the man:lttng-enable-rotation(1) command, for: With the option:--session='SESSION' option:: - The tracing session named 'SESSION'. + The recording session named 'SESSION'. Without the option:--session option:: - The current tracing session (see man:lttng-concepts(7) to learn more - about the current tracing session). + The current recording session (see man:lttng-concepts(7) to learn + more about the current recording session). -See man:lttng-concepts(7) to learn more about the tracing session +See man:lttng-concepts(7) to learn more about the recording session rotation and trace chunk concepts. See the ``<>'' section below for usage examples. @@ -50,8 +50,8 @@ option:--timer:: Recording target ~~~~~~~~~~~~~~~~ option:-s 'SESSION', option:--session='SESSION':: - Unset a rotation schedule for the tracing session named 'SESSION' - instead of the current tracing session. + Unset a rotation schedule for the recording session named 'SESSION' + instead of the current recording session. include::common-lttng-cmd-help-options.txt[] @@ -63,7 +63,7 @@ include::common-lttng-cmd-after-options.txt[] [[examples]] EXAMPLES -------- -.Unset the size-based rotation schedule of the current tracing session. +.Unset the size-based rotation schedule of the current recording session. ==== See the option:--size option. @@ -73,7 +73,7 @@ $ lttng disable-rotation --size ---- ==== -.Unset the periodic rotation schedule of a specific tracing session. +.Unset the periodic rotation schedule of a specific recording session. ==== See the option:--timer and option:--session options. diff --git a/doc/man/lttng-enable-channel.1.txt b/doc/man/lttng-enable-channel.1.txt index 2428c8a96..58aecc102 100644 --- a/doc/man/lttng-enable-channel.1.txt +++ b/doc/man/lttng-enable-channel.1.txt @@ -1,6 +1,6 @@ lttng-enable-channel(1) ======================= -:revdate: 17 May 2021 +:revdate: 14 June 2021 NAME @@ -54,18 +54,18 @@ See man:lttng-concepts(7) to learn more about channels. The channel(s) to create or enable belong to: With the option:--session='SESSION' option:: - The tracing session named 'SESSION'. + The recording session named 'SESSION'. Without the option:--session option:: - The current tracing session (see man:lttng-concepts(7) to learn more - about the current tracing session). + The current recording session (see man:lttng-concepts(7) to learn + more about the current recording session). NOTE: The man:lttng-enable-event(1) command can automatically create a default channel when no channel exists for the provided tracing domain. See the ``<>'' section below for usage examples. -List the channels of a given tracing session with the +List the channels of a given recording session with the man:lttng-list(1) and man:lttng-status(1) commands. Disable an enabled channel with the man:lttng-disable-channel(1) @@ -78,16 +78,16 @@ operations with the `enable-channel` command: * Change an attribute of an existing channel. -* Enable a disabled channel once its tracing session has been active +* Enable a disabled channel once its recording session has been active (started; see man:lttng-start(1)) at least once. -* Create a channel once its tracing session has been active at least +* Create a channel once its recording session has been active at least once. * Create a user space channel with a given buffering scheme (option:--buffers-uid or option:--buffers-pid options) and create a second user space channel with a different buffering scheme in the - same tracing session. + same recording session. ==== @@ -108,8 +108,8 @@ option:-u, option:--userspace:: Recording target ~~~~~~~~~~~~~~~~ option:-s 'SESSION', option:--session='SESSION':: - Create or enable channels in the tracing session named 'SESSION' - instead of the current tracing session. + Create or enable channels in the recording session named 'SESSION' + instead of the current recording session. Buffering scheme @@ -356,10 +356,10 @@ include::common-lttng-cmd-after-options.txt[] [[examples]] EXAMPLES -------- -.Create a Linux kernel channel with default attributes in the current tracing session. +.Create a Linux kernel channel with default attributes in the current recording session. ==== The following command line only creates a new channel if `my-channel` -doesn't name an existing Linux kernel channel in the current tracing +doesn't name an existing Linux kernel channel in the current recording session. [role="term"] @@ -368,7 +368,7 @@ $ lttng enable-channel --kernel my-channel ---- ==== -.Create a user space channel with a per-process buffering scheme in a specific tracing session. +.Create a user space channel with a per-process buffering scheme in a specific recording session. ==== See the option:--session and option:--buffers-pid options. @@ -379,7 +379,7 @@ $ lttng enable-channel --session=my-session --userspace \ ---- ==== -.Create a Linux kernel channel in the current tracing session with four 32-MiB sub-buffers per ring buffer. +.Create a Linux kernel channel in the current recording session with four 32-MiB sub-buffers per ring buffer. ==== See the option:--num-subbuf and option:--subbuf-size options. @@ -390,7 +390,7 @@ $ lttng enable-channel --kernel my-channel \ ---- ==== -.Create a user space channel in the current tracing session with trace file rotation. +.Create a user space channel in the current recording session with trace file rotation. ==== See the option:--tracefile-count and option:--tracefile-size options. @@ -401,7 +401,7 @@ $ lttng enable-channel --userspace my-channel \ ---- ==== -.Enable two user space channels of a specific tracing session. +.Enable two user space channels of a specific recording session. ==== [role="term"] ---- diff --git a/doc/man/lttng-enable-event.1.txt b/doc/man/lttng-enable-event.1.txt index 2a8289697..94efe497c 100644 --- a/doc/man/lttng-enable-event.1.txt +++ b/doc/man/lttng-enable-event.1.txt @@ -1,6 +1,6 @@ lttng-enable-event(1) ===================== -:revdate: 25 May 2021 +:revdate: 14 June 2021 NAME @@ -61,11 +61,11 @@ events, recording event rules, and event records. The recording event rule(s) to create or enable belong to: With the option:--session='SESSION' option:: - The tracing session named 'SESSION'. + The recording session named 'SESSION'. Without the option:--session option:: - The current tracing session (see man:lttng-concepts(7) to learn more - about the current tracing session). + The current recording session (see man:lttng-concepts(7) to learn + more about the current recording session). With the option:--channel='CHANNEL' option:: The channel named 'CHANNEL'. @@ -73,13 +73,13 @@ With the option:--channel='CHANNEL' option:: Without the option:--channel option:: The channel named `channel0`. + -If there's already a channel for the selected tracing session and domain -which isn't named `channel0`, the `enable-event` command fails. +If there's already a channel for the selected recording session and +domain which isn't named `channel0`, the `enable-event` command fails. Otherwise, it automatically creates it. See the ``<>'' section below for usage examples. -List the recording event rules of a specific tracing session +List the recording event rules of a specific recording session and/or channel with the man:lttng-list(1) and man:lttng-status(1) commands. @@ -138,16 +138,16 @@ A channel is enabled on creation. + Enable a disabled channel with the man:lttng-enable-channel(1) command. -* The tracing session of{nbsp}__ER__ is active (started). +* The recording session of{nbsp}__ER__ is active (started). + -A tracing session is inactive (stopped) on creation. +A recording session is inactive (stopped) on creation. + -Start an inactive tracing session with the man:lttng-start(1) command. +Start an inactive recording session with the man:lttng-start(1) command. * The process for which LTTng creates{nbsp}__E__ is allowed to record events. + -All processes are allowed to record events on tracing session +All processes are allowed to record events on recording session creation. + Use the man:lttng-track(1) and man:lttng-untrack(1) commands to select @@ -612,7 +612,7 @@ The `enable-event` command can enable a disabled recording event rule, as listed in the output of the man:lttng-list(1) command. You may enable a disabled recording event rule regardless of the -activity (started or stopped) of its tracing session (see +activity (started or stopped) of its recording session (see man:lttng-start(1) and man:lttng-stop(1)). To enable a disabled recording event rule, run the `enable-event` @@ -655,8 +655,8 @@ option:-c 'CHANNEL', option:--channel='CHANNEL':: 'CHANNEL' instead of `channel0`. option:-s 'SESSION', option:--session='SESSION':: - Create or enable recording event rules in the tracing session named - 'SESSION' instead of the current tracing session. + Create or enable recording event rules in the recording session + named 'SESSION' instead of the current recording session. Instrumentation point type condition @@ -860,7 +860,7 @@ include::common-lttng-cmd-after-options.txt[] [[examples]] EXAMPLES -------- -.Create a recording event rule which matches all Linux system call events (current tracing session, default channel). +.Create a recording event rule which matches all Linux system call events (current recording session, default channel). ==== See the option:--all and option:--syscall options. @@ -870,7 +870,7 @@ $ lttng enable-event --kernel --all --syscall ---- ==== -.Create a recording event rule which matches user space tracepoint events named specifically (current tracing session, default channel). +.Create a recording event rule which matches user space tracepoint events named specifically (current recording session, default channel). ==== The recording event rule below matches all user space tracepoint events of which the name starts with `my_provider:msg`. @@ -881,7 +881,7 @@ $ lttng enable-event --userspace 'my_provider:msg*' ---- ==== -.Create three recording event rules which match Python logging events named specifically (current tracing session, default channel). +.Create three recording event rules which match Python logging events named specifically (current recording session, default channel). ==== [role="term"] ---- @@ -889,7 +889,7 @@ $ lttng enable-event --python server3,ui.window,user-mgmt ---- ==== -.Create a recording event rule which matches Apache log4j logging events with a specific log level range (current tracing session, specific channel). +.Create a recording event rule which matches Apache log4j logging events with a specific log level range (current recording session, specific channel). ==== See the option:--channel, option:--all, and option:--loglevel options. @@ -900,7 +900,7 @@ $ lttng enable-event --log4j --channel=my-loggers \ ---- ==== -.Create a recording event rule which matches specific Linux kprobe events (current tracing session, default channel). +.Create a recording event rule which matches specific Linux kprobe events (current recording session, default channel). ==== The recording event rule below matches the entry of `usb_disconnect()` Linux kernel function calls. The records of such events are named `usbd` @@ -914,7 +914,7 @@ $ lttng enable-event --kernel --probe=usb_disconnect usbd ---- ==== -.Create a recording event rule which matches Linux kernel tracepoint events which satisfy an event payload and context filter (specific tracing session, default channel). +.Create a recording event rule which matches Linux kernel tracepoint events which satisfy an event payload and context filter (specific recording session, default channel). ==== See the option:--session and option:--filter options. @@ -925,7 +925,7 @@ $ lttng enable-event --kernel --session=my-session 'sched_*' \ ---- ==== -.Enable two Linux kernel tracepoint recording event rules (current tracing session, specific channel). +.Enable two Linux kernel tracepoint recording event rules (current recording session, specific channel). ==== See the option:--channel option. diff --git a/doc/man/lttng-enable-rotation.1.txt b/doc/man/lttng-enable-rotation.1.txt index a607a5739..0aa9b09b8 100644 --- a/doc/man/lttng-enable-rotation.1.txt +++ b/doc/man/lttng-enable-rotation.1.txt @@ -1,11 +1,11 @@ lttng-enable-rotation(1) ======================== -:revdate: 17 May 2021 +:revdate: 14 June 2021 NAME ---- -lttng-enable-rotation - Set an LTTng tracing session rotation schedule +lttng-enable-rotation - Set an LTTng recording session rotation schedule SYNOPSIS @@ -17,17 +17,17 @@ SYNOPSIS DESCRIPTION ----------- -The `lttng enable-rotation` command sets a tracing session rotation +The `lttng enable-rotation` command sets a recording session rotation schedule for: With the option:--session='SESSION' option:: - The tracing session named 'SESSION'. + The recording session named 'SESSION'. Without the option:--session option:: - The current tracing session (see man:lttng-concepts(7) to learn more - about the current tracing session). + The current recording session (see man:lttng-concepts(7) to learn more + about the current recording session). -See man:lttng-concepts(7) to learn more about the tracing session +See man:lttng-concepts(7) to learn more about the recording session rotation and trace chunk concepts. With the option:--timer='PERIODUS' option, the `enable-rotation` command @@ -41,8 +41,8 @@ least 'SIZE'. For both the option:--timer and option:--size options, LTTng checks the schedule condition periodically using the monitor timers of the channels -of the selected tracing session (see the nloption:--monitor-timer option -of the man:lttng-enable-channel(1) command). This means that: +of the selected recording session (see the nloption:--monitor-timer +option of the man:lttng-enable-channel(1) command). This means that: * With the option:--timer='PERIODUS' option, LTTng can perform an automatic rotation when the elapsed time since the last automatic @@ -62,22 +62,22 @@ archive directory. See the ``<>'' section below for usage examples. -Unset a tracing session rotation schedule with the +Unset a recording session rotation schedule with the man:lttng-disable-rotation(1) command. [IMPORTANT] ==== You may only use the `enable-rotation` command when: -* The selected tracing session was created in normal mode or in network - streaming mode (see man:lttng-create(1)). +* The selected recording session was created in normal mode or in + network streaming mode (see man:lttng-create(1)). * No channel was created with a configured trace file count or size limit (see the nloption:--tracefile-size and nloption:--tracefile-count options of the man:lttng-enable-channel(1) command). -For a given tracing session, LTTng only performs an automatic rotation +For a given recording session, LTTng only performs an automatic rotation when it's not currently performing a rotation. ==== @@ -106,8 +106,8 @@ and `h`{nbsp}(hours) suffixes are supported. Recording target ~~~~~~~~~~~~~~~~ option:-s 'SESSION', option:--session='SESSION':: - Set a rotation schedule for the tracing session named 'SESSION' - instead of the current tracing session. + Set a rotation schedule for the recording session named 'SESSION' + instead of the current recording session. include::common-lttng-cmd-help-options.txt[] @@ -119,7 +119,7 @@ include::common-lttng-cmd-after-options.txt[] [[examples]] EXAMPLES -------- -.Set the size-based rotation schedule of the current tracing session. +.Set the size-based rotation schedule of the current recording session. ==== See the option:--size option. @@ -129,7 +129,7 @@ $ lttng disable-rotation --size=256M ---- ==== -.Set the periodic rotation schedule of a specific tracing session. +.Set the periodic rotation schedule of a specific recording session. ==== See the option:--timer and option:--session options. diff --git a/doc/man/lttng-list.1.txt b/doc/man/lttng-list.1.txt index 12b137697..e9c12ae43 100644 --- a/doc/man/lttng-list.1.txt +++ b/doc/man/lttng-list.1.txt @@ -1,26 +1,27 @@ lttng-list(1) ============= -:revdate: 17 May 2021 +:revdate: 14 June 2021 NAME ---- -lttng-list - List LTTng tracing sessions and instrumentation points +lttng-list - List LTTng recording sessions and instrumentation points SYNOPSIS -------- -List the tracing sessions: +List the recording sessions: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *list* -List the tracing domains of a tracing session with at least one channel: +List the tracing domains of a recording session with at least one +channel: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *list* option:--domain 'SESSION' -List the channels and recording event rules of a tracing session: +List the channels and recording event rules of a recording session: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *list* [option:--channel='CHANNEL'] 'SESSION' @@ -39,27 +40,27 @@ DESCRIPTION The `lttng list` command lists: Without arguments:: - The tracing sessions of your Unix user, or of all users + The recording sessions of your Unix user, or of all users if your Unix user is `root`, within the connected session daemon. + See the ``Session daemon connection'' section of man:lttng(1) to learn how a user application connects to a session daemon. + -The command shows tracing session properties such as their output +The command shows recording session properties such as their output directories/URLs and whether or not they're active. With the 'SESSION' argument:: With the option:--domain option::: - The tracing domains (with at least one channel) of the tracing + The tracing domains (with at least one channel) of the recording session named 'SESSION'. Without the option:--domain option::: With the option:--channel='CHANNEL' option:::: The recording event rules of the channel 'CHANNEL' of the - tracing session named 'SESSION'. + recording session named 'SESSION'. Without the option:--channel option:::: - The channels of the tracing session named 'SESSION' and + The channels of the recording session named 'SESSION' and their recording event rules. + Use the dedicated tracing domain options (option:--kernel, @@ -84,12 +85,12 @@ With the option:--jul, option:--log4j, and/or option:--python options:: Also list the available instrumentation point fields with the option:--fields option. -See man:lttng-concept(7) to learn more about tracing sessions, tracing +See man:lttng-concept(7) to learn more about recording sessions, tracing domains, channels, recording event rules, and instrumentation points. See the ``<>'' section below for usage examples. -List the channels and recording event rules of the current tracing +List the channels and recording event rules of the current recording session (see man:lttng-concept(7) to learn more) with the man:lttng-status(1) command. @@ -143,7 +144,7 @@ option:-c 'CHANNEL', option:--channel='CHANNEL':: Only available with the 'SESSION' argument. option:-d, option:--domain:: - Show the tracing domains with at least one channel of the tracing + Show the tracing domains with at least one channel of the recording session named 'SESSION'. option:-f, option:--fields:: @@ -164,7 +165,7 @@ include::common-lttng-cmd-after-options.txt[] [[examples]] EXAMPLES -------- -.List the tracing sessions. +.List the recording sessions. ==== [role="term"] ---- @@ -172,7 +173,7 @@ $ lttng list ---- ==== -.Show the details of a specific tracing session. +.Show the details of a specific recording session. ==== [role="term"] ---- @@ -198,7 +199,7 @@ $ lttng list --userspace --fields ---- ==== -.List the tracing domains of a specific tracing session having at least one channel. +.List the tracing domains of a specific recording session having at least one channel. ==== See the option:--domain option. @@ -208,7 +209,7 @@ $ lttng list --domain my-session ---- ==== -.Show the details of a specific channel in a specific tracing session. +.Show the details of a specific channel in a specific recording session. ==== See the option:--channel option. diff --git a/doc/man/lttng-load.1.txt b/doc/man/lttng-load.1.txt index 4a0ffa8f4..4cf5c0411 100644 --- a/doc/man/lttng-load.1.txt +++ b/doc/man/lttng-load.1.txt @@ -1,11 +1,11 @@ lttng-load(1) ============= -:revdate: 17 May 2021 +:revdate: 14 June 2021 NAME ---- -lttng-load - Load LTTng tracing session configurations +lttng-load - Load LTTng recording session configurations SYNOPSIS @@ -18,21 +18,21 @@ SYNOPSIS DESCRIPTION ----------- The `lttng load` command loads the configurations of one or more -tracing sessions from files. +recording sessions from files. -See man:lttng-concepts(7) to learn more about tracing sessions. +See man:lttng-concepts(7) to learn more about recording sessions. Use the `load` command in conjunction with the man:lttng-save(1) command -to save and restore the complete configurations of tracing sessions. A -tracing session configuration includes the enabled channels and -recording event rules, the context fields to be recorded, the tracing +to save and restore the complete configurations of recording sessions. A +recording session configuration includes the enabled channels and +recording event rules, the context fields to be recorded, the recording activity, and more. -Once LTTng loads one or more tracing session configurations, they appear -exactly as they were saved from the user's point of view. +Once LTTng loads one or more recording session configurations, they +appear exactly as they were saved from the user's point of view. LTTng searches the following directories, non-recursively, in this order -for tracing session configuration files: +for recording session configuration files: . `$LTTNG_HOME/.lttng/sessions` (`$LTTNG_HOME` defaults to `$HOME`) . +{system_sessions_dir}+ @@ -43,33 +43,33 @@ this option, LTTng does :not: search the default directories above. A directory:: With the 'SESSION' argument::: - LTTng searches for the tracing session configuration named + LTTng searches for the recording session configuration named 'SESSION' in all the files of the directory 'PATH' and loads it if found. Without the 'SESSION' argument::: - The option:--all option is implicit: LTTng loads all the tracing - session configurations found in all the files in the directory - 'PATH'. + The option:--all option is implicit: LTTng loads all the + recording session configurations found in all the files in the + directory 'PATH'. A file:: With the 'SESSION' argument::: - LTTng searches for the tracing session configuration named + LTTng searches for the recording session configuration named 'SESSION' in the file 'PATH' and loads it if found. Without the 'SESSION' argument::: - The option:--all option is implicit: LTTng loads all the tracing - session configurations found in the file 'PATH'. + The option:--all option is implicit: LTTng loads all the + recording session configurations found in the file 'PATH'. -Override the output URL of the loaded tracing session configurations +Override the output URL of the loaded recording session configurations with the option:--override-url option. -With the 'SESSION' argument, override the name of the loaded tracing +With the 'SESSION' argument, override the name of the loaded recording session configuration with the option:--override-name option. -By default, the `load` command does :not: overwrite existing tracing +By default, the `load` command does :not: overwrite existing recording sessions: the command fails. Allow the `load` command to overwrite -existing tracing sessions with the option:--force option. +existing recording sessions with the option:--force option. See the ``<>'' section below for usage examples. @@ -78,28 +78,28 @@ include::common-lttng-cmd-options-head.txt[] option:-a, option:--all:: - Load all the tracing session configurations (default). + Load all the recording session configurations (default). option:-f, option:--force:: - Overwrite existing tracing sessions when loading. + Overwrite existing recording sessions when loading. option:-i 'PATH', option:--input-path='PATH':: - Load tracing session configurations from 'PATH', either a directory - or a file, instead of loading them from the default search + Load recording session configurations from 'PATH', either a + directory or a file, instead of loading them from the default search directories. option:--override-name='NAME':: - Override the name of the loaded tracing session configuration, + Override the name of the loaded recording session configuration, 'SESSION', with 'NAME'. option:--override-url='URL':: - Override the output URL of the loaded tracing session configurations - with 'URL'. + Override the output URL of the loaded recording session + configurations with 'URL'. + This is the equivalent of the nloption:--set-url option of man:lttng-create(1). The validity of the URL override depends on the -type of tracing session configurations to load. This option applies to -_all_ the loaded tracing session configurations. +type of recording session configurations to load. This option applies to +_all_ the loaded recording session configurations. include::common-lttng-cmd-help-options.txt[] @@ -111,7 +111,7 @@ include::common-lttng-cmd-after-options.txt[] [[examples]] EXAMPLES -------- -.Load all the tracing session configurations from the default search directories. +.Load all the recording session configurations from the default search directories. ==== [role="term"] ---- @@ -119,7 +119,7 @@ $ lttng load ---- ==== -.Load all the tracing session configurations from a specific directory. +.Load all the recording session configurations from a specific directory. ==== See the option:--input-path option. @@ -129,7 +129,7 @@ $ lttng load --input-path=/path/to/sessions ---- ==== -.Load a specific tracing session configuration from the default search directories. +.Load a specific recording session configuration from the default search directories. ==== [role="term"] ---- @@ -137,7 +137,7 @@ $ lttng load my-session ---- ==== -.Allow LTTng to overwrite existing tracing sessions when loading. +.Allow LTTng to overwrite existing recording sessions when loading. ==== See the option:--force option. @@ -147,7 +147,7 @@ $ lttng load --force ---- ==== -.Load a specific tracing session configuration from a specific file, overriding its name. +.Load a specific recording session configuration from a specific file, overriding its name. ==== See the option:--input-path and option:--override-name options. diff --git a/doc/man/lttng-metadata.1.txt b/doc/man/lttng-metadata.1.txt index e2dfde623..b4f1c401b 100644 --- a/doc/man/lttng-metadata.1.txt +++ b/doc/man/lttng-metadata.1.txt @@ -1,11 +1,11 @@ lttng-metadata(1) ================= -:revdate: 30 April 2021 +:revdate: 14 June 2021 NAME ---- -lttng-metadata - Manage the metadata generation of an LTTng tracing session +lttng-metadata - Manage the metadata generation of an LTTng recording session SYNOPSIS @@ -24,9 +24,9 @@ include::common-lttng-cmd-options-head.txt[] option:-s 'SESSION', option:--session='SESSION':: - Manage the metadata generation of the tracing session named - 'SESSION' instead of the current tracing session (see - man:lttng-concepts(7) to learn more about the current tracing + Manage the metadata generation of the recording session named + 'SESSION' instead of the current recording session (see + man:lttng-concepts(7) to learn more about the current recording session). diff --git a/doc/man/lttng-regenerate.1.txt b/doc/man/lttng-regenerate.1.txt index b1cdc054c..5338fc06f 100644 --- a/doc/man/lttng-regenerate.1.txt +++ b/doc/man/lttng-regenerate.1.txt @@ -1,21 +1,21 @@ lttng-regenerate(1) =================== -:revdate: 17 May 2021 +:revdate: 14 June 2021 NAME ---- -lttng-regenerate - Regenerate specific data of an LTTng tracing session +lttng-regenerate - Regenerate specific data of an LTTng recording session SYNOPSIS -------- -Regenerate the metadata of a tracing session: +Regenerate the metadata of a recording session: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *regenerate metadata* [option:--session='SESSION'] -Regenerate the state dump event records of a tracing session: +Regenerate the state dump event records of a recording session: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *regenerate statedump* [option:--session='SESSION'] @@ -26,13 +26,13 @@ DESCRIPTION The `lttng regenerate` command regenerates specific data of: With the option:--session='SESSION' option:: - The tracing session named 'SESSION'. + The recording session named 'SESSION'. Without the option:--session option:: - The current tracing session (see man:lttng-concepts(7) to learn more - about the current tracing session). + The current recording session (see man:lttng-concepts(7) to learn + more about the current recording session). -See man:lttng-concepts(7) to learn more about tracing sessions. +See man:lttng-concepts(7) to learn more about recording sessions. As of this version, the `metadata` and `statedump` targets are available. @@ -40,29 +40,28 @@ available. See the ``<>'' section below for usage examples. -Regenerate the metadata of a tracing session -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Regenerate the metadata of a recording session +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Use the `metadata` target to resample the offset between the monotonic clock and the wall time of the system, and then regenerate the metadata stream files. -More specifically, you may want to resample the wall time -following a major -link:https://en.wikipedia.org/wiki/Network_Time_Protocol[NTP] +More specifically, you may want to resample the wall time following a +major link:https://en.wikipedia.org/wiki/Network_Time_Protocol[NTP] correction. As such, LTTng can trace a system booting with an incorrect wall time before its wall time is NTP-corrected. Regenerating the -metadata of the selected tracing session ensures that trace readers can -accurately determine the event record timestamps relative to the +metadata of the selected recording session ensures that trace readers +can accurately determine the event record timestamps relative to the Unix epoch. Note that if you plan to rotate (see man:lttng-concepts(7) to learn -more) the selected tracing session, this target only regenerates the +more) the selected recording session, this target only regenerates the metadata stream files of the current and next trace chunks. [IMPORTANT] ==== You can only use the `metadata` target when the selected -tracing session: +recording session: * Is not in live mode (nloption:--live option of man:lttng-create(1)). @@ -75,12 +74,12 @@ See man:lttng-concepts(7) to learn more about channels. ==== -Regenerate the state dump event records of a tracing session -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Regenerate the state dump event records of a recording session +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Use the `statedump` target to collect up-to-date state dump information and create corresponding event records. -This is particularly useful if the selected tracing session is in +This is particularly useful if the selected recording session is in snapshot mode (nloption:--snapshot option of the man:lttng-create(1) command) or if LTTng rotates trace files for one of its channels (see man:lttng-concepts(7)): in both cases, the state dump information may be @@ -91,8 +90,8 @@ include::common-lttng-cmd-options-head.txt[] option:-s 'SESSION', option:--session='SESSION':: - Regenerate specific data of the tracing session named 'SESSION' - instead of the current tracing session. + Regenerate specific data of the recording session named 'SESSION' + instead of the current recording session. include::common-lttng-cmd-help-options.txt[] @@ -104,7 +103,7 @@ include::common-lttng-cmd-after-options.txt[] [[examples]] EXAMPLES -------- -.Regenerate the metadata of the current tracing session. +.Regenerate the metadata of the current recording session. ==== [role="term"] ---- @@ -112,7 +111,7 @@ $ lttng regenerate metadata ---- ==== -.Regenerate the state dump event records of a specific tracing session. +.Regenerate the state dump event records of a specific recording session. ==== See the option:--session option. diff --git a/doc/man/lttng-relayd.8.txt b/doc/man/lttng-relayd.8.txt index d165d93eb..4a51e15ba 100644 --- a/doc/man/lttng-relayd.8.txt +++ b/doc/man/lttng-relayd.8.txt @@ -1,6 +1,6 @@ lttng-relayd(8) =============== -:revdate: 30 April 2021 +:revdate: 14 June 2021 :daemon-bin-name: lttng-relayd :daemon-ini-section: relayd @@ -29,7 +29,7 @@ data from (possibly remote) LTTng session/consumer daemons and which writes it to the local file system. The relay daemon also accepts LTTng live connections from compatible readers (for example, man:babeltrace2(1)); this is the recommended approach to read trace data -while the remote tracing session is active. +while the remote recording session is active. By default, a relay daemon listens on all network interfaces to receive trace data, but only on `localhost` for LTTng live connections. Override @@ -72,7 +72,7 @@ The relay daemon uses different output path patterns depending on: + See the ``<>'' section above. -* The tracing session configuration of the connected peer. +* The recording session configuration of the connected peer. * The LTTng session daemon (see man:lttng-sessiond(8)) version of the connected peer. @@ -86,10 +86,10 @@ Consider the following variables: Hostname of the connected peer. 'SESSION':: - Tracing session name. + Recording session name. 'DATETIME':: - Unique tracing session date/time. + Unique recording session date/time. 'TRACEDIR':: Custom trace directory path ('TRACEDIR' part of the argument of the @@ -112,7 +112,7 @@ With a custom trace directory::: [verse] 'BASE'/'HOSTNAME'/'TRACEDIR' -With the option:--group-output-by-session option (tracing session grouping):: +With the option:--group-output-by-session option (recording session grouping):: Without a custom trace directory::: 'SESSIONDV' is at least{nbsp}2.4:::: + @@ -240,8 +240,8 @@ As of LTTng{nbsp}{lttng_version}, this is the default output grouping strategy, but this may change in the future. option:-s, option:--group-output-by-session:: - Group the written trace directories by tracing session name instead - of by hostname. + Group the written trace directories by recording session name + instead of by hostname. option:-o 'DIR', option:--output='DIR':: Set the base output directory of the written trace directories to diff --git a/doc/man/lttng-rotate.1.txt b/doc/man/lttng-rotate.1.txt index 91df503fe..b994d7def 100644 --- a/doc/man/lttng-rotate.1.txt +++ b/doc/man/lttng-rotate.1.txt @@ -1,11 +1,11 @@ lttng-rotate(1) =============== -:revdate: 17 May 2021 +:revdate: 14 June 2021 NAME ---- -lttng-rotate - Archive the current trace chunk of an LTTng tracing session +lttng-rotate - Archive the current trace chunk of an LTTng recording session SYNOPSIS @@ -20,29 +20,29 @@ The `lttng rotate` command archives to the file system the current trace chunk of: With the 'SESSION' argument:: - The tracing session named 'SESSION'. + The recording session named 'SESSION'. Without the 'SESSION' argument:: - The current tracing session (see man:lttng-concepts(7) to learn more - about the current tracing session). + The current recording session (see man:lttng-concepts(7) to learn + more about the current recording session). -This action is called a _tracing session rotation_. +This action is called a _recording session rotation_. -See man:lttng-concepts(7) to learn more about the tracing session +See man:lttng-concepts(7) to learn more about the recording session rotation and trace chunk concepts. You can use the `rotate` command: -* Any time the tracing session is active. +* Any time the recording session is active. -* A single time once the tracing session becomes inactive. +* A single time once the recording session becomes inactive. See man:lttng-concepts(7) to learn more about the activity of a -tracing session. +recording session. By default, the `rotate` command ensures that LTTng finished performing -the tracing session rotation before it prints the path of the archived -trace chunk and exits. The printed path is absolute when the tracing +the recording session rotation before it prints the path of the archived +trace chunk and exits. The printed path is absolute when the recording session was created in normal mode and relative to the base output directory of the relay daemon (see the nloption:--output option of man:lttng-relayd(8)) when it was created in network streaming mode (see @@ -53,14 +53,14 @@ this case, there's no easy way to know when the current trace chunk becomes archived, and the command does :not: print the path of the archived trace chunk. -Because LTTng flushes the current sub-buffers of the selected tracing -session when it performs a tracing session rotation, archived trace +Because LTTng flushes the current sub-buffers of the selected recording +session when it performs a recording session rotation, archived trace chunks are never redundant, that is, they do not overlap over time like snapshots can (see man:lttng-snapshot(1)). Also, a rotation does :not: directly cause discarded event records or packets. -A `rotate-session` trigger action can also rotate a tracing session (see -man:lttng-add-trigger(1)). +A `rotate-session` trigger action can also rotate a recording session +(see man:lttng-add-trigger(1)). See the ``<>'' section below for usage examples. @@ -68,8 +68,8 @@ See the ``<>'' section below for usage examples. ==== You may only use the `rotate` command when: -* The selected tracing session was created in normal mode or in network - streaming mode (see man:lttng-create(1)). +* The selected recording session was created in normal mode or in + network streaming mode (see man:lttng-create(1)). * No channel was created with a configured trace file count or size limit (see the nloption:--tracefile-size and @@ -85,7 +85,7 @@ include::common-lttng-cmd-options-head.txt[] option:-n, option:--no-wait:: - Do not ensure that the tracing session rotation operation is + Do not ensure that the recording session rotation operation is completed before exiting. @@ -98,7 +98,7 @@ include::common-lttng-cmd-after-options.txt[] [[examples]] EXAMPLES -------- -.Rotate the current tracing session. +.Rotate the current recording session. ==== [role="term"] ---- @@ -106,7 +106,7 @@ $ lttng rotate ---- ==== -.Rotate a specific tracing session. +.Rotate a specific recording session. ==== [role="term"] ---- @@ -114,7 +114,7 @@ $ lttng rotate my-session ---- ==== -.Rotate the current tracing session without waiting for completion. +.Rotate the current recording session without waiting for completion. ==== See the option:--no-wait option. diff --git a/doc/man/lttng-save.1.txt b/doc/man/lttng-save.1.txt index 26e350dbc..b5dd8daea 100644 --- a/doc/man/lttng-save.1.txt +++ b/doc/man/lttng-save.1.txt @@ -1,11 +1,11 @@ lttng-save(1) ============= -:revdate: 17 May 2021 +:revdate: 14 June 2021 NAME ---- -lttng-save - Save LTTng tracing session configurations +lttng-save - Save LTTng recording session configurations SYNOPSIS @@ -20,10 +20,10 @@ DESCRIPTION The `lttng save` command saves to files the configurations of: With the 'SESSION' argument:: - The tracing session named 'SESSION'. + The recording session named 'SESSION'. Without the 'SESSION' argument:: - Implicit option:--all option: *all* the tracing sessions of the + Implicit option:--all option: *all* the recording sessions of the connected session daemon for your Unix user, or for all users if your Unix user is `root`, as listed in the output of `lttng list` (see man:lttng-list(1)). @@ -31,24 +31,24 @@ Without the 'SESSION' argument:: See the ``Session daemon connection'' section of man:lttng(1) to learn how a user application connects to a session daemon. -See man:lttng-concepts(7) to learn more about tracing sessions. +See man:lttng-concepts(7) to learn more about recording sessions. Use the `save` command in conjunction with the man:lttng-load(1) command -to save and restore the complete configurations of tracing sessions. +to save and restore the complete configurations of recording sessions. -The `save` command does :not: save tracing data, only the tracing +The `save` command does :not: save tracing data, only the recording session parameters, including the channel and recording event rule configurations. The default output directory path is `$LTTNG_HOME/.lttng/sessions` (`$LTTNG_HOME` defaults to `$HOME`). Override the default output -directory path with the option:--output-path option. Each tracing +directory path with the option:--output-path option. Each recording session configuration file is named __SNAME__++.lttng++, -where{nbsp}__SNAME__ is the original tracing session name. +where{nbsp}__SNAME__ is the original recording session name. -By default, the `save` command does :not: overwrite existing tracing +By default, the `save` command does :not: overwrite existing recording session configuration files: the command fails. Allow the `save` command -to overwrite existing tracing session configuration files with the +to overwrite existing recording session configuration files with the option:--force option. See the ``<>'' section below for usage examples. @@ -58,17 +58,17 @@ include::common-lttng-cmd-options-head.txt[] option:-a, option:--all:: - Save all the tracing session configurations of your Unix user, or of - all users if your Unix user is `root`, as listed in the output of - man:lttng-list(1), instead of the current tracing session or the - tracing session named 'SESSION'. + Save all the recording session configurations of your Unix user, or + of all users if your Unix user is `root`, as listed in the output of + man:lttng-list(1), instead of the current recording session or the + recording session named 'SESSION'. option:-f, option:--force:: - Overwrite existing tracing session configuration files when + Overwrite existing recording session configuration files when saving. option:-o 'DIR', option:--output-path='DIR':: - Save tracing session configuration files to the directory 'DIR' + Save recording session configuration files to the directory 'DIR' instead of `$LTTNG_HOME/.lttng/sessions` (`$LTTNG_HOME` defaults to `$HOME`). @@ -82,7 +82,7 @@ include::common-lttng-cmd-after-options.txt[] [[examples]] EXAMPLES -------- -.Save all the tracing session configurations to the default output directory. +.Save all the recording session configurations to the default output directory. ==== [role="term"] ---- @@ -90,7 +90,7 @@ $ lttng save ---- ==== -.Save a specific tracing session configuration to a specific output directory. +.Save a specific recording session configuration to a specific output directory. ==== See the option:--output-path option. @@ -100,7 +100,7 @@ $ lttng save my-session --output-path=/path/to/sessions ---- ==== -.Allow LTTng to overwrite existing tracing session configuration files when saving. +.Allow LTTng to overwrite existing recording session configuration files when saving. ==== See the option:--force option. diff --git a/doc/man/lttng-sessiond.8.txt b/doc/man/lttng-sessiond.8.txt index fe8a9c66d..2bfce1c37 100644 --- a/doc/man/lttng-sessiond.8.txt +++ b/doc/man/lttng-sessiond.8.txt @@ -1,6 +1,6 @@ lttng-sessiond(8) ================= -:revdate: 21 April 2021 +:revdate: 14 June 2021 :daemon-bin-name: lttng-sessiond :daemon-ini-section: sessiond @@ -38,8 +38,8 @@ include::common-intro.txt[] An LTTng session daemon, `lttng-sessiond`, is a program which: -* Manages tracing sessions (see man:lttng-concepts(7) to learn more - about tracing sessions). +* Manages recording sessions (see man:lttng-concepts(7) to learn more + about recording sessions). * Controls the various components (like tracers and consumer daemons) of LTTng. @@ -98,10 +98,10 @@ extra-kmod-probes=my-driver,other-module [[load]] -Tracing session configuration loading -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -When the session daemon starts, it loads tracing session configurations -from: +Recording session configuration loading +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +When the session daemon starts, it loads recording session +configurations from: Without the option:--load option:: In this order: @@ -114,8 +114,8 @@ Without the option:--load option:: . All the files in +{system_sessions_auto_dir}+. -- + -`lttng-sessiond` only loads tracing configuration files from the -directories above if its UID and their UID are the same. +`lttng-sessiond` only loads recording session configuration files from +the directories above if its UID and their UID are the same. With the option:--load='PATH' option:: 'PATH' is a directory::: @@ -164,11 +164,11 @@ Members of the Unix tracing group may connect to the root session daemon and, therefore, control LTTng kernel tracing. option:-l 'PATH', option:--load='PATH':: - Load tracing session configurations from 'PATH', either a directory - or a file, instead of loading them from the default search + Load recording session configurations from 'PATH', either a + directory or a file, instead of loading them from the default search directories. + -See the ``<>'' section +See the ``<>'' section above. option:-S, option:--sig-parent:: @@ -380,7 +380,7 @@ variable. Set to `0` or `-1` to use the timeout of the operating system (default). `LTTNG_SESSION_CONFIG_XSD_PATH`:: - Tracing session configuration XML schema definition (XSD) path. + Recording session configuration XML schema definition (XSD) path. FILES @@ -396,18 +396,18 @@ Override this path with the nloption:--output option of the man:lttng-create(1) command. `$LTTNG_HOME/.lttng/sessions/auto`:: - Directory from which `lttng-sessiond` loads Unix user tracing + Directory from which `lttng-sessiond` loads Unix user recording session configurations when starting. + -See the ``<>'' section above -to learn more. +See the ``<>'' section +above to learn more. +{system_sessions_auto_dir}+:: - Directory from which `lttng-sessiond` loads system-wide tracing + Directory from which `lttng-sessiond` loads system-wide recording session configurations when starting. + -See the ``<>'' section above -to learn more. +See the ``<>'' section +above to learn more. `$LTTNG_HOME/.lttng/lttng.conf`:: Unix user's LTTng daemon INI configuration file. diff --git a/doc/man/lttng-set-session.1.txt b/doc/man/lttng-set-session.1.txt index 21663ddc3..c0ae89aa0 100644 --- a/doc/man/lttng-set-session.1.txt +++ b/doc/man/lttng-set-session.1.txt @@ -1,11 +1,11 @@ lttng-set-session(1) ==================== -:revdate: 29 April 2021 +:revdate: 14 June 2021 NAME ---- -lttng-set-session - Set the current LTTng tracing session +lttng-set-session - Set the current LTTng recording session SYNOPSIS @@ -16,15 +16,16 @@ SYNOPSIS DESCRIPTION ----------- -The `lttng set-session` command sets the current tracing session of your -Unix user to the tracing session named 'SESSION'. +The `lttng set-session` command sets the current recording session of your +Unix user to the recording session named 'SESSION'. -See man:lttng-concepts(7) to learn more about the current tracing session. +See man:lttng-concepts(7) to learn more about the current recording +session. The `set-session` command effectively updates the `$LTTNG_HOME/.lttngrc` file. -List the tracing sessions of your Unix user, or of all users if +List the recording sessions of your Unix user, or of all users if your Unix user is `root`, within the connected session daemon with the man:lttng-list(1) command. diff --git a/doc/man/lttng-snapshot.1.txt b/doc/man/lttng-snapshot.1.txt index 7886bbde5..1cf522f1d 100644 --- a/doc/man/lttng-snapshot.1.txt +++ b/doc/man/lttng-snapshot.1.txt @@ -1,35 +1,35 @@ lttng-snapshot(1) ================= -:revdate: 17 May 2021 +:revdate: 14 June 2021 NAME ---- -lttng-snapshot - Take a snapshot of an LTTng tracing session +lttng-snapshot - Take a snapshot of an LTTng recording session SYNOPSIS -------- -Take a tracing session snapshot: +Take a recording session snapshot: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot* *record* [option:--max-size='SIZE'] [option:--name='NAME'] [option:--session='SESSION'] [option:--ctrl-url='URL' option:--data-url='URL' | 'URL'] -Add a snapshot output to a tracing session: +Add a snapshot output to a recording session: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot* *add-output* [option:--max-size='SIZE'] [option:--name='NAME'] [option:--session='SESSION'] (option:--ctrl-url='URL' option:--data-url='URL' | 'URL') -Show the snapshot output of a tracing session: +Show the snapshot output of a recording session: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot* *list-output* [option:--session='SESSION'] -Remove the snapshot output from a tracing session: +Remove the snapshot output from a recording session: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot* *del-output* [option:--session='SESSION'] *1* @@ -41,40 +41,40 @@ The `lttng snapshot` command can take a snapshot of, add or remove a snapshot output, and show the snapshot output of: With the option:--session='SESSION' option:: - The tracing session named 'SESSION'. + The recording session named 'SESSION'. Without the option:--session option:: - The current tracing session (see man:lttng-concepts(7) to learn more - about the current tracing session). + The current recording session (see man:lttng-concepts(7) to learn more + about the current recording session). -See man:lttng-concepts(7) to learn more about tracing sessions. +See man:lttng-concepts(7) to learn more about recording sessions. A _snapshot_ is a dump of the current sub-buffers of all the channels of -the selected tracing session. +the selected recording session. When LTTng takes a snapshot, it sends the sub-buffer dump of the -selected tracing session to the local file system or over the network to -a listening relay daemon (man:lttng-relayd(8)). See the +selected recording session to the local file system or over the network +to a listening relay daemon (man:lttng-relayd(8)). See the ``<>'' section below to learn more. When LTTng takes a snapshot, it does :not: clear the sub-buffers of the -selected tracing session. In other words, different snapshots of the -selected tracing session can contain the same event records. +selected recording session. In other words, different snapshots of the +selected recording session can contain the same event records. -You must have created the selected tracing session in snapshot mode (see -the nloption:--snapshot option of the man:lttng-create(1) command as -well as man:lttng-concepts(7) to learn more about tracing session modes) -to use the `snapshot` command. +You must have created the selected recording session in snapshot mode +(see the nloption:--snapshot option of the man:lttng-create(1) command +as well as man:lttng-concepts(7) to learn more about recording session +modes) to use the `snapshot` command. -A `snapshot-session` trigger action can also take a tracing session +A `snapshot-session` trigger action can also take a recording session snapshot (see man:lttng-add-trigger(1)). See the ``<>'' section below for usage examples. If you want, instead, to keep all the trace data, but divide it into archived chunks which are then, like snapshots, ready to be processed, -see the tracing session rotation feature in man:lttng-concepts(7). Trace -chunk archives do :not: overlap like snapshots can. +see the recording session rotation feature in man:lttng-concepts(7). +Trace chunk archives do :not: overlap like snapshots can. [NOTE] ==== @@ -84,15 +84,15 @@ command. Otherwise, the snapshot could contain ``holes'', the result of the tracers overwriting unconsumed trace packets during the snapshot operation. -After LTTng writes the snapshot trace data, you can restart the tracing -session with the man:lttng-start(1) command. +After LTTng writes the snapshot trace data, you can restart the +recording session with the man:lttng-start(1) command. ==== [[output]] Snapshot output ~~~~~~~~~~~~~~~ -When you take a tracing session snapshot with the `record` action, LTTng +When you take a recording session snapshot with the `record` action, LTTng writes the snapshot trace files to: If you specify the 'URL' non-option argument or the option:--ctrl-url and option:--data-url options:: @@ -102,33 +102,33 @@ If you specify the 'URL' non-option argument or the option:--ctrl-url and option See man:lttng-create(1) for the format of 'URL'. Otherwise:: - The snapshot output of the selected tracing session. + The snapshot output of the selected recording session. + -Add a snapshot output to a tracing session with the `add-output` action. -As of LTTng{nbsp}{lttng_version}, you may only add one snapshot output -to a given tracing session. +Add a snapshot output to a recording session with the `add-output` +action. As of LTTng{nbsp}{lttng_version}, you may only add one snapshot +output to a given recording session. + -When you create a snapshot mode tracing session with the +When you create a snapshot mode recording session with the nloption:--snapshot option of the man:lttng-create(1) command, and without its nloption:--no-output option, the `create` command automatically adds a snapshot output named `snapshot-1` to the created -tracing session: +recording session: + -- With its nloption:--output, nloption:--set-url, nloption:--ctrl-url, or nloption:--data-url options:: Equivalent to using the `add-output` action with the provided or - equivalent URL(s) immediately after creating the tracing session. + equivalent URL(s) immediately after creating the recording session. Otherwise:: A subdirectory, under the `$LTTNG_HOME/lttng-traces` (`$LTTNG_HOME` defaults to `$HOME`) directory, of which the name contains the - tracing session name and the date/time. + recording session name and the date/time. -- + -Show the current snapshot output of a tracing session with the +Show the current snapshot output of a recording session with the `list-output` action. + -Remove the snapshot output of a tracing session with the +Remove the snapshot output of a recording session with the `del-output` action. For both the `record` and `add-output` actions: @@ -140,7 +140,7 @@ For both the `record` and `add-output` actions: to this output. * By default, the snapshot files can be as big as the sum of the sizes - of all the sub-buffers of all the channels of the selected tracing + of all the sub-buffers of all the channels of the selected recording session. + Set the maximum total size of all the snapshot trace files LTTng writes @@ -153,8 +153,8 @@ include::common-lttng-cmd-options-head.txt[] Recording target ~~~~~~~~~~~~~~~~ option:-s 'SESSION', option:--session='SESSION':: - Take a snapshot of the sub-buffers of the tracing session named - 'SESSION' instead of the current tracing session. + Take a snapshot of the sub-buffers of the recording session named + 'SESSION' instead of the current recording session. Output @@ -195,7 +195,7 @@ include::common-lttng-cmd-after-options.txt[] [[examples]] EXAMPLES -------- -.Take a snapshot of the current tracing session, sending the trace files to its snapshot output. +.Take a snapshot of the current recording session, sending the trace files to its snapshot output. ==== [role="term"] ---- @@ -203,7 +203,7 @@ $ lttng snapshot record ---- ==== -.Take a snapshot of a specific tracing session, giving it a custom name. +.Take a snapshot of a specific recording session, giving it a custom name. ==== See the option:--session and option:--name options. @@ -213,7 +213,7 @@ $ lttng snapshot record --session=my-session --name=SNAP ---- ==== -.Take a snapshot of the current tracing session, sending the trace files to a custom location. +.Take a snapshot of the current recording session, sending the trace files to a custom location. ==== See the ``Output directory'' section of man:lttng-relayd(8) to understand where the relay daemon to connect to (`3.96.87.215`) writes @@ -225,7 +225,7 @@ $ lttng snapshot record net://3.96.87.215 ---- ==== -.Replace the snapshot output of a specific tracing session with a local file system path. +.Replace the snapshot output of a specific recording session with a local file system path. ==== See the option:--session option. @@ -237,7 +237,7 @@ $ lttng snapshot add-output --session=monk \ ---- ==== -.Take a snapshot of the current tracing session, making sure its size is not over 4{nbsp}MiB. +.Take a snapshot of the current recording session, making sure its size is not over 4{nbsp}MiB. ==== See the option:--max-size option. diff --git a/doc/man/lttng-start.1.txt b/doc/man/lttng-start.1.txt index 0ee764e40..b595b2f5c 100644 --- a/doc/man/lttng-start.1.txt +++ b/doc/man/lttng-start.1.txt @@ -1,11 +1,11 @@ lttng-start(1) ============== -:revdate: 17 May 2021 +:revdate: 14 June 2021 NAME ---- -lttng-start - Start an LTTng tracing session +lttng-start - Start an LTTng recording session SYNOPSIS @@ -16,27 +16,27 @@ SYNOPSIS DESCRIPTION ----------- -The `lttng start` command starts a tracing session, that is, it +The `lttng start` command starts a recording session, that is, it activates the LTTng tracers for: With the 'SESSION' argument:: - The tracing session named 'SESSION'. + The recording session named 'SESSION'. Without the 'SESSION' argument:: - The current tracing session (see man:lttng-concepts(7) to learn more - about the current tracing session). + The current recording session (see man:lttng-concepts(7) to learn + more about the current recording session). -See man:lttng-concepts(7) to learn more about tracing sessions. +See man:lttng-concepts(7) to learn more about recording sessions. -The selected tracing session must be inactive (stopped). A tracing +The selected recording session must be inactive (stopped). A recording session is inactive on creation (see man:lttng-create(1)). -A `start-session` trigger action can also start a tracing session +A `start-session` trigger action can also start a recording session (see man:lttng-add-trigger(1)). See the ``<>'' section below for usage examples. -Stop an active tracing session with the man:lttng-stop(1) command. +Stop an active recording session with the man:lttng-stop(1) command. include::common-lttng-cmd-options-head.txt[] @@ -51,7 +51,7 @@ include::common-lttng-cmd-after-options.txt[] [[examples]] EXAMPLES -------- -.Start the current tracing session. +.Start the current recording session. ==== [role="term"] ---- @@ -59,7 +59,7 @@ $ lttng start ---- ==== -.Start a specific tracing session. +.Start a specific recording session. ==== [role="term"] ---- diff --git a/doc/man/lttng-status.1.txt b/doc/man/lttng-status.1.txt index c0d96da0d..557a2a076 100644 --- a/doc/man/lttng-status.1.txt +++ b/doc/man/lttng-status.1.txt @@ -1,11 +1,11 @@ lttng-status(1) =============== -:revdate: 29 April 2021 +:revdate: 14 June 2021 NAME ---- -lttng-status - Show the status of the current LTTng tracing session +lttng-status - Show the status of the current LTTng recording session SYNOPSIS @@ -16,16 +16,16 @@ SYNOPSIS DESCRIPTION ----------- -The `lttng status` command shows the status of the current tracing +The `lttng status` command shows the status of the current recording session (see man:lttng-concepts(7) to learn more about the current -tracing session). +recording session). This command is equivalent to: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *list* 'CURSESSION' -where `CURSESSION` is the name of the current tracing session. +where `CURSESSION` is the name of the current recording session. include::common-lttng-cmd-options-head.txt[] diff --git a/doc/man/lttng-stop.1.txt b/doc/man/lttng-stop.1.txt index 19da7e966..0ad1f0e3c 100644 --- a/doc/man/lttng-stop.1.txt +++ b/doc/man/lttng-stop.1.txt @@ -1,11 +1,11 @@ lttng-stop(1) ============= -:revdate: 17 May 2021 +:revdate: 14 June 2021 NAME ---- -lttng-stop - Stop an LTTng tracing session +lttng-stop - Stop an LTTng recording session SYNOPSIS @@ -16,41 +16,41 @@ SYNOPSIS DESCRIPTION ----------- -The `lttng stop` command stops a tracing session, that is, it +The `lttng stop` command stops a recording session, that is, it deactivates the LTTng tracers for: With the 'SESSION' argument:: - The tracing session named 'SESSION'. + The recording session named 'SESSION'. Without the 'SESSION' argument:: - The current tracing session (see man:lttng-concepts(7) to learn more - about the current tracing session). + The current recording session (see man:lttng-concepts(7) to learn more + about the current recording session). -See man:lttng-concepts(7) to learn more about tracing sessions. +See man:lttng-concepts(7) to learn more about recording sessions. -The selected tracing session must be active (started; see -man:lttng-start(1)). A tracing session is inactive on creation (see +The selected recording session must be active (started; see +man:lttng-start(1)). A recording session is inactive on creation (see man:lttng-create(1)). -A `stop-session` trigger action can also stop a tracing session (see +A `stop-session` trigger action can also stop a recording session (see man:lttng-add-trigger(1)). -Start an inactive tracing session with the man:lttng-start(1) command. +Start an inactive recording session with the man:lttng-start(1) command. By default, the `stop` command ensures that the trace data of the -selected tracing session is valid before it exits. Make the command exit -immediately with the option:--no-wait option. In this case, however, the -traces(s) might not be valid when the command exits, and there's no way -to know when it/they becomes valid. +selected recording session is valid before it exits. Make the command +exit immediately with the option:--no-wait option. In this case, +however, the traces(s) might not be valid when the command exits, and +there's no way to know when it/they becomes valid. If LTTng archived the current trace chunk (see man:lttng-rotate(1) and -man:lttng-enable-rotation(1)) of the selected tracing session at least +man:lttng-enable-rotation(1)) of the selected recording session at least once during its lifetime, the `stop` command renames the current trace chunk subdirectory and prints the renamed path. Although it's safe to -read the content of this renamed subdirectory while the tracing session -remains inactive, it's :not: a trace chunk archive: you need to destroy -the tracing session with man:lttng-destroy(1) or perform a rotation with -man:lttng-rotate(1) to archive it. +read the content of this renamed subdirectory while the recording +session remains inactive, it's :not: a trace chunk archive: you need to +destroy the recording session with man:lttng-destroy(1) or perform a +rotation with man:lttng-rotate(1) to archive it. See the ``<>'' section below for usage examples. @@ -59,8 +59,8 @@ include::common-lttng-cmd-options-head.txt[] option:-n, option:--no-wait:: - Do :not: ensure that the trace data of the selected tracing session - is valid before exiting. + Do :not: ensure that the trace data of the selected recording + session is valid before exiting. include::common-lttng-cmd-help-options.txt[] @@ -72,7 +72,7 @@ include::common-lttng-cmd-after-options.txt[] [[examples]] EXAMPLES -------- -.Stop the current tracing session. +.Stop the current recording session. ==== [role="term"] ---- @@ -80,7 +80,7 @@ $ lttng stop ---- ==== -.Stop a specific tracing session. +.Stop a specific recording session. ==== [role="term"] ---- @@ -88,7 +88,7 @@ $ lttng stop my-session ---- ==== -.Stop the current tracing session without waiting for completion. +.Stop the current recording session without waiting for completion. ==== See the option:--no-wait option. diff --git a/doc/man/lttng-track.1.txt b/doc/man/lttng-track.1.txt index 5c328c6e0..fd854c03c 100644 --- a/doc/man/lttng-track.1.txt +++ b/doc/man/lttng-track.1.txt @@ -1,6 +1,6 @@ lttng-track(1) ============== -:revdate: 17 May 2021 +:revdate: 14 June 2021 NAME @@ -41,17 +41,17 @@ The `lttng track` command allows one or more processes to record LTTng events based on their attributes within: With the option:--session='SESSION' option:: - The tracing session named 'SESSION'. + The recording session named 'SESSION'. Without the option:--session option:: - The current tracing session (see man:lttng-concepts(7) to learn more - about the current tracing session). + The current recording session (see man:lttng-concepts(7) to learn + more about the current recording session). -See man:lttng-concepts(7) to learn more about tracing sessions and +See man:lttng-concepts(7) to learn more about recording sessions and recording event rules. The `track` command adds values to _inclusion sets_ of process -attributes. The available inclusion sets are, for a given tracing +attributes. The available inclusion sets are, for a given recording session: With the option:--kernel option:: @@ -83,12 +83,12 @@ With the option:--userspace option:: When an event{nbsp}__E__ satisfies all the other explicit and implicit conditions of an event rule{nbsp}__ER__, __ER__ matches{nbsp}__E__ if the attributes of the process for which LTTng creates{nbsp}__E__ are -*all* part of the inclusion sets of the tracing session and domain +*all* part of the inclusion sets of the recording session and domain of{nbsp}__ER__. -By default, on tracing session creation (see man:lttng-create(1)), +By default, on recording session creation (see man:lttng-create(1)), all processes are allowed to record events. In other words, all the -inclusion sets of the tracing session contain all the possible +inclusion sets of the recording session contain all the possible process attribute values. If a given inclusion set{nbsp}__IS__ contains all the possible values @@ -120,7 +120,7 @@ command. Inclusion set example ~~~~~~~~~~~~~~~~~~~~~ This example operates on the Linux kernel process ID (PID) inclusion set -of the current tracing session to show how an inclusion set works. +of the current recording session to show how an inclusion set works. Assume the maximum system PID is 7 for this example. @@ -189,15 +189,15 @@ option:-u, option:--userspace:: Recording target ~~~~~~~~~~~~~~~~ option:-s 'SESSION', option:--session='SESSION':: - Add values to one or more inclusion sets of the tracing session - named 'SESSION' instead of the current tracing session. + Add values to one or more inclusion sets of the recording session + named 'SESSION' instead of the current recording session. Inclusion set selection ~~~~~~~~~~~~~~~~~~~~~~~ option:-p ['PID'[,'PID']...], option:--pid[='PID'[,'PID']...]:: For each 'PID' argument, add 'PID' to the process ID inclusion set - of the selected tracing session and domain. + of the selected recording session and domain. + 'PID' is the process ID attribute of a process as seen from the root PID namespace (see man:pid_namespaces(7)). @@ -206,14 +206,14 @@ Only available with option:--kernel option. option:--vpid[='VPID'[,'VPID']...]:: For each 'VPID' argument, add 'VPID' to the virtual process ID - inclusion set of the selected tracing session and domain. + inclusion set of the selected recording session and domain. + 'VPID' is the virtual process ID attribute of a process as seen from the PID namespace of the process (see man:pid_namespaces(7)). option:--uid[='USER'[,'USER']...]:: For each 'USER' argument, add 'USER' to the user ID inclusion set of - the selected tracing session and domain. + the selected recording session and domain. + 'USER' is either: + @@ -231,7 +231,7 @@ Only available with option:--kernel option. option:--vuid[='VUSER'[,'VUSER']...]:: For each 'VUSER' argument, add 'VUSER' to the virtual user ID - inclusion set of the selected tracing session and domain. + inclusion set of the selected recording session and domain. + 'VUSER' is either: + @@ -248,7 +248,7 @@ set. option:--gid[='GROUP'[,'GROUP']...]:: For each 'GROUP' argument, add 'GROUP' to the group ID - inclusion set of the selected tracing session and domain. + inclusion set of the selected recording session and domain. + 'GROUP' is either: + @@ -266,7 +266,7 @@ Only available with option:--kernel option. option:--vgid[='VGROUP'[,'VGROUP']...]:: For each 'VGROUP' argument, add 'VGROUP' to the virtual group ID - inclusion set of the selected tracing session and domain. + inclusion set of the selected recording session and domain. + 'VGROUP' is either: + @@ -299,7 +299,7 @@ include::common-lttng-cmd-after-options.txt[] [[examples]] EXAMPLES -------- -.Add the PIDs 1728 and 3775 to the Linux kernel process ID inclusion set of the current tracing session. +.Add the PIDs 1728 and 3775 to the Linux kernel process ID inclusion set of the current recording session. ==== See the option:--pid option. @@ -309,7 +309,7 @@ $ lttng track --kernel --pid=1728,3775 ---- ==== -.Add the ID of a specific user to the user space virtual user ID inclusion set of a specific tracing session. +.Add the ID of a specific user to the user space virtual user ID inclusion set of a specific recording session. ==== See the option:--vuid and option:--session options. @@ -319,7 +319,7 @@ $ lttng track --userspace --session=my-session --vuid=http ---- ==== -.Add all the possible group IDs to the Linux kernel group ID inclusion set of the current tracing session. +.Add all the possible group IDs to the Linux kernel group ID inclusion set of the current recording session. ==== See the option:--all and option:--gid options. diff --git a/doc/man/lttng-untrack.1.txt b/doc/man/lttng-untrack.1.txt index e70ef968b..9a485950c 100644 --- a/doc/man/lttng-untrack.1.txt +++ b/doc/man/lttng-untrack.1.txt @@ -1,6 +1,6 @@ lttng-untrack(1) ================ -:revdate: 17 May 2021 +:revdate: 14 June 2021 NAME @@ -40,13 +40,13 @@ The `lttng untrack` command disallows one or more processes to record LTTng events based on their attributes within: With the option:--session='SESSION' option:: - The tracing session named 'SESSION'. + The recording session named 'SESSION'. Without the option:--session option:: - The current tracing session (see man:lttng-concepts(7) to learn more - about the current tracing session). + The current recording session (see man:lttng-concepts(7) to learn + more about the current recording session). -See man:lttng-concepts(7) to learn more about tracing sessions and +See man:lttng-concepts(7) to learn more about recording sessions and recording event rules. The `untrack` command removes values from _inclusion sets_ of process @@ -57,10 +57,10 @@ See the ``<>'' section below for usage examples. Inclusion set example ~~~~~~~~~~~~~~~~~~~~~ -A common operation is to create a tracing session (see +A common operation is to create a recording session (see man:lttng-create(1)), remove all the entries from the Linux kernel -process ID inclusion set, start tracing, and then manually add PIDs -while the tracing session is active. +process ID inclusion set, start recording, and then manually add PIDs +while the recording session is active. Assume the maximum system PID is 7 for this example. @@ -137,15 +137,15 @@ option:-u, option:--userspace:: Recording target ~~~~~~~~~~~~~~~~ option:-s 'SESSION', option:--session='SESSION':: - Remove values from one or more inclusion sets of the tracing session - named 'SESSION' instead of the current tracing session. + Remove values from one or more inclusion sets of the recording + session named 'SESSION' instead of the current recording session. Inclusion set selection ~~~~~~~~~~~~~~~~~~~~~~~ option:-p ['PID'[,'PID']...], option:--pid[='PID'[,'PID']...]:: For each 'PID' argument, remove 'PID' from the process ID inclusion - set of the selected tracing session and domain. + set of the selected recording session and domain. + 'PID' is the process ID attribute of a process as seen from the root PID namespace (see man:pid_namespaces(7)). @@ -154,14 +154,14 @@ Only available with option:--kernel option. option:--vpid[='VPID'[,'VPID']...]:: For each 'VPID' argument, remove 'VPID' from the virtual process ID - inclusion set of the selected tracing session and domain. + inclusion set of the selected recording session and domain. + 'VPID' is the virtual process ID attribute of a process as seen from the PID namespace of the process (see man:pid_namespaces(7)). option:--uid[='USER'[,'USER']...]:: For each 'USER' argument, remove 'USER' from the user ID inclusion - set of the selected tracing session and domain. + set of the selected recording session and domain. + 'USER' is either: + @@ -179,7 +179,7 @@ Only available with option:--kernel option. option:--vuid[='VUSER'[,'VUSER']...]:: For each 'VUSER' argument, remove 'VUSER' from the virtual user ID - inclusion set of the selected tracing session and domain. + inclusion set of the selected recording session and domain. + 'VUSER' is either: + @@ -196,7 +196,7 @@ set. option:--gid[='GROUP'[,'GROUP']...]:: For each 'GROUP' argument, remove 'GROUP' from the group ID - inclusion set of the selected tracing session and domain. + inclusion set of the selected recording session and domain. + 'GROUP' is either: + @@ -214,7 +214,7 @@ Only available with option:--kernel option. option:--vgid[='VGROUP'[,'VGROUP']...]:: For each 'VGROUP' argument, remove 'VGROUP' from the virtual group - ID inclusion set of the selected tracing session and domain. + ID inclusion set of the selected recording session and domain. + 'VGROUP' is either: + @@ -247,7 +247,7 @@ include::common-lttng-cmd-after-options.txt[] [[examples]] EXAMPLES -------- -.Remove the PIDs 1728 and 3775 from the Linux kernel process ID inclusion set of the current tracing session. +.Remove the PIDs 1728 and 3775 from the Linux kernel process ID inclusion set of the current recording session. ==== See the option:--pid option. @@ -257,7 +257,7 @@ $ lttng untrack --kernel --pid=1728,3775 ---- ==== -.Remove the IDs of a specific groups from the user space virtual group ID inclusion set of a specific tracing session. +.Remove the IDs of a specific groups from the user space virtual group ID inclusion set of a specific recording session. ==== See the option:--vgid and option:--session options. @@ -268,7 +268,7 @@ $ lttng untrack --userspace --session=my-session \ ---- ==== -.Remove all the user IDs from the Linux kernel user ID inclusion set of the current tracing session. +.Remove all the user IDs from the Linux kernel user ID inclusion set of the current recording session. ==== See the option:--all and option:--uid options. diff --git a/doc/man/lttng-view.1.txt b/doc/man/lttng-view.1.txt index 0eccb30d1..02d788c5e 100644 --- a/doc/man/lttng-view.1.txt +++ b/doc/man/lttng-view.1.txt @@ -1,6 +1,6 @@ lttng-view(1) ============= -:revdate: 17 May 2021 +:revdate: 14 June 2021 NAME @@ -21,17 +21,17 @@ The `lttng view` command launches an external trace reader to read the current traces of: With the option:--session='SESSION' option:: - The tracing session named 'SESSION'. + The recording session named 'SESSION'. With the option:--trace-path='DIR' option:: The local file system directory 'DIR'. Otherwise:: - The current tracing session (see man:concepts(1) to learn more about - the current tracing session). + The current recording session (see man:concepts(1) to learn more + about the current recording session). With the option:--session option or without the option:--trace-path -option, the mode of the selected tracing session may :not: be network +option, the mode of the selected recording session may :not: be network streaming or live. By default, the `view` command attempts to launch man:babeltrace2(1) or, @@ -46,7 +46,7 @@ include::common-lttng-cmd-options-head.txt[] option:-t 'DIR', option:--trace-path='DIR':: Pass 'DIR' as the last argument of the trace reader command instead - of the output directory of the selected tracing session. + of the output directory of the selected recording session. option:-e 'READER', option:--viewer='READER':: Use the trace reader 'READER' to read the traces. @@ -68,7 +68,7 @@ include::common-lttng-cmd-after-options.txt[] [[examples]] EXAMPLES -------- -.Read the traces of the current tracing session with Babeltrace. +.Read the traces of the current recording session with Babeltrace. ==== [role="term"] ---- @@ -76,7 +76,7 @@ $ lttng view ---- ==== -.Read the traces of a specific tracing session with a custom trace reader. +.Read the traces of a specific recording session with a custom trace reader. ==== See the option:--viewer option. diff --git a/doc/man/lttng.1.txt b/doc/man/lttng.1.txt index fba24cee5..43b695c77 100644 --- a/doc/man/lttng.1.txt +++ b/doc/man/lttng.1.txt @@ -1,6 +1,6 @@ lttng(1) ======== -:revdate: 12 May 2021 +:revdate: 14 June 2021 NAME @@ -25,8 +25,8 @@ with the LTTng control library (`liblttng-ctl`), sends commands to a listening LTTng session daemon (man:lttng-sessiond(8)). A session daemon: -* Manages tracing sessions (see man:lttng-concepts(7) to learn more - about tracing sessions). +* Manages recording sessions (see man:lttng-concepts(7) to learn more + about recording sessions). * Controls the various components (like tracers and consumer daemons) of LTTng. @@ -185,8 +185,8 @@ COMMANDS The following commands also have their own nloption:--help option. -Tracing session -~~~~~~~~~~~~~~~ +Recording session +~~~~~~~~~~~~~~~~~ [options="header"] |=== |Command |Description diff --git a/doc/python-howto.txt b/doc/python-howto.txt index 5f7fcfbac..5a3c2683a 100644 --- a/doc/python-howto.txt +++ b/doc/python-howto.txt @@ -34,7 +34,7 @@ Quick example using Python to trace with LTTng. >>> lttng.create("session-name", "path/to/trace") -4) Create a handle for the tracing session and domain +4) Create a handle for the recording session and domain >>> domain = lttng.Domain() >>> domain.type = lttng.DOMAIN_KERNEL * @@ -63,7 +63,7 @@ Quick example using Python to trace with LTTng. >>> lttng.stop("session-name") -7) Destroy the tracing session +7) Destroy the recording session >>> lttng.destroy("session-name") diff --git a/doc/quickstart.txt b/doc/quickstart.txt index 9bcb84604..06b308406 100644 --- a/doc/quickstart.txt +++ b/doc/quickstart.txt @@ -3,7 +3,7 @@ NOTES: 2011-12-12: For user-space tracing, only the global UST domain ("-u" alone) is supported meaning that if you enable a tracepoint for user-space it will be -enabled for all applications for the current tracing session you are working +enabled for all applications for the current recording session you are working on. QUICKSTART @@ -23,8 +23,8 @@ For user-space tracing, you'll need an instrumented application with lttng-ust lttng-tools provide a session daemon (lttng-sessiond) that acts as a tracing registry. To trace any instrumented applications or the kernel, a registered -tracing session is needed beforehand. To interact with the session daemon and a -tracing session, you should use the lttng command line UI (lttng). It is also +recording session is needed beforehand. To interact with the session daemon and a +recording session, you should use the lttng command line UI (lttng). It is also possible to use the liblttngctl library for tracing control (lttng.h). Here is a list of some powerful features the LTTng 2.0 kernel tracer offers: @@ -57,7 +57,7 @@ List available kernel events: # lttng list -k -1) Create a tracing session. The .lttng directory will be created with .lttngrc +1) Create a recording session. The .lttng directory will be created with .lttngrc file in $HOME containing the session name (here 'mysession') you are working on. @@ -172,7 +172,7 @@ List available registered applications: $ lttng list -u -1) Create a tracing session. The .lttng directory will be created with a +1) Create a recording session. The .lttng directory will be created with a .lttngrc file in $HOME containing the session name (here 'mysession') you are working on. diff --git a/doc/streaming-howto.txt b/doc/streaming-howto.txt index db1938dfa..a864dc702 100644 --- a/doc/streaming-howto.txt +++ b/doc/streaming-howto.txt @@ -48,7 +48,7 @@ Example 1: Simple and quick network streaming. -1) Create a tracing session that will be streamed over the network for the +1) Create a recording session that will be streamed over the network for the specified domain. This session will contain, in our example, syscall events. # lttng create syscall-session @@ -83,12 +83,12 @@ Example 2: This example uses all possible options to fine grained control the streaming. -1) Again, create a tracing session that will be streamed over the network for +1) Again, create a recording session that will be streamed over the network for the specified domain. # lttng create syscall-session -2) Set relayd URIs for the tracing session and kernel domain. +2) Set relayd URIs for the recording session and kernel domain. ONLY set the remote relayd URIs (both control and data at the same destination and using default ports) on the consumer but does not enable the consumer to use diff --git a/extras/bindings/swig/python/lttng.i.in b/extras/bindings/swig/python/lttng.i.in index 684482e1f..b555f4aae 100644 --- a/extras/bindings/swig/python/lttng.i.in +++ b/extras/bindings/swig/python/lttng.i.in @@ -398,20 +398,20 @@ int lttng_list_domains(const char *session_name, struct lttng_domain **domains); //Functions not needing redefinition %feature("docstring")"create(str name, str path) -> int -Create a new tracing session using name and path. +Create a new recording session using name and path. Returns 0 on success or a negative error code." int lttng_create_session(const char *name, const char *path); %feature("docstring")"create_snapshot(str name, str snapshot_url) -> int -Create a new tracing session using name and snapshot_url in snapshot +Create a new recording session using name and snapshot_url in snapshot mode (flight recorder). Returns 0 on success or a negative error code." int lttng_create_session_snapshot(const char *name, const char *path); %feature("docstring")"destroy(str name) -> int -Tear down tracing session using name. +Tear down recording session using name. Returns 0 on success or a negative error code." int lttng_destroy_session(const char *name); diff --git a/src/bin/lttng/commands/list.c b/src/bin/lttng/commands/list.c index a2db7e6b1..4f4fcb5ef 100644 --- a/src/bin/lttng/commands/list.c +++ b/src/bin/lttng/commands/list.c @@ -2128,19 +2128,19 @@ static int list_sessions(const char *session_name) } else { /* Pretty print */ if (count == 0) { - MSG("Currently no available tracing session"); + MSG("Currently no available recording session"); goto end; } if (session_name == NULL) { - MSG("Available tracing sessions:"); + MSG("Available recording sessions:"); } for (i = 0; i < count; i++) { if (session_name != NULL) { if (strncmp(sessions[i].name, session_name, NAME_MAX) == 0) { session_found = 1; - MSG("Tracing session %s: [%s%s]", session_name, + MSG("Recording session %s: [%s%s]", session_name, active_string(sessions[i].enabled), snapshot_string(sessions[i].snapshot_mode)); if (*sessions[i].path) { diff --git a/src/bin/lttng/lttng.c b/src/bin/lttng/lttng.c index 1c7d79954..af1d3f488 100644 --- a/src/bin/lttng/lttng.c +++ b/src/bin/lttng/lttng.c @@ -272,7 +272,7 @@ static void show_basic_help(void) puts(""); puts("Available commands:"); puts(""); - puts("Tracing sessions:"); + puts("Recording sessions:"); puts(" create " CONFIG_CMD_DESCR_CREATE); puts(" clear " CONFIG_CMD_DESCR_CLEAR); puts(" destroy " CONFIG_CMD_DESCR_DESTROY); @@ -299,7 +299,7 @@ static void show_basic_help(void) puts(" start " CONFIG_CMD_DESCR_START); puts(" stop " CONFIG_CMD_DESCR_STOP); puts(""); - puts("Tracing session rotation:"); + puts("Recording session rotation:"); puts(" disable-rotation " CONFIG_CMD_DESCR_DISABLE_ROTATION); puts(" enable-rotation " CONFIG_CMD_DESCR_ENABLE_ROTATION); puts(" rotate " CONFIG_CMD_DESCR_ROTATE); diff --git a/src/common/error.c b/src/common/error.c index 611967b86..4d6b26b22 100644 --- a/src/common/error.c +++ b/src/common/error.c @@ -161,7 +161,7 @@ static const char *error_string_array[] = { [ ERROR_INDEX(LTTNG_ERR_FILTER_INVAL) ] = "Invalid filter bytecode", [ ERROR_INDEX(LTTNG_ERR_FILTER_NOMEM) ] = "Not enough memory for filter bytecode", [ ERROR_INDEX(LTTNG_ERR_FILTER_EXIST) ] = "Filter already exist", - [ ERROR_INDEX(LTTNG_ERR_NO_CONSUMER) ] = "Consumer not found for tracing session", + [ ERROR_INDEX(LTTNG_ERR_NO_CONSUMER) ] = "Consumer not found for recording session", [ ERROR_INDEX(LTTNG_ERR_NO_SESSIOND) ] = "No session daemon is available", [ ERROR_INDEX(LTTNG_ERR_SESSION_STARTED) ] = "Session is running", [ ERROR_INDEX(LTTNG_ERR_NOT_SUPPORTED) ] = "Operation not supported", @@ -195,7 +195,7 @@ static const char *error_string_array[] = { [ ERROR_INDEX(LTTNG_ERR_OVERFLOW) ] = "Overflow occurred", [ ERROR_INDEX(LTTNG_ERR_SESSION_NOT_STARTED) ] = "Session not started", [ ERROR_INDEX(LTTNG_ERR_LIVE_SESSION) ] = "Live sessions are not supported", - [ ERROR_INDEX(LTTNG_ERR_PER_PID_SESSION) ] = "Per-PID tracing sessions are not supported", + [ ERROR_INDEX(LTTNG_ERR_PER_PID_SESSION) ] = "Per-PID recording sessions are not supported", [ ERROR_INDEX(LTTNG_ERR_KERN_CONTEXT_UNAVAILABLE) ] = "Context unavailable on this kernel", [ ERROR_INDEX(LTTNG_ERR_REGEN_STATEDUMP_FAIL) ] = "Failed to regenerate the state dump", [ ERROR_INDEX(LTTNG_ERR_REGEN_STATEDUMP_NOMEM) ] = "Failed to regenerate the state dump, not enough memory", @@ -223,7 +223,7 @@ static const char *error_string_array[] = { [ ERROR_INDEX(LTTNG_ERR_MKDIR_FAIL_CONSUMER) ] = "Directory creation failure on consumer", [ ERROR_INDEX(LTTNG_ERR_CHAN_NOT_FOUND) ] = "Channel not found", [ ERROR_INDEX(LTTNG_ERR_SNAPSHOT_UNSUPPORTED) ] = "Session configuration does not allow the use of snapshots", - [ ERROR_INDEX(LTTNG_ERR_SESSION_NOT_EXIST) ] = "Tracing session does not exist", + [ ERROR_INDEX(LTTNG_ERR_SESSION_NOT_EXIST) ] = "Recording session does not exist", [ ERROR_INDEX(LTTNG_ERR_CREATE_TRACE_CHUNK_FAIL_CONSUMER) ] = "Trace chunk creation failed on consumer", [ ERROR_INDEX(LTTNG_ERR_CLOSE_TRACE_CHUNK_FAIL_CONSUMER) ] = "Trace chunk close failed on consumer", [ ERROR_INDEX(LTTNG_ERR_TRACE_CHUNK_EXISTS_FAIL_CONSUMER) ] = "Failed to query consumer for trace chunk existence", diff --git a/src/lib/lttng-ctl/lttng-ctl.pc.in b/src/lib/lttng-ctl/lttng-ctl.pc.in index b8506fc5e..aa365def8 100644 --- a/src/lib/lttng-ctl/lttng-ctl.pc.in +++ b/src/lib/lttng-ctl/lttng-ctl.pc.in @@ -9,7 +9,7 @@ libdir=@libdir@ includedir=@includedir@ Name: LTTng control library -Description: The LTTng control and utility library is a library used to control the tracing sessions of a LTTng-session daemon +Description: Control LTTng recording sessions and triggers Version: @PACKAGE_VERSION@ Requires: Requires.private: diff --git a/tests/regression/tools/trigger/start-stop/test_start_stop b/tests/regression/tools/trigger/start-stop/test_start_stop index 102e7ac1d..c3a4e7fbd 100755 --- a/tests/regression/tools/trigger/start-stop/test_start_stop +++ b/tests/regression/tools/trigger/start-stop/test_start_stop @@ -25,7 +25,7 @@ NR_USEC_WAIT=5 function lttng_session_is_active() { local SESSION_NAME="$1" - "$FULL_LTTNG_BIN" list "$SESSION_NAME" | grep "Tracing session" | grep -q "\[active\]" + "$FULL_LTTNG_BIN" list "$SESSION_NAME" | grep "Recording session" | grep -q "\[active\]" ok $ret "Session \"$SESSION_NAME\" is active" } @@ -33,7 +33,7 @@ function lttng_session_is_active() function lttng_session_is_inactive() { local SESSION_NAME="$1" - "$FULL_LTTNG_BIN" list "$SESSION_NAME" | grep "Tracing session" | grep -q "\[inactive\]" + "$FULL_LTTNG_BIN" list "$SESSION_NAME" | grep "Recording session" | grep -q "\[inactive\]" ok $ret "Session \"$SESSION_NAME\" is inactive" } diff --git a/tests/utils/test_utils.py b/tests/utils/test_utils.py index 385f8544d..afe066d76 100644 --- a/tests/utils/test_utils.py +++ b/tests/utils/test_utils.py @@ -74,7 +74,7 @@ def create_session(): res = create(session_name, trace_path) if res < 0: - bail("Failed to create tracing session.") + bail("Failed to create recording session.") channel = Channel() channel.name = "channel0" -- 2.34.1