From: Philippe Proulx Date: Thu, 29 Apr 2021 21:00:07 +0000 (-0400) Subject: Update the remaining manual pages for LTTng-tools 2.13 X-Git-Tag: v2.13.0-rc2~34 X-Git-Url: https://git.lttng.org./?a=commitdiff_plain;h=188419c4eee5d623605d6c7bd797c18ae8564647;p=lttng-tools.git Update the remaining manual pages for LTTng-tools 2.13 This patch updates the remaining manual pages for LTTng-tools 2.13. This patch: * Improves the consistency of some command descriptions in `configure.ac`. * Adds `common-daemon-cfg.txt` which is a section explaining how to configure a daemon (session or relay). lttng-sessiond(8) and lttng-relayd(8) include this file. * Adds `lttng-concepts.7.txt` which is an adapted copy of the "Core concepts" section of the online LTTng Documentation. This centralizes all the LTTng theory into a single manual page instead of having this information split into multiple lttng(1) command manual pages. Many manual pages now refer to lttng-concepts(7), making it possible to cut a lot of text in those. * Updates existing manual pages to: * Have a style and voice which is more consistent with the LTTng Documentation (website) for 2.13. * Fix various terminology ambiguities. * Use more textual variables and lists to explain more complex logic and processes. * Always use the same pattern to specify the behaviour of an lttng(1) command depending on the `SESSION` argument or the `--session` option. * For the commands which can perform more than one task, list their available tasks at the beginning of the "DESCRIPTION" section. * For some lttng(1) commands which can operate on all tracing sessions (for example, lttng-clear(1) and lttng-destroy(1)), always indicate that they target all your Unix user's tracing sessions or, if your Unix user is `root`, the tracing sessions of all the Unix users within the root session daemon. * Clean the "SEE ALSO" sections. * Always have "LTTng" in the "NAME" section of a manual page. More specifically: lttng-create(1): * Clarify the tracing session modes. * Clarify how the command adds (or not) a snapshot output for a snapshot mode tracing session. * Specify that `--output=DIR` is equivalent to `--set-url=file://DIR`. lttng-enable-channel(1): Include the `--discard`, `--buffers-uid`, and `--buffers-global` options in the "SYNOPSIS" section even if they are the current defaults. lttng-list(1): Explain what this command does exactly using a tree of options and arguments. lttng-load(1): Clarify how LTTng finds tracing session configurations. lttng-relayd(8): * Document the missing `--group` option. * Rework the text in general. * Add a daemon configuration section with an INI file example. * Add more cross-references between options and equivalent environment variables. lttng-rotate(1): Specify that the `rotate-session` trigger action can also rotate a tracing session. lttng-save(1): Clarify the output path. lttng-sessiond(8): Add more cross-references between options and equivalent environment variables. lttng-shapshot(1): * Clarify everything related to the snapshot output of a tracing session, including when and how the lttng-create(1) command adds an initial snapshot output. * Specify that the `snapshot-session` trigger action can also take a snapshot of a tracing session. lttng-track(1): lttng-untrack(1): * Simply refer to allowing processes to record events and to process attribute inclusion sets instead of using the vague "tracker" terminology. * Restate that those commands control an implicit condition of a recording event rule, as per lttng-concepts(7). * Improve the documentation of each inclusion set selection option. Signed-off-by: Philippe Proulx Signed-off-by: Jérémie Galarneau Change-Id: Iac7498ee979fe077f0927a9b8335f6c07f203989 --- diff --git a/configure.ac b/configure.ac index 137d956b8..75240d836 100644 --- a/configure.ac +++ b/configure.ac @@ -433,12 +433,12 @@ _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_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 rotation schedule]) +_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_DISABLE_ROTATION], [Unset a tracing 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 rotation schedule]) +_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_ENABLE_ROTATION], [Set a tracing 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, tracing domains, channels, and recording event rules]) +_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_LIST], [List tracing 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]) @@ -450,8 +450,8 @@ _AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_SNAPSHOT], [Take a tracing session snapsh _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_TRACK], [Track process attrbutes]) -_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_UNTRACK], [Untrack process attributes]) +_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]) _AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_VIEW], [Launch a trace reader]) diff --git a/doc/man/Makefile.am b/doc/man/Makefile.am index 869494db9..97aa59b66 100644 --- a/doc/man/Makefile.am +++ b/doc/man/Makefile.am @@ -41,7 +41,7 @@ MAN1_NAMES = \ lttng-remove-trigger \ lttng-list-triggers MAN3_NAMES = -MAN7_NAMES = lttng-event-rule +MAN7_NAMES = lttng-event-rule lttng-concepts MAN8_NAMES = lttng-sessiond lttng-relayd MAN1_NO_ASCIIDOC_NAMES = MAN3_NO_ASCIIDOC_NAMES = lttng-health-check @@ -63,7 +63,8 @@ COMMON_TXT = \ $(srcdir)/common-cmd-options-head.txt \ $(srcdir)/common-cmd-help-options.txt \ $(srcdir)/common-help-option.txt \ - $(srcdir)/common-intro.txt + $(srcdir)/common-intro.txt \ + $(srcdir)/common-daemon-cfg.txt # config ASCIIDOC_CONF = $(srcdir)/asciidoc.conf diff --git a/doc/man/common-cmd-footer.txt b/doc/man/common-cmd-footer.txt index dbeab32d6..cd0ce8b76 100644 --- a/doc/man/common-cmd-footer.txt +++ b/doc/man/common-cmd-footer.txt @@ -22,8 +22,8 @@ directory. configuration XML schema. `LTTNG_SESSIOND_PATH`:: - Absolute path to the LTTng session daemon (see - man:lttng-sessiond(8)) binary. + Absolute path to the LTTng session daemon binary (see + man:lttng-sessiond(8)). + The genoption:--sessiond-path general option overrides this environment variable. diff --git a/doc/man/common-daemon-cfg.txt b/doc/man/common-daemon-cfg.txt new file mode 100644 index 000000000..c7b7eed80 --- /dev/null +++ b/doc/man/common-daemon-cfg.txt @@ -0,0 +1,39 @@ +[[cfg]] +Daemon configuration +~~~~~~~~~~~~~~~~~~~~ +When you run +{daemon-bin-name}+, it configures itself from, in this order: + +. The INI configuration file +{system_lttng_conf}+, if any. + +. The INI configuration file `$LTTNG_HOME/.lttng/lttng.conf`, if any. ++ +`$LTTNG_HOME` defaults to `$HOME`. + +. With the option:--config='PATH' option: the INI configuration file + 'PATH'. + +. The command-line options. + +Each step can override a previous configuration property. + +In INI configuration files, the session daemon only reads the properties +under the +{daemon-ini-section}+ INI section. Each INI property is: + +Key:: + The long name of a command-line option to set (see the + <> section below). + +Value:: + The selected command-line option accepts an argument::: + Option argument (string). + + The selected command-line option is a switch::: + `true`:::: + `yes`:::: + `on`:::: + Enable the option. + + `false`:::: + `no`:::: + `off`:::: + Disable the option. diff --git a/doc/man/lttng-add-context.1.txt b/doc/man/lttng-add-context.1.txt index 512bdf154..a5ca19ef5 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: 8 April 2021 +:revdate: 3 May 2021 NAME @@ -10,8 +10,8 @@ lttng-add-context - Add context fields to be recorded by LTTng SYNOPSIS -------- -Add context fields to be recorded to the LTTng event records of -one or more channels: +Add context fields to be recorded to the event records of one or more +channels: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *add-context* @@ -27,77 +27,84 @@ List the available context field types: DESCRIPTION ----------- -The `lttng add-context` command adds one or more context fields to be -recorded to the event records of a given channel, or of all the channels -of a selected tracing session, by LTTng. +The `lttng add-context` command can: -See man:lttng-enable-channel(1) to learn more about LTTng channels. +Without the option:--list option:: + Add one or more context fields to be recorded by LTTng to the event + records of a given channel, or of all the channels of: ++ +With the option:--session='SESSION' option::: + The tracing 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). -When you use the `add-context` command to add context fields for a given -channel, all the event records which LTTng writes to a sub-buffer of -that channel contain the dynamic values of those context fields. +With the option:--list option:: + List the available context field types. -Without the option:--session option, the `add-context` command selects -the current tracing session (see man:lttng-create(1) and -man:lttng-set-session(1) to learn more about the current tracing -session). +See man:lttng-concepts(7) to learn more about tracing sessions and +channels. Without the option:--channel option, LTTng adds context fields to be recorded to the event records of *all* the channels of the selected tracing session. -Repeat the option:--type option to add more than one context field to be -recorded. +Repeat the option:--type='TYPE' option to add more than one context +field to be recorded. 'TYPE' is one of: -perf counter context fields are available: +* A statically-known, or built-in context field named. +* A perf counter name: ++ +-- Per-CPU:: - Prefix: `perf:cpu:`. + Prefix: `perf:cpu:` + -Only available for Linux kernel (option:--kernel option) channels. +Only available with the option:--kernel option. Per-thread:: - Prefix: `perf:thread:`. + Prefix: `perf:thread:` + -Only available for user application/library (option:--userspace, -option:--jul, and option:--log4j options) channels. - -Add PMU counter context fields by raw ID with the -++perf:cpu:raw:r++__N__++:++__NAME__ (Linux kernel tracing domain) or -++perf:thread:raw:r++__N__++:++__NAME__ (user space tracing domain) -types, with: - +Only available with the option:--userspace, option:--jul, or +option:--log4j option. +-- ++ +Add Performance Monitoring Unit (PMU) counter context fields by raw ID +with the ++perf:cpu:raw:r++__N__++:++__NAME__ (option:--kernel option) +or ++perf:thread:raw:r++__N__++:++__NAME__ (option:--userspace, +option:--jul, or option:--log4j option) types, with: ++ +-- 'N':: A hexadecimal event descriptor which follows the man:perf-record(1) format: a concatenation of the event number and umask value which the manufacturer of the processor provides. + -The possible values for this field are processor-specific. +The possible values for this part are processor-specific. 'NAME':: - Custom name to easily recognize the counter. - -Add an application-specific context field with the following syntax: + Custom name to identify the counter. +-- +* An LTTng application-specific context field name: ++ [verse] $app.'PROVIDER':__TYPE__ - ++ 'PROVIDER':: Provider name. 'TYPE':: Context type name. -NOTE: Make sure to **single-quote** the argument of the option:--type -option when you run the `add-context` command from a shell, as `$` is a -special character for variable substitution in most shells. - -List the available context field types with the option:--list option and -without other arguments. +IMPORTANT: Make sure to **single-quote** 'TYPE' when you run the +`add-context` command from a shell, as `$` is a special character for +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. +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. include::common-cmd-options-head.txt[] @@ -160,5 +167,5 @@ include::common-cmd-footer.txt[] SEE ALSO -------- man:lttng(1), -man:lttng-enable-channel(1), -man:lttng-set-session(1) +man:lttng-concepts(7), +man:lttng-enable-channel(1) diff --git a/doc/man/lttng-add-trigger.1.txt b/doc/man/lttng-add-trigger.1.txt index ccca9da0f..5694d28d6 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: 23 April 2021 +:revdate: 3 May 2021 NAME @@ -18,33 +18,27 @@ SYNOPSIS DESCRIPTION ----------- The `lttng add-trigger` command creates and adds an LTTng _trigger_ to -the session daemon (see man:lttng-sessiond(8)). +the connected session daemon (see man:lttng-sessiond(8)). -A trigger is an association between a _condition_ and one or more -_actions_. When the condition of a trigger{nbsp}__T__ is satisfied, -LTTng requests to execute the actions of{nbsp}__T__. Depending on the -rate policy of an action, an execution request can become an actual -execution. +See man:lttng-concepts(7) to learn more about LTTng triggers. -A trigger doesn't belong to a specific tracing session: it's global to -the session daemon. Within the session daemon, and for a given Unix -user, a trigger has a unique name. By default, the `add-trigger` command -automatically assigns a name to the added trigger. Use the option:--name -option to assign a specific name instead. +By default, the `add-trigger` command automatically assigns a name, +unique for a given session daemon and Unix user, to the added trigger. +Assign a custom name with the option:--name. The `add-trigger` command adds a trigger for your Unix user. If your -Unix user is `root`, you can add the trigger as another user with the +Unix user is `root`, you may add the trigger as another user with the option:--owner-uid option. Specify the condition of the trigger to add with a <> and its actions with one or more <>. The order of the action specifiers is significant: LTTng -attempts to execute the actions of a trigger in order. +attempts to execute the actions of a firing trigger in this order. -List the available triggers for your Unix user (or for all users if your -Unix user is `root`) with the man:lttng-list-triggers(1) command. +List the triggers of your Unix user, or of all users if your +Unix user is `root`, with the man:lttng-list-triggers(1) command. -Remove an existing trigger with the man:lttng-remove-trigger(1) command. +Remove a trigger with the man:lttng-remove-trigger(1) command. [[cond-spec]] @@ -65,7 +59,7 @@ The available condition types are: Synopsis: + [verse] -option:--condition=event-rule-matches [nloption:--capture='CDESCR']... 'ERSPEC' +option:--condition=**event-rule-matches** [nloption:--capture='CDESCR']... 'ERSPEC' {nbsp} + An `event-rule-matches` condition is considered satisfied when the event @@ -168,7 +162,7 @@ Notify:: Synopsis: + [verse] -option:--action=notify [nloption:--rate-policy='POLICY'] +option:--action=**notify** [nloption:--rate-policy='POLICY'] {nbsp} + Sends a notification through the notification @@ -186,7 +180,7 @@ Start a tracing session:: Synopsis: + [verse] -option:--action=start-session 'SESSION' [nloption:--rate-policy='POLICY'] +option:--action=**start-session** 'SESSION' [nloption:--rate-policy='POLICY'] {nbsp} + Starts the tracing session named 'SESSION' like man:lttng-start(1) @@ -201,7 +195,7 @@ Stop a tracing session:: Synopsis: + [verse] -option:--action=stop-session 'SESSION' [nloption:--rate-policy='POLICY'] +option:--action=**stop-session** 'SESSION' [nloption:--rate-policy='POLICY'] {nbsp} + Stops the tracing session named 'SESSION' like man:lttng-stop(1) would. @@ -215,7 +209,7 @@ Rotate a tracing session:: Synopsis: + [verse] -option:--action=rotate-session 'SESSION' [nloption:--rate-policy='POLICY'] +option:--action=**rotate-session** 'SESSION' [nloption:--rate-policy='POLICY'] {nbsp} + Archives the current trace chunk of the tracing session named 'SESSION' @@ -230,7 +224,7 @@ Take a tracing session snapshot:: Synopsis: + [verse] -option:--action=snapshot-session 'SESSION' [nloption:--rate-policy='POLICY'] +option:--action=**snapshot-session** 'SESSION' [nloption:--rate-policy='POLICY'] {nbsp} + Takes a snapshot of the tracing session named 'SESSION' like @@ -315,5 +309,6 @@ include::common-cmd-footer.txt[] SEE ALSO -------- man:lttng(1), +man:lttng-concepts(7), man:lttng-list-triggers(1), man:lttng-remove-trigger(1) diff --git a/doc/man/lttng-clear.1.txt b/doc/man/lttng-clear.1.txt index 7cec7f44e..34714f699 100644 --- a/doc/man/lttng-clear.1.txt +++ b/doc/man/lttng-clear.1.txt @@ -1,10 +1,10 @@ lttng-clear(1) ============== -:revdate: 8 April 2021 +:revdate: 3 May 2021 NAME ---- -lttng-clear - Clear a tracing session +lttng-clear - Clear an LTTng tracing session SYNOPSIS @@ -19,27 +19,33 @@ 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. +See man:lttng-concepts(7) to learn more about tracing sessions. + The `clear` command clears: Without any option:: The current tracing session. + -See man:lttng-create(1) and man:lttng-set-session(1) to learn more about -the current tracing session. +See man:lttng-concepts(7) to learn more about the current tracing +session. With the 'SESSION' argument:: - The existing tracing session named 'SESSION'. + The tracing session named 'SESSION'. With the option:--all option:: - *All* the tracing sessions of your Unix user, as listed in the - output of `lttng list` (see man:lttng-list(1)). + *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)). ++ +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 nloption:--snapshot option of the man:lttng-create(1) command), the `clear` command only clears the tracing buffers. For a given tracing session, if at least one rotation occurred (see -man:lttng-rotate(1)), the `clear` command only clears its tracing +man:lttng-concepts(7)), the `clear` command only clears its tracing buffers and its current trace chunk, :not: its archived trace chunks. NOTE: The nloption:--disallow-clear option and the @@ -55,9 +61,10 @@ include::common-cmd-options-head.txt[] Recording target ~~~~~~~~~~~~~~~~ option:-a, option:--all:: - Clear all the tracing sessions of your Unix user, as listed in the - output of man:lttng-list(1), instead of the current tracing session - or the tracing session named 'SESSION'. + Clear 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'. include::common-cmd-help-options.txt[] @@ -69,7 +76,6 @@ include::common-cmd-footer.txt[] SEE ALSO -------- man:lttng(1), +man:lttng-concepts(7), man:lttng-create(1), -man:lttng-relayd(8), -man:lttng-rotate(1), -man:lttng-set-session(1) +man:lttng-relayd(8) diff --git a/doc/man/lttng-concepts.7.txt b/doc/man/lttng-concepts.7.txt new file mode 100644 index 000000000..e88f529f0 --- /dev/null +++ b/doc/man/lttng-concepts.7.txt @@ -0,0 +1,999 @@ +lttng-concepts(7) +================= +:revdate: 3 May 2021 +:sect-event-rule: INSTRUMENTATION POINT, EVENT RULE, AND EVENT +:sect-session: TRACING SESSION +:sect-domain: TRACING DOMAIN +:sect-channel: CHANNEL AND RING BUFFER +:sect-recording-event-rule: RECORDING EVENT RULE AND EVENT RECORD + + +NAME +---- +lttng-concepts - LTTng concepts + + +DESCRIPTION +----------- +This manual page documents the concepts of LTTng. + +Many other LTTng manual pages refer to this one so that you can +understand what are the various LTTng objects and how they relate to +each other. + +The concepts of LTTng{nbsp}{lttng_version} are: + +* Instrumentation point, event rule, and event +* Trigger +* Tracing session +* Tracing domain +* Channel and ring buffer +* Recording event rule and event record + + +[[event-rule]] +{sect-event-rule} +----------------- +An _instrumentation point_ is a point, within a piece of software, +which, when executed, creates an LTTng _event_. + +LTTng offers various types of instrumentation; see the +<> section below to learn +about them. + +An _event rule_ is a set of conditions to match a set of events. + +When LTTng creates an event{nbsp}__E__, an event rule{nbsp}__ER__ is +said to __match__{nbsp}__E__ when{nbsp}__E__ satisfies *all* the +conditions of{nbsp}__ER__. This concept is similar to a regular +expression which matches a set of strings. + +When an event rule matches an event, LTTng _emits_ the event, therefore +attempting to execute one or more actions. + +[IMPORTANT] +==== +The event creation and emission processes are documentation concepts to +help understand the journey from an instrumentation point to the +execution of actions. + +The actual creation of an event can be costly because LTTng needs to +evalute the arguments of the instrumentation point. + +In practice, LTTng implements various optimizations for the Linux kernel +and user space tracing domains (see the <> section +below) to avoid actually creating an event +when the tracer knows, thanks to properties which are independent from +the event payload and current context, that it would never emit such an +event. Those properties are: + +* The instrumentation point type (see the + <> section below). + +* The instrumentation point name. + +* The instrumentation point log level. + +* For a recording event rule (see the + <> section + below): +** 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 <> section below). +** Whether or not the process for which LTTng would create the event is + allowed to record events (see man:lttng-track(1)). + +In other words: if, for a given instrumentation point{nbsp}__IP__, the +LTTng tracer knows that it would never emit an event, +executing{nbsp}__IP__ represents a simple boolean variable check and, +for a Linux kernel recording event rule, a few process attribute checks. +==== + +As of LTTng{nbsp}{lttng_version}, there are two places where you can +find an event rule: + +Recording event rule:: + A specific type of event rule of which the action is to record the + matched event as an event record. ++ +See the <> section +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 +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. ++ +See man:lttng-add-trigger(1) and man:lttng-event-rule(7). + +For LTTng to emit an event{nbsp}__E__,{nbsp}__E__ must satisfy *all* the +basic conditions of an event rule{nbsp}__ER__, that is: + +* The instrumentation point from which LTTng creates{nbsp}__E__ has a + specific type. ++ +See the <> section below. + +* A pattern matches the name of{nbsp}__E__ while another pattern + doesn't. + +* The log level of the instrumentation point from which LTTng + creates{nbsp}__E__ is at least as severe as some value, or is exactly + some value. + +* The fields of the payload of{nbsp}__E__ and the current context fields + satisfy a filter expression. + +A recording event rule has additional, implicit conditions to satisfy. +See the <> section +below to learn more. + + +[[inst-point-types]] +Instrumentation point types +~~~~~~~~~~~~~~~~~~~~~~~~~~~ +As of LTTng{nbsp}{lttng_version}, the available instrumentation point +types are, depending on the tracing domain (see the +<> section below): + +Linux kernel:: + LTTng tracepoint::: + A statically defined point in the source code of the kernel + image or of a kernel module using the LTTng-modules macros. ++ +List the available Linux kernel tracepoints with `lttng list --kernel`. +See man:lttng-list(1) to learn more. + + Linux kernel system call::: + Entry, exit, or both of a Linux kernel system call. ++ +List the available Linux kernel system call instrumentation points with +`lttng list --kernel --syscall`. See man:lttng-list(1) to learn more. + + Linux kprobe::: + A single probe dynamically placed in the compiled kernel code. ++ +When you create such an instrumentation point, you set its memory +address or symbol name. + + Linux user space probe::: + A single probe dynamically placed at the entry of a compiled + user space application/library function through the kernel. ++ +When you create such an instrumentation point, you set: ++ +-- +With the ELF method:: + Its application/library path and its symbol name. + +With the USDT method:: + Its application/library path, its provider name, and its probe name. ++ +``USDT'' stands for SystemTap User-level Statically Defined Tracing, +a DTrace-style marker. +-- ++ +As of LTTng{nbsp}{lttng_version}, LTTng only supports USDT probes which +are :not: reference-counted. + + Linux kretprobe::: + Entry, exit, or both of a Linux kernel function. ++ +When you create such an instrumentation point, you set the memory +address or symbol name of its function. + +User space:: + LTTng tracepoint::: + A statically defined point in the source code of a C/$$C++$$ + application/library using the LTTng-UST macros. ++ +List the available Linux kernel tracepoints with +`lttng list --userspace`. See man:lttng-list(1) to learn more. + +`java.util.logging`, Apache log4j, and Python:: + Java or Python logging statement::: + A method call on a Java or Python logger attached to an + LTTng-UST handler. ++ +List the available Java and Python loggers with `lttng list --jul`, +`lttng list --log4j`, and `lttng list --python`. See man:lttng-list(1) +to learn more. + + +[[trigger]] +TRIGGER +------- +A _trigger_ associates a condition to one or more actions. + +When the condition of a trigger is satisfied, LTTng attempts to execute +its actions. + +As of LTTng{nbsp}{lttng_version}, the available trigger conditions and +actions are: + +Conditions:: ++ +* The consumed buffer size of a given tracing + session (see the <> section below) + becomes greater than some value. + +* The buffer usage of a given channel (see the + <> section below) becomes greater than some + value. + +* The buffer usage of a given channel becomes less than some value. + +* There's an ongoing tracing session rotation (see the + <> section below). + +* A tracing session rotation becomes completed. + +* An event rule matches an event. ++ +As of LTTng{nbsp}{lttng_version}, this is the only available condition +when you add a trigger with the man:lttng-add-trigger(1) command. The +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), + like man:lttng-rotate(1) would do. +* Take a snapshot of a given tracing 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 +user has its own, private triggers. Note, however, that the `root` Unix +user may, for the root session daemon: + +* Add a trigger as another Unix user. + +* List all the triggers, regardless of their owner. + +* Remove a trigger which belongs to another Unix user. + +For a given session daemon and Unix user, a trigger has a unique name. + +Add a trigger to a session daemon with the man:lttng-add-trigger(1) +command. + +List the triggers of your Unix user (or of all users if your +Unix user is `root`) with the man:lttng-list-triggers(1) command. + +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. + +Everything that you do when you control LTTng tracers to record events +happens within a tracing session. In particular, a tracing session: + +* Has its own name, unique for a given session daemon. + +* Has its own set of trace files, if any. + +* Has its own state of activity (started or stopped). ++ +An active tracing 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 learn +more. + +* Has its own channels (see the <> section + below) to which are attached their own recording event rules. + +* Has its own process attribute inclusion sets (see man:lttng-track(1)). + +Those attributes and objects are completely isolated between different +tracing sessions. + +A tracing 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 +the man:lttng-create(1) command to the man:lttng-destroy(1) command. + +A tracing 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. + +Create a tracing session with the man:lttng-create(1) command. + +List the tracing 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 +man:lttng-stop(1) commands. + +Save and load a tracing 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 +man:lttng-rotate(1) command. + +Destroy a tracing session with the man:lttng-destroy(1) command. + + +Current tracing 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 +session_. + +When you create a new tracing session with the `create` command, LTTng +updates the current tracing session. + +The following man:lttng(1) commands select the current tracing session +if you don't specify one: + +* man:lttng-add-context(1) +* man:lttng-clear(1) +* man:lttng-destroy(1) +* man:lttng-disable-channel(1) +* man:lttng-disable-event(1) +* man:lttng-disable-rotation(1) +* man:lttng-enable-channel(1) +* man:lttng-enable-event(1) +* man:lttng-enable-rotation(1) +* man:lttng-regenerate(1) +* man:lttng-rotate(1) +* man:lttng-save(1) +* man:lttng-snapshot(1) +* man:lttng-start(1) +* man:lttng-status(1) +* man:lttng-stop(1) +* man:lttng-track(1) +* man:lttng-untrack(1) +* man:lttng-view(1) + +Set the current tracing 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: + +Local mode:: + Write the trace data to the local file system. + +Network streaming mode:: + Send the trace data over the network to a listening relay daemon + (see man:lttng-relayd(8)). + +Snapshot mode:: + Only write the trace data to the local file system or send it to a + listening relay daemon (man:lttng-relayd(8)) when LTTng takes a + snapshot. ++ +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: ++ +-- +* You run the man:lttng-snapshot(1) command. + +* LTTng executes a `snapshot-session` trigger action (see the + <> section above). +-- + +Live mode:: + Send the trace data over the network to a listening relay daemon + (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 +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. + +Once LTTng archives a trace chunk, it does :not: manage it anymore: you +can read it, modify it, move it, or remove it. + +An _archived trace chunk_ is a collection of metadata and data stream +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 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 + man:lttng-start(1) command or with a `start-session` trigger action + (see the <> section above). + +** The last rotation, performed with: + +*** An man:lttng-rotate(1) command. + +*** A rotation schedule previously set with + man:lttng-enable-rotation(1). + +*** An executed `rotate-session` trigger action (see the + <> section above). + +* The content of all the non-flushed sub-buffers of the channels of the + tracing 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 +nloption:--output option of the man:lttng-create(1) command and +of man:lttng-relayd(8)). + +A trace chunk archive contains, through tracing domain and possibly +UID/PID subdirectories, metadata and data stream files. + +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. + +In other words, an LTTng trace reader can read both the tracing +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 +trace chunk archive as such, relative to the output directory of the +tracing session: + +[verse] +archives/__BEGIN__-__END__-__ID__ + +__BEGIN__:: + Date and time of the beginning of the trace chunk archive with + the ISO{nbsp}8601-compatible __YYYYmmddTHHMMSS±HHMM__ form, where + __YYYYmmdd__ is the date and __HHMMSS±HHMM__ is the time with the + time zone offset from UTC. ++ +Example: `20171119T152407-0500` + +__END__:: + Date and time of the end of the trace chunk archive with + the ISO{nbsp}8601-compatible __YYYYmmddTHHMMSS±HHMM__ form, where + __YYYYmmdd__ is the date and __HHMMSS±HHMM__ is the time with the + time zone offset from UTC. ++ +Example: `20180118T152407+0930` + +__ID__:: + Unique numeric identifier of the trace chunk within its tracing + session. + +Trace chunk archive name example: + +---- +archives/20171119T152407-0500-20171119T151422-0500-3 +---- + + +[[domain]] +{sect-domain} +------------- +A _tracing domain_ identifies a type of LTTng tracer. + +A tracing domain has its own properties and features. + +There are currently five available tracing domains: + +[options="header"] +|=== +|Tracing domain |``Event rule matches'' trigger condition option |Option for other CLI commands + +|Linux kernel +|nloption:--domain=++kernel++ +|nloption:--kernel + +|User space +|nloption:--domain=++user++ +|nloption:--userspace + +|`java.util.logging` (JUL) +|nloption:--domain=++jul++ +|nloption:--jul + +|Apache log4j +|nloption:--domain=++log4j++ +|nloption:--log4j + +|Python +|nloption:--domain=++python++ +|nloption:--python +|=== + +You must specify a tracing domain to target a type of LTTng tracer when +using some man:lttng(1) to avoid ambiguity. For example, because the +Linux kernel and user space tracing domains support named tracepoints as +instrumentation points (see the <<"event-rule","{sect-event-rule}">> section +above), you need to specify a tracing domain when you create an event +rule because both tracing domains could have tracepoints sharing the +same name. + +You can create channels (see the <> section +below) in the Linux kernel and user space tracing domains. The other +tracing domains have a single, default channel. + + +[[channel]] +{sect-channel} +-------------- +A _channel_ is an object which is responsible for a set of ring buffers. + +Each ring buffer is divided into multiple _sub-buffers_. When a +recording event rule (see the +<> section below. + +* What to do when there's no + space left for a new event record because all sub-buffers are full. ++ +See the <> section below. + +* The size of each ring buffer and how many sub-buffers a ring buffer + has. ++ +See the <> section +below. + +* The size of each trace file LTTng writes for this channel and the + maximum count of trace files. ++ +See the <> section below. + +* The periods of its read, switch, and monitor timers. ++ +See the <> section below. + +* For a Linux kernel channel: its output type (man:mmap(2) or + man:splice(2)). ++ +See the nloption:--output option of the man:lttng-enable-channel(1) +command. + +* For a user space channel: the value of its blocking timeout. ++ +See the nloption:--blocking-timeout option of the +man:lttng-enable-channel(1) command. + +Note that the man:lttng-enable-event(1) command can automatically create +a default channel with sane defaults when no channel exists for the +provided tracing domain. + +A channel is always associated to a tracing domain (see the +<> section below). The `java.util.logging` (JUL), +log4j, and Python tracing domains each have a default channel which you +can't configure. + +A channel owns recording event rules. + +List the channels of a given tracing session with the +man:lttng-list(1) and man:lttng-status(1) commands. + +Disable an enabled channel with the man:lttng-disable-channel(1) +command. + + +[[channel-buf-scheme]] +Buffering scheme +~~~~~~~~~~~~~~~~ +A channel has at least one ring buffer per CPU. LTTng always records an +event to the ring buffer dedicated to the CPU which emits it. + +The buffering scheme of a user space channel determines what has its own +set of per-CPU ring buffers: + +Per-user buffering (nloption:--buffers-uid option of the man:lttng-enable-channel(1) command):: + Allocate one set of ring buffers (one per CPU) shared by all the + instrumented processes of: + If your Unix user is `root`::: + Each Unix user. + Otherwise::: + Your Unix user. + +Per-process buffering (nloption:--buffers-pid option of the man:lttng-enable-channel(1) command):: + Allocate one set of ring buffers (one per CPU) for each instrumented + process of: + If your Unix user is `root`::: + All Unix users. + Otherwise::: + Your Unix user. + +The per-process buffering scheme tends to consume more memory than the +per-user option because systems generally have more instrumented +processes than Unix users running instrumented processes. However, the +per-process buffering scheme ensures that one process having a high +event throughput won't fill all the shared sub-buffers of the same Unix +user, only its own. + +The buffering scheme of a Linux kernel channel is always to allocate a +single set of ring buffers for the whole system. This scheme is similar +to the per-user option, but with a single, global user ``running'' the +kernel. + + +[[channel-er-loss-mode]] +Event record loss mode +~~~~~~~~~~~~~~~~~~~~~~ +When LTTng emits an event, LTTng can record it to a specific, available +sub-buffer within the ring buffers of specific channels. When there's no +space left in a sub-buffer, the tracer marks it as consumable and +another, available sub-buffer starts receiving the following event +records. An LTTng consumer daemon eventually consumes the marked +sub-buffer, which returns to the available state. + +In an ideal world, sub-buffers are consumed faster than they are filled. +In the real world, however, all sub-buffers can be full at some point, +leaving no space to record the following events. + +By default, LTTng-modules and LTTng-UST are _non-blocking_ tracers: when +there's no available sub-buffer to record an event, it's acceptable to +lose event records when the alternative would be to cause substantial +delays in the execution of the instrumented application. LTTng +privileges performance over integrity; it aims at perturbing the +instrumented application as little as possible in order to make the +detection of subtle race conditions and rare interrupt cascades +possible. + +Since LTTng{nbsp}2.10, the LTTng user space tracer, LTTng-UST, supports +a _blocking mode_. See the nloption:--blocking-timeout of the +man:lttng-enable-channel(1) command to learn how to use the blocking +mode. + +When it comes to losing event records because there's no available +sub-buffer, or because the blocking timeout of the channel is +reached, the _event record loss mode_ of the channel determines what to +do. The available event record loss modes are: + +Discard mode:: + Drop the newest event records until a sub-buffer becomes available. ++ +This is the only available mode when you specify a blocking timeout. ++ +With this mode, LTTng increments a count of lost event records when an +event record is lost and saves this count to the trace. A trace reader +can use the saved discarded event record count of the trace to decide +whether or not to perform some analysis even if trace data is known to +be missing. + +Overwrite mode:: + Clear the sub-buffer containing the oldest event records and start + writing the newest event records there. ++ +This mode is sometimes called _flight recorder mode_ because it's +similar to a https://en.wikipedia.org/wiki/Flight_recorder[flight +recorder]: always keep a fixed amount of the latest data. It's also +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. ++ +With this mode, LTTng doesn't write to the trace the exact number of +lost event records in the lost sub-buffers. + +Which mechanism you should choose depends on your context: prioritize +the newest or the oldest event records in the ring buffer? + +Beware that, in overwrite mode, the tracer abandons a _whole sub-buffer_ +as soon as a there's no space left for a new event record, whereas in +discard mode, the tracer only discards the event record that doesn't +fit. + +Set the event record loss mode of a channel with the nloption:--discard +and nloption:--overwrite options of the man:lttng-enable-channel(1) +command. + +There are a few ways to decrease your probability of losing event +records. The <> +section below shows how to fine-tune the sub-buffer size and count of a +channel to virtually stop losing event records, though at the cost of +greater memory usage. + + +[[channel-sub-buf-size-count]] +Sub-buffer size and count +~~~~~~~~~~~~~~~~~~~~~~~~~ +A channel has one or more ring buffer for each CPU of the target system. + +See the <> section above to learn +how many ring buffers of a given channel are dedicated to each CPU +depending on its buffering scheme. + +Set the size of each sub-buffer the ring buffers of a channel contain +with the nloption:--subbuf-size option of the +man:lttng-enable-channel(1) command. + +Set the number of sub-buffers each ring buffer of a channel contains +with the nloption:--num-subbuf option of the man:lttng-enable-channel(1) +command. + +Note that LTTng switching the current sub-buffer of a ring buffer +(marking a full one as consumable and switching to an available one for +LTTng to record the next events) introduces noticeable CPU overhead. +Knowing this, the following list presents a few practical situations +along with how to configure the sub-buffer size and count for them: + +High event throughput:: + In general, prefer large sub-buffers to lower the risk of losing + event records. ++ +Having larger sub-buffers also ensures a lower sub-buffer switching +frequency (see the <> section below). ++ +The sub-buffer count is only meaningful if you create the channel in +overwrite mode (see the <> +section above): in this case, if LTTng overwrites a sub-buffer, then the +other sub-buffers are left unaltered. + +Low event throughput:: + In general, prefer smaller sub-buffers since the risk of losing + event records is low. ++ +Because LTTng emits events less frequently, the sub-buffer switching +frequency should remain low and therefore the overhead of the tracer +shouldn't be a problem. + +Low memory system:: + If your target system has a low memory limit, prefer fewer first, + then smaller sub-buffers. ++ +Even if the system is limited in memory, you want to keep the +sub-buffers as large as possible to avoid a high sub-buffer switching +frequency. + +Note that LTTng uses https://diamon.org/ctf/[CTF] as its trace format, +which means event record data is very compact. For example, the average +LTTng kernel event record weights about 32{nbsp}bytes. Therefore, a +sub-buffer size of 1{nbsp}MiB is considered large. + +The previous scenarios highlight the major trade-off between a few large +sub-buffers and more, smaller sub-buffers: sub-buffer switching +frequency vs. how many event records are lost in overwrite mode. +Assuming a constant event throughput and using the overwrite mode, the +two following configurations have the same ring buffer total size: + +Two sub-buffers of 4{nbsp}MiB each:: + Expect a very low sub-buffer switching frequency, but if LTTng + ever needs to overwrite a sub-buffer, half of the event records so + far (4{nbsp}MiB) are definitely lost. + +Eight sub-buffers of 1{nbsp}MiB each:: + Expect four times the tracer overhead of the configuration above, + but if LTTng needs to overwrite a sub-buffer, only the eighth of + event records so far (1{nbsp}MiB) are definitely lost. + +In discard mode, the sub-buffer count parameter is pointless: use two +sub-buffers and set their size according to your requirements. + + +[[channel-max-trace-file-size-count]] +Maximum trace file size and count +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +By default, trace files can grow as large as needed. + +Set the maximum size of each trace file that LTTng writes of a given +channel with the nloption:--tracefile-size option of the man:lttng-enable-channel(1) +command. + +When the size of a trace file reaches the fixed maximum size of the +channel, LTTng creates another file to contain the next event records. +LTTng appends a file count to each trace file name in this case. + +If you set the trace file size attribute when you create a channel, the +maximum number of trace files that LTTng creates is _unlimited_ by +default. To limit them, use the nloption:--tracefile-count option of +man:lttng-enable-channel(1). When the number of trace files reaches the +fixed maximum count of the channel, LTTng overwrites the oldest trace +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. + +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 above), +which is available since LTTng{nbsp}2.11. +==== + + +[[channel-timers]] +Timers +~~~~~~ +Each channel can have up to three optional timers: + +Switch timer:: + When this timer expires, a sub-buffer switch happens: for each ring + buffer of the channel, LTTng marks the current sub-buffer as + consumable and switches to an available one to record the next + events. ++ +A switch timer is useful to ensure that LTTng consumes and commits trace +data to trace files or to a distant relay daemon (man:lttng-relayd(8)) +periodically in case of a low event throughput. ++ +Such a timer is also convenient when you use large sub-buffers (see the +<> section above) +to cope with a sporadic high event throughput, even if the throughput is +otherwise low. ++ +Set the period of the switch timer of a channel, or disable the timer +altogether, with the nloption:--switch-timer option of the +man:lttng-enable-channel(1) command. + +Read timer:: + When this timer expires, LTTng checks for full, consumable + sub-buffers. ++ +By default, the LTTng tracers use an asynchronous message mechanism to +signal a full sub-buffer so that a consumer daemon can consume it. ++ +When such messages must be avoided, for example in real-time +applications, use this timer instead. ++ +Set the period of the read timer of a channel, or disable the timer +altogether, with the nloption:--read-timer option of the +man:lttng-enable-channel(1) command. + +Monitor timer:: + When this timer expires, the consumer daemon samples some channel + (see the <> section above) + statistics to evaluate the following trigger conditions: ++ +-- +. The consumed buffer size of a given tracing 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. +-- ++ +If you disable the monitor timer of a channel{nbsp}__C__: ++ +-- +* The consumed buffer size value of the tracing 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. + +* The buffer usage trigger conditions (types{nbsp}2 and{nbsp}3) + for{nbsp}__C__ will never be satisfied. +-- ++ +See the <> section above to learn more about triggers. ++ +Set the period of the monitor timer of a channel, or disable the timer +altogether, with the nloption:--monitor-timer option of the +man:lttng-enable-channel(1) command. + + +[[recording-event-rule]] +{sect-recording-event-rule} +--------------------------- +A _recording event rule_ is a specific type of event rule (see the +<<"event-rule","{sect-event-rule}">> section above) of which the action is +to serialize and record the matched event as an _event record_. + +Set the explicit conditions of a recording event rule when you create it +with the man:lttng-enable-event(1) command. A recording event rule also +has the following implicit conditions: + +* The recording event rule itself is enabled. ++ +A recording event rule is enabled on creation. + +* The channel to which the recording event rule is attached is enabled. ++ +A channel is enabled on creation. ++ +See the <> section above. + +* The tracing session of the recording event rule is active (started). ++ +A tracing 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 +creation. ++ +Use the man:lttng-track(1) and man:lttng-untrack(1) commands to select +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. + +When a recording event rule{nbsp}__ER__ matches an event{nbsp}__E__, +LTTng attempts to serialize and record{nbsp}__E__ to one of the +available sub-buffers of the channel to which{nbsp}__E__ is attached. + +When multiple matching recording event rules are attached to the same +channel, LTTng attempts to serialize and record the matched event +_once_. In the following example, the second recording event rule is +redundant when both are enabled: + +[role="term"] +---- +$ lttng enable-event --userspace hello:world +$ lttng enable-event --userspace hello:world --loglevel=TRACE_INFO +---- + +List the recording event rules of a specific tracing session +and/or channel with the man:lttng-list(1) and man:lttng-status(1) +commands. + +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. + + +include::common-footer.txt[] + + +SEE ALSO +-------- +man:lttng(1), +man:lttng-relayd(8), +man:lttng-sessiond(8) diff --git a/doc/man/lttng-crash.1.txt b/doc/man/lttng-crash.1.txt index a25fd4fbd..dd8c6c701 100644 --- a/doc/man/lttng-crash.1.txt +++ b/doc/man/lttng-crash.1.txt @@ -1,6 +1,6 @@ lttng-crash(1) ============== -:revdate: 8 April 2021 +:revdate: 3 May 2021 NAME @@ -86,7 +86,4 @@ SEE ALSO -------- man:babeltrace2(1), man:lttng(1), -man:lttng-create(1), -man:lttng-relayd(8), -man:lttng-sessiond(8), -man:lttng-ust(3) +man:lttng-create(1) diff --git a/doc/man/lttng-create.1.txt b/doc/man/lttng-create.1.txt index b1032fb5e..daac924f7 100644 --- a/doc/man/lttng-create.1.txt +++ b/doc/man/lttng-create.1.txt @@ -1,6 +1,6 @@ lttng-create(1) =============== -:revdate: 8 April 2021 +:revdate: 3 May 2021 NAME @@ -14,7 +14,7 @@ Create a local mode tracing session: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] [option:--shm-path='DIR'] - [option:--no-output | option:--output='DIR' | option:--set-url=file://'DIR'] + [option:--no-output | option:--output='DIR' | option:--set-url=**file://**__DIR__] Create a network streaming mode tracing session: @@ -25,8 +25,9 @@ Create a network streaming mode tracing session: Create a snapshot mode tracing session: [verse] -*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] option:--snapshot - [option:--shm-path='DIR'] [option:--set-url='URL' | option:--ctrl-url='URL' option:--data-url='URL'] +*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: @@ -37,32 +38,11 @@ Create a live mode tracing session: DESCRIPTION ----------- The `lttng create` command creates a new tracing session for your Unix -user. - -A tracing session 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: - -* Has its own name. - -* Has its own set of trace files, if any. +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). -* Has its own state of activity (started or stopped). - -* Has its own mode (local, network streaming, - snapshot, or live). -+ -See the <> section below to learn more. - -* Has its own channels (see man:lttng-enable-channel(1)) to which are - attached their own recording event rules (see - man:lttng-enable-event(1)). - -* Has its own process attribute tracking inclusion sets (see - man:lttng-track(1)). +See man:lttng-concepts(7) to learn more about tracing sessions. Without the 'SESSION' argument, LTTng automatically generates a tracing session name having the ++auto-++__YYYYmmdd__++-++__HHMMSS__ form, where @@ -81,8 +61,15 @@ the session daemon binary to spawn with the general genoption:--sessiond-path option. Avoid automatically spawning a session daemon with the general genoption:--no-sessiond option. -List the tracing sessions of your Unix user with the man:lttng-list(1) -command. +On success, the `create` command sets the current tracing session (see +man:lttng-concepts(7) to learn more) to the created tracing session. + +Show the status of the current tracing session with the +man:lttng-status(1) command. + +List the tracing 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 man:lttng-stop(1) commands. @@ -90,71 +77,36 @@ man:lttng-stop(1) commands. Save and load a tracing session with the man:lttng-save(1) and man:lttng-load(1) commands. -Archive the current trace chunk (rotate) a tracing session with the +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 man:lttng-rotate(1) command. Destroy a tracing session with the man:lttng-destroy(1) command. -Current tracing session -~~~~~~~~~~~~~~~~~~~~~~~ -When you run the `create` 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 -session_. - -When you create a new tracing session with the `create` command, LTTng -updates the current tracing session. - -The following man:lttng(1) commands select the current tracing session -if you don't specify one: - -* man:lttng-add-context(1) -* man:lttng-clear(1) -* man:lttng-destroy(1) -* man:lttng-disable-channel(1) -* man:lttng-disable-event(1) -* man:lttng-disable-rotation(1) -* man:lttng-enable-channel(1) -* man:lttng-enable-event(1) -* man:lttng-enable-rotation(1) -* man:lttng-regenerate(1) -* man:lttng-rotate(1) -* man:lttng-save(1) -* man:lttng-snapshot(1) -* man:lttng-start(1) -* man:lttng-status(1) -* man:lttng-stop(1) -* man:lttng-track(1) -* man:lttng-untrack(1) -* man:lttng-view(1) - -Set the current tracing session manually with the -man:lttng-set-session(1) command, without having to edit the `.lttngrc` -file. - - [[modes]] Tracing session modes ~~~~~~~~~~~~~~~~~~~~~ -LTTng offers four tracing session modes: +As documented in man:lttng-concepts(7), LTTng offers four tracing +session modes: [[local-mode]]Local mode:: Write the trace data to the local file system. + -The option:--output option specifies the trace path. Using -option:--set-url=++file://++__DIR__ is equivalent to using -option:--output='DIR'. -+ -Disable the file system output with the -option:--no-output option. +The trace data output directory is: + -If you don't use any of the option:--output, option:--set-url, or -option:--no-output options, then LTTng writes the trace data locally to -the `$LTTNG_HOME/lttng-traces` directory (`$LTTNG_HOME` defaults to -`$HOME`). +With the option:--no-output option::: + None: the file system output is disabled. + +With the option:--output='DIR' or option:--set-url=++file://++__DIR__ option::: + The directory 'DIR'. + +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. [[network-streaming-mode]]Network streaming mode:: Send the trace data over the network to a listening relay daemon @@ -165,26 +117,28 @@ with the option:--ctrl-url and option:--data-url options (see the <> section below). [[snapshot-mode]]Snapshot mode (option:--snapshot option):: - Don't write the trace data to the local file system by default - (implicit option:--no-output option): only write the trace data to - the local file system or send it to a listening relay daemon - (man:lttng-relayd(8)) when LTTng takes a snapshot. + Only write the trace data to the local file system or send it to a + listening relay daemon (man:lttng-relayd(8)) when LTTng takes a + snapshot (see the man:lttng-snapshot(1) command). + -LTTng automatically configures the channels of such a tracing session to -be snapshot-ready on creation (see man:lttng-enable-channel(1)). +With this mode, LTTng: + -LTTng takes a snapshot of such a tracing session when: -+ --- -* You run the man:lttng-snapshot(1) command. -* LTTng executes a `snapshot-session` trigger action (see - man:lttng-add-trigger(1)). --- +With the option:--no-output option::: + Does :not: add any snapshot output to the created tracing + 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. + +Otherwise::: + Adds an automatic snapshot output named `snapshot-1` to the created + tracing session. + -Set the default snapshot output destination with the -option:--set-url option, or with the option:--ctrl-url and -option:--data-url options (see the <> section -below). +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 +date/time. [[live-mode]]Live mode (option:--live option):: Send the trace data over the network to a listening relay daemon @@ -199,10 +153,10 @@ with `file://`. [[url-format]] URL format ~~~~~~~~~~ -The argument of the option:--set-url, option:--ctrl-url, and -option:--data-url options is an URL. +The argument of the option:--set-url='URL', option:--ctrl-url='URL', and +option:--data-url='URL' options is an URL. -There are two available URL formats. +There are two available 'URL' formats. Local format:: + @@ -226,8 +180,8 @@ Network format:: {nbsp} + This format is only available when you create the tracing session in -network streaming, snapshot, or live mode (see the <> section above). +network streaming, snapshot (option:--snapshot), or live (option:--live) +mode (see the <> section above). + 'NETPROTO'::: Network protocol, amongst: @@ -261,9 +215,10 @@ option:--data-url options together. -- + ('HOST' | 'IPADDR')::: - Hostname or IP address (IPv6 address *must* be enclosed in square - brackets (`[` and{nbsp}`]`); see - https://www.ietf.org/rfc/rfc2732.txt[RFC{nbsp}2732]). + Hostname or IP address. ++ +IPv6 address must be enclosed in square brackets (`[` and{nbsp}`]`); +see https://www.ietf.org/rfc/rfc2732.txt[RFC{nbsp}2732]. 'CTRLPORT'::: Control TCP port. @@ -305,24 +260,48 @@ The session daemon must be able to connect to a listening relay daemon option:--snapshot:: Create the tracing session in snapshot mode. + -This is equivalent to using the option:--no-output option and creating -all the channels of this new tracing session with the -nloption:--override and nloption:--output=++mmap++ options (see -man:lttng-enable-channel(1)). +This is equivalent to: ++ +* One of: ++ +-- +With the option:--no-output option:: + Not adding any snapshot output after LTTng creates the tracing + 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. + +Otherwise:: + Adding an automatic snapshot output named `snapshot-1` immediately + after LTTng creates the tracing 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 +date/time. +-- + +* Forcing all the channels to be created for the tracing session to be + configured with the nloption:--override and nloption:--output=++mmap++ + options (see man:lttng-enable-channel(1)). Output ~~~~~~ option:--no-output:: - In local mode (see the <> section - above), do :not: write any trace data. + Depending on the tracing session mode (see the <> section above): + -You may :not: use this option with the option:--output option. +Local mode::: + Disable the file system output. + +Snapshot mode (option:--snapshot option)::: + Do :not: add a snapshot output after creating the tracing session. option:-o 'DIR', option:--output='DIR':: - In local mode, set the trace output path to 'DIR'. -+ -You may :not: use this option with the option:--no-output option. + Equivalent to option:--set-url=++file://++__DIR__. option:--shm-path='DIR':: Set the path of the directory containing the shared memory files @@ -338,20 +317,46 @@ option:-C 'URL', option:--ctrl-url='URL':: Set the control path URL to 'URL'. + You must also use the option:--data-url option. ++ +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. 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). ++ +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. option:-U 'URL', option:--set-url='URL':: Set the destination URL of the control path and trace data to 'URL'. + -This URL stays the same as long as the tracing session exists. +This URL remains unchanged as long as the tracing session exists. ++ +Depending on the tracing session mode (see the <> section above): + -In local mode (see the <> section above), -'URL' must start with `file://`, followed with the destination directory -path on the local file system. +Local mode::: + 'URL' must start with `file://`, followed with the destination + directory path on the local file system. + +Network streaming and live modes::: + Equivalent to using both the option:--ctrl-url and option:--data-url + options. + +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. include::common-cmd-help-options.txt[] @@ -363,12 +368,15 @@ include::common-cmd-footer.txt[] SEE ALSO -------- man:lttng(1), +man:lttng-concepts(7), man:lttng-destroy(1), man:lttng-enable-channel(1), +man:lttng-list(8), man:lttng-relayd(8), man:lttng-rotate(1), +man:lttng-save(1), man:lttng-sessiond(8), man:lttng-set-session(1), man:lttng-start(1), -man:lttng-stop(1), +man:lttng-status(8), man:lttng-track(1) diff --git a/doc/man/lttng-destroy.1.txt b/doc/man/lttng-destroy.1.txt index 2ddd05a99..5084485fd 100644 --- a/doc/man/lttng-destroy.1.txt +++ b/doc/man/lttng-destroy.1.txt @@ -1,6 +1,6 @@ lttng-destroy(1) ================ -:revdate: 12 April 2021 +:revdate: 3 May 2021 NAME @@ -16,47 +16,48 @@ SYNOPSIS DESCRIPTION ----------- -The `lttng destroy` command destroys one or more tracing sessions -previously created with the man:lttng-create(1) command. - -``Destroying'' a tracing session means freeing the resources acquired by -the LTTng daemons and tracers 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 -session mode. - -Use the `destroy` command to destroy: +The `lttng destroy` command destroys: With the 'SESSION' argument:: The tracing session named 'SESSION'. With the option:--all option:: - *All* the tracing sessions of your Unix user, - as listed in the output of `lttng list` (see man:lttng-list(1)). + *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)). ++ +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-create(1) and - man:lttng-set-session(1) to learn more about the current tracing - session). + The current tracing session (see man:lttng-concepts(7) to learn more + about the current tracing session). + In that case, the current tracing session becomes nonexistent. +See man:lttng-concepts(7) to learn more about tracing sessions. + +``Destroying'' a tracing 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 +session mode. + The `destroy` command stops any tracing activity within the selected -tracing session(s). By default, the command runs the implicit +tracing session(s). By default, the command runs an implicit man:lttng-stop(1) command to ensure that the trace data of the tracing 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 becomes valid. +when it/they become valid. If, for a tracing session{nbsp}__TS__ to destroy with the `destroy` command, the following statements are true: -* You don't use the option:--no-wait option. +* You don't specify the option:--no-wait option. -* LTTng archived the current trace chunk (see man:lttng-rotate(1) and - man:lttng-enable-rotation(1)) of{nbsp}__TS__ at least once during its - lifetime. +* LTTng archived the current trace chunk (see man:lttng-concepts(7)) + of{nbsp}__TS__ at least once during its lifetime. Then all the subdirectories of the output directory of{nbsp}__TS__ (local or remote) are considered trace chunk archives once the `destroy` @@ -68,8 +69,10 @@ include::common-cmd-options-head.txt[] option:-a, option:--all:: - Destroy all the tracing sessions of your Unix user, as listed in the - output of man:lttng-list(1). + 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'. option:-n, option:--no-wait:: Do :not: ensure that the trace data of the tracing session(s) to @@ -85,6 +88,6 @@ include::common-cmd-footer.txt[] SEE ALSO -------- man:lttng(1), +man:lttng-concepts(7), man:lttng-create(1), -man:lttng-list(1), -man:lttng-set-session(1) +man:lttng-list(1) diff --git a/doc/man/lttng-disable-channel.1.txt b/doc/man/lttng-disable-channel.1.txt index be845e65d..164dfdd2f 100644 --- a/doc/man/lttng-disable-channel.1.txt +++ b/doc/man/lttng-disable-channel.1.txt @@ -1,6 +1,6 @@ lttng-disable-channel(1) ======================== -:revdate: 21 April 2021 +:revdate: 29 April 2021 NAME ---- @@ -17,13 +17,17 @@ SYNOPSIS DESCRIPTION ----------- The `lttng disable-channel` command disables one or more channels -previously enabled with the man:lttng-enable-channel(1) command. +previously enabled with the man:lttng-enable-channel(1) command +which belong to: -A channel always belongs to a tracing session (see man:lttng-create(1) -to create a tracing session). Without the option:--session option, the -`disable-channel` command disables one or more channels of the current -tracing session (see man:lttng-create(1) and man:lttng-set-session(1) to -learn more about the current tracing session). +With the option:--session='SESSION' option:: + The tracing 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). + +See man:lttng-concepts(7) to learn more about channels. The `disable-channel` command disables one channel per 'CHANNEL' argument. @@ -47,8 +51,8 @@ option:-u, option:--userspace:: Disable one or more user space channels. -Target -~~~~~~ +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. @@ -63,4 +67,5 @@ include::common-cmd-footer.txt[] SEE ALSO -------- man:lttng(1), +man:lttng-concepts(7), man:lttng-enable-channel(1) diff --git a/doc/man/lttng-disable-event.1.txt b/doc/man/lttng-disable-event.1.txt index 9719a631c..82cea0988 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: 21 April 2021 +:revdate: 3 May 2021 NAME @@ -33,7 +33,22 @@ DESCRIPTION ----------- The `lttng disable-event` command disables one or more enabled recording event rules previously created with the man:lttng-enable-event(1) -command. +command which belong to: + +With the option:--session='SESSION' option:: + The tracing 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). + +With the option:--channel='CHANNEL' option:: + The channel named 'CHANNEL'. + +Without the option:--channel option:: + The channel named `channel0`. + +See man:lttng-concepts(7) to learn more about recording event rules. As of LTTng{nbsp}{lttng_version}, the `disable-event` command can only find recording event rules to disable by their instrumentation point @@ -41,7 +56,7 @@ type and event name conditions. Therefore, you cannot disable recording event rules having a specific instrumentation point log level condition, for example. -List the existing recording event rules of a given tracing session +List the recording event rules of a given tracing session and/or channel with the man:lttng-list(1) command. Without the option:--all-events option, the `disable-event` command @@ -50,14 +65,6 @@ exact event name condition pattern of the recording event rule to disable, as listed in the output of `lttng list` (see man:lttng-list(1)). -Without the option:--channel option, the `disable-event` command selects -the channel named `channel0`. - -Without the option:--session option, the `disable-event` command selects -the current tracing session (see man:lttng-create(1) and -man:lttng-set-session(1) to learn more about the current tracing -session). - You may disable an enabled recording event rule regardless of the activity (started or stopped) of its tracing session (see man:lttng-start(1) and man:lttng-stop(1)). @@ -137,7 +144,7 @@ Event name condition ~~~~~~~~~~~~~~~~~~~~ option:-a, option:--all-events:: Disable recording event rules regardless of their event name - condition is. + condition. include::common-cmd-help-options.txt[] @@ -149,5 +156,6 @@ include::common-cmd-footer.txt[] SEE ALSO -------- man:lttng(1), +man:lttng-concepts(7), man:lttng-enable-event(1), man:lttng-list(1) diff --git a/doc/man/lttng-disable-rotation.1.txt b/doc/man/lttng-disable-rotation.1.txt index f9255a94e..0c23031a6 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: 21 April 2021 +:revdate: 30 April 2021 NAME ---- -lttng-disable-rotation - Unset a tracing session rotation schedule +lttng-disable-rotation - Unset an LTTng tracing session rotation schedule SYNOPSIS @@ -24,9 +24,11 @@ With the option:--session='SESSION' option:: The tracing session named 'SESSION'. Without the option:--session option:: - The current tracing session (see man:lttng-create(1) and - man:lttng-set-session(1) to learn more about the current tracing - session). + The current tracing session (see man:lttng-concepts(7) to learn more + about the current tracing session). + +See man:lttng-concepts(7) to learn more about the tracing session +rotation and trace chunk concepts. include::common-cmd-options-head.txt[] diff --git a/doc/man/lttng-enable-channel.1.txt b/doc/man/lttng-enable-channel.1.txt index b9c6d1696..271ada1ce 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: 9 November 2018 +:revdate: 3 May 2021 NAME @@ -14,25 +14,26 @@ Create a Linux kernel channel: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-channel* option:--kernel - [option:--overwrite] [option:--output=(`mmap` | `splice`)] + [option:--discard | option:--overwrite] [option:--output=(**mmap** | **splice**)] [option:--subbuf-size='SIZE'] [option:--num-subbuf='COUNT'] [option:--switch-timer='PERIODUS'] [option:--read-timer='PERIODUS'] - [option:--monitor-timer='PERIODUS'] - [option:--tracefile-size='SIZE'] [option:--tracefile-count='COUNT'] + [option:--monitor-timer='PERIODUS'] [option:--buffers-global] + [option:--tracefile-size='SIZE' [option:--tracefile-count='COUNT']] [option:--session='SESSION'] 'CHANNEL' Create a user space channel: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-channel* option:--userspace - [option:--overwrite | option:--blocking-timeout='TIMEOUTUS'] [option:--buffers-pid] + [option:--overwrite | [option:--discard] option:--blocking-timeout='TIMEOUTUS'] + [option:--output=**mmap**] [option:--buffers-uid | option:--buffers-pid] [option:--subbuf-size='SIZE'] [option:--num-subbuf='COUNT'] [option:--switch-timer='PERIODUS'] [option:--read-timer='PERIODUS'] [option:--monitor-timer='PERIODUS'] - [option:--tracefile-size='SIZE'] [option:--tracefile-count='COUNT'] + [option:--tracefile-size='SIZE' [option:--tracefile-count='COUNT']] [option:--session='SESSION'] 'CHANNEL' -Enable existing channel(s): +Enable channel(s): [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-channel* (option:--userspace | option:--kernel) @@ -41,425 +42,318 @@ Enable existing channel(s): DESCRIPTION ----------- -The `lttng enable-channel` command can create a new channel, or enable -one or more existing and disabled ones. - -A channel is the owner of sub-buffers holding recorded events. Recording -event rules, when created using man:lttng-enable-event(1), are always -assigned to a channel. When creating a new channel, many parameters -related to those sub-buffers can be fine-tuned. They are described in -the subsections below. +The `lttng enable-channel` command does one of: -When 'CHANNEL' does not name an existing channel, a channel named -'CHANNEL' is created. Otherwise, the disabled channel named 'CHANNEL' -is enabled. +* Create a channel named 'CHANNEL'. -Note that the man:lttng-enable-event(1) command can automatically -create default channels when no channel exist. +* Enable one or more disabled channels named 'CHANNEL' + (non-option argument, comma-separated). -A channel is always contained in a tracing session -(see man:lttng-create(1) for creating a tracing session). The -session in which a channel is created using `lttng enable-channel` can -be specified using the option:--session option. If the option:--session -option is omitted, the current tracing session is targeted. +See man:lttng-concepts(7) to learn more about channels. -Existing enabled channels can be disabled using -man:lttng-disable-channel(1). Channels of a given session can be -listed using man:lttng-list(1). +The channel(s) to create or enable belong to: -See the <> section below for a list of -limitations of this command to consider. +With the option:--session='SESSION' option:: + The tracing 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). -Event loss modes -~~~~~~~~~~~~~~~~ -LTTng tracers are non-blocking by default: when no empty sub-buffer -exists, losing events is acceptable when the alternative would be to -cause substantial delays in the instrumented application's execution. - -LTTng privileges performance over integrity, aiming at perturbing the -traced system as little as possible in order to make tracing of subtle -race conditions and rare interrupt cascades possible. - -You can allow the user space tracer to block with a -option:--blocking-timeout option set to a positive value or to `inf`, -and with an application which is instrumented with LTTng-UST started -with a set `LTTNG_UST_ALLOW_BLOCKING` environment variable. See -man:lttng-ust(3) for more details. - -When it comes to losing events because no empty sub-buffer is available, -the channel's event loss mode, specified by one of the option:--discard -and option:--overwrite options, determines what to do amongst: - -Discard:: - Drop the newest events until a sub-buffer is released. - -Overwrite:: - Clear the sub-buffer containing the oldest recorded events and start - recording the newest events there. This mode is sometimes called - _flight recorder mode_ because it behaves like a flight recorder: - always keep a fixed amount of the latest data. - -Which mechanism to choose depends on the context: prioritize the newest -or the oldest events in the ring buffer? - -Beware that, in overwrite mode (option:--overwrite option), a whole -sub-buffer is abandoned as soon as a new event doesn't find an empty -sub-buffer, whereas in discard mode (option:--discard option), only the -event that doesn't fit is discarded. - -Also note that a count of lost events is incremented and saved in the -trace itself when an event is lost in discard mode, whereas no -information is kept when a sub-buffer gets overwritten before being -committed. - -The probability of losing events, if it is experience in a given -context, can be reduced by fine-tuning the sub-buffers count and size -(see next subsection). - - -Sub-buffers count and size -~~~~~~~~~~~~~~~~~~~~~~~~~~ -The option:--num-subbuf and option:--subbuf-size options respectively -set the number of sub-buffers and their individual size when creating -a new channel. - -Note that there is a noticeable tracer's CPU overhead introduced when -switching sub-buffers (marking a full one as consumable and switching -to an empty one for the following events to be recorded). Knowing this, -the following list presents a few practical situations along with how -to configure sub-buffers for them when creating a channel in overwrite -mode (option:--overwrite option): - -High event throughput:: - In general, prefer bigger sub-buffers to lower the risk of losing - events. Having bigger sub-buffers also ensures a lower sub-buffer - switching frequency. The number of sub-buffers is only meaningful - if the channel is enabled in overwrite mode: in this case, if a - sub-buffer overwrite happens, the other sub-buffers - are left unaltered. - -Low event throughput:: - In general, prefer smaller sub-buffers since the risk of losing - events is already low. Since events happen less frequently, the - sub-buffer switching frequency should remain low and thus the - tracer's overhead should not be a problem. - -Low memory system:: - If the target system has a low memory limit, prefer fewer first, - then smaller sub-buffers. Even if the system is limited in memory, - it is recommended to keep the sub-buffers as big as possible to - avoid a high sub-buffer switching frequency. - -In discard mode (option:--discard option), the sub-buffers count -parameter is pointless: using two sub-buffers and setting their size -according to the requirements of the context is fine. - - -Switch timer -~~~~~~~~~~~~ -When a channel's switch timer fires, a sub-buffer switch happens. This -timer may be used to ensure that event data is consumed and committed -to trace files periodically in case of a low event throughput. - -It's also convenient when big sub-buffers are used to cope with sporadic -high event throughput, even if the throughput is normally lower. - -Use the option:--switch-timer option to control the switch timer's -period of the channel to create. - - -Read timer -~~~~~~~~~~ -By default, an internal notification mechanism is used to signal a full -sub-buffer so that it can be consumed. When such notifications must be -avoided, for example in real-time applications, the channel's read timer -can be used instead. When the read timer fires, sub-buffers are checked -for consumption when they are full. - -Use the option:--read-timer option to control the read timer's period of -the channel to create. - - -Monitor timer -~~~~~~~~~~~~~ -When a channel's monitor timer fires, its registered trigger conditions -are evaluated using the current values of its properties (for example, -the current usage of its sub-buffers). When a trigger condition is true, -LTTng executes its associated action. The only type of action currently -supported is to notify one or more user applications. - -See the installed $$C/C++$$ headers in `lttng/action`, -`lttng/condition`, `lttng/notification`, and `lttng/trigger` to learn -more about application notifications and triggers. - -Use the option:--monitor-timer option to control the monitor timer's -period of the channel to create. +NOTE: The man:lttng-enable-event(1) command can automatically create a +default channel when no channel exists for the provided tracing domain. +List the channels of a given tracing session with the +man:lttng-list(1) and man:lttng-status(1) commands. -Buffering scheme -~~~~~~~~~~~~~~~~ -In the user space tracing domain, two buffering schemes are available -when creating a channel: +Disable an enabled channel with the man:lttng-disable-channel(1) +command. -Per-process buffering (option:--buffers-pid option):: - Keep one ring buffer per process. +[IMPORTANT] +==== +As of LTTng{nbsp}{lttng_version}, you may :not: perform the following +operations with the `enable-channel` command: -Per-user buffering (option:--buffers-uid option):: - Keep one ring buffer for all the processes of a single user. +* Change an attribute of an existing channel. -The per-process buffering scheme consumes more memory than the per-user -option if more than one process is instrumented for LTTng-UST. -However, per-process buffering ensures that one process having a high -event throughput won't fill all the shared sub-buffers, only its own. +* Enable a disabled channel once its tracing session has been active + (started; see man:lttng-start(1)) at least once. -The Linux kernel tracing domain only has one available buffering scheme -which is to use a single ring buffer for the whole system -(option:--buffers-global option). +* Create a channel once its tracing 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. +==== -Trace files limit and size -~~~~~~~~~~~~~~~~~~~~~~~~~~ -By default, trace files can grow as large as needed. The maximum size -of each trace file written by a channel can be set on creation using the -option:--tracefile-size option. When such a trace file's size reaches -the channel's fixed maximum size, another trace file is created to hold -the next recorded events. A file count is appended to each trace file -name in this case. -If the option:--tracefile-size option is used, the maximum number of -created trace files is unlimited. To limit them, the -option:--tracefile-count option can be used. This option is always used -in conjunction with the option:--tracefile-size option. +include::common-cmd-options-head.txt[] -For example, consider this command: -[role="term"] ----- -$ lttng enable-channel --kernel --tracefile-size=4096 \ - --tracefile-count=32 my-channel ----- +Tracing domain +~~~~~~~~~~~~~~ +One of: -Here, for each stream, the maximum size of each trace file is -4 kiB and there can be a maximum of 32 different files. When there is -no space left in the last file, _trace file rotation_ happens: the first -file is cleared and new sub-buffers containing events are written there. +option:-k, option:--kernel:: + Create or enable channels in the Linux kernel domain. -LTTng does not guarantee that you can view the trace of an active -tracing session before you run the man:lttng-stop(1) command, even -with multiple trace files, because LTTng could overwrite them at any -moment, or some of them could be incomplete. You can archive a -tracing session's current trace chunk while the tracing session is -active to obtain an unmanaged and self-contained LTTng trace: see -the man:lttng-rotate(1) and man:lttng-enable-rotation(1) commands. +option:-u, option:--userspace:: + Create or enable channels in the user space domain. -include::common-cmd-options-head.txt[] +Recording target +~~~~~~~~~~~~~~~~ +option:-s 'SESSION', option:--session='SESSION':: + Create or enable channels in the tracing session named 'SESSION' + instead of the current tracing session. -Domain -~~~~~~ +Buffering scheme +~~~~~~~~~~~~~~~~ One of: -option:-k, option:--kernel:: - Enable channel in the Linux kernel domain. +option:--buffers-global:: + Allocate a single set of ring buffers for the whole system. ++ +Only available with the option:--kernel option. ++ +As of LTTng{nbsp}{lttng_version}, this is the default buffering scheme +for the Linux kernel tracing domain, but this may change in the future. -option:-u, option:--userspace:: - Enable channel in the user space domain. +option:--buffers-pid:: + Allocate one set of ring buffers (one per CPU) for each instrumented + process of: ++ +-- +If you connect to the root session daemon:: + All Unix users. ++ +See the ``Session daemon connection'' section of man:lttng(1) to learn +how a user application connects to a session daemon. +Otherwise:: + Your Unix user. +-- ++ +Only available with the option:--userspace option. -Target -~~~~~~ -option:-s 'SESSION', option:--session='SESSION':: - Create or enable channel in the tracing session named 'SESSION' - instead of the current tracing session. +option:--buffers-uid:: + Allocate one set of ring buffers (one per CPU) shared by all the + instrumented processes of: ++ +-- +If you connect to the root session daemon:: + Each Unix user. ++ +See the ``Session daemon connection'' section of man:lttng(1) to learn +how a user application connects to a session daemon. + +Otherwise:: + Your Unix user. +-- ++ +Only available with the option:--userspace option. ++ +As of LTTng{nbsp}{lttng_version}, this is the default buffering scheme +for the user space tracing domain, but this may change in the future. -Event loss mode -~~~~~~~~~~~~~~~ +Event record loss mode +~~~~~~~~~~~~~~~~~~~~~~ option:--blocking-timeout='TIMEOUTUS':: - Set the channel's blocking timeout value to 'TIMEOUTUS' µs for - instrumented applications executed with a set - `LTTNG_UST_ALLOW_BLOCKING` environment variable: + Set the channel's blocking timeout value to __TIMEOUTUS__{nbsp}µs + for instrumented applications executed with a set + `LTTNG_UST_ALLOW_BLOCKING` environment variable. ++ +'TIMEOUTUS' is one of: + -- -0 (default):: +`0` (default):: Do not block (non-blocking mode). `inf`:: - Block forever until room is available in the sub-buffer to write the - event record. + Block forever until a sub-buffer is available to write the event + record. -__n__, a positive value:: - Wait for at most __n__ µs when trying to write into a sub-buffer. - After __n__ µs, discard the event record. +__N__, a positive value:: + Wait for at most __N__{nbsp}µs when trying to write to a sub-buffer. + After __N__{nbsp}µs, discard the event record. -- + -This option is only available with the option:--userspace option and -without the option:--overwrite option. +This option is only available with both the option:--userspace and +option:--discard options. One of: option:--discard:: - Discard events when sub-buffers are full (default). + Discard event records when there's no available sub-buffer. ++ +As of LTTng{nbsp}{lttng_version}, this is the default event record loss +mode, but this may change in the future. option:--overwrite:: - Flight recorder mode: always keep a fixed amount of the latest - data. + Overwrite the whole sub-buffer containing the oldest event records + when there's no available sub-buffer (flight recorder mode). Sub-buffers ~~~~~~~~~~~ option:--num-subbuf='COUNT':: - Use 'COUNT' sub-buffers. Rounded up to the next power of two. + Use 'COUNT' sub-buffers per ring buffer. ++ +The effective value is 'COUNT' rounded up to the next power of two. + Default values: + -* option:--userspace and option:--buffers-uid options: - {default_ust_uid_channel_subbuf_num} -* option:--userspace and option:--buffers-pid options: - {default_ust_pid_channel_subbuf_num} -* option:--kernel option: {default_kernel_channel_subbuf_num} -* `metadata` channel: {default_metadata_subbuf_num} +option:--userspace and option:--buffers-uid options::: + +{default_ust_uid_channel_subbuf_num}+ +option:--userspace and option:--buffers-pid options::: + +{default_ust_pid_channel_subbuf_num}+ +option:--kernel and option:--buffers-global options::: + +{default_kernel_channel_subbuf_num}+ +`metadata` channel::: + +{default_metadata_subbuf_num}+ option:--output='TYPE':: Set channel's output type to 'TYPE'. + -Available types: `mmap` (always available) and `splice` (only available -with the option:--kernel option). +'TYPE' is one of: ++ +-- +`mmap`::: + Share ring buffers between the tracer and the consumer daemon with + the man:mmap(2) system call. + +`splice`::: + Share ring buffers between the tracer and the consumer daemon + with the man:splice(2) system call. ++ +Only available with the option:--kernel option. +-- + Default values: + -* option:--userspace and option:--buffers-uid options: `mmap` -* option:--userspace and option:--buffers-pid options: `mmap` -* option:--kernel option: `splice` -* `metadata` channel: `mmap` +option:--userspace and option:--buffers-uid options::: + `mmap` +option:--userspace and option:--buffers-pid options::: + `mmap` +option:--kernel and option:--buffers-global options::: + `splice` +`metadata` channel::: + `mmap` option:--subbuf-size='SIZE':: - Set the individual size of sub-buffers to 'SIZE' bytes. - The `k` (kiB), `M` (MiB), and `G` (GiB) suffixes are supported. - Rounded up to the next power of two. + Set the size of each sub-buffer to 'SIZE' bytes. ++ +The effective value is 'SIZE' rounded up to the next power of two. ++ +The `k`{nbsp}(KiB), `M`{nbsp}(MiB), and `G`{nbsp}(GiB) suffixes are +supported. + The minimum sub-buffer size, for each tracer, is the maximum value -between the default below and the system's page size. The following -command shows the current system's page size: `getconf PAGE_SIZE`. +between the default below and the system page size (see man:getconf(1) +with the `PAGE_SIZE` variable). + Default values: + -* option:--userspace and option:--buffers-uid options: - {default_ust_uid_channel_subbuf_size} -* option:--userspace and option:--buffers-pid options: - {default_ust_pid_channel_subbuf_size} -* option:--kernel option: {default_kernel_channel_subbuf_size} -* `metadata` channel: {default_metadata_subbuf_size} - - -Buffering scheme -~~~~~~~~~~~~~~~~ -One of: - -option:--buffers-global:: - Use shared sub-buffers for the whole system (only available with the - option:--kernel option). - -option:--buffers-pid:: - Use different sub-buffers for each traced process (only available - with the the option:--userspace option). This is the default - buffering scheme for user space channels. - -option:--buffers-uid:: - Use shared sub-buffers for all the processes of the user running - the command (only available with the option:--userspace option). +option:--userspace and option:--buffers-uid options::: + +{default_ust_uid_channel_subbuf_size}+ +option:--userspace and option:--buffers-pid options::: + +{default_ust_pid_channel_subbuf_size}+ +option:--kernel and option:--buffers-global options::: + +{default_kernel_channel_subbuf_size}+ +`metadata` channel::: + +{default_metadata_subbuf_size}+ Trace files ~~~~~~~~~~~ option:--tracefile-count='COUNT':: - Limit the number of trace files created by this channel to - 'COUNT'. 0 means unlimited. Default: - {default_channel_tracefile_count}. + Limit the number of trace files which LTTng writes for this channel + to 'COUNT'. + -Use this option in conjunction with the option:--tracefile-size option. +'COUNT' set to `0` means ``unlimited''. + -The file count within a stream is appended to each created trace -file. If 'COUNT' files are created and more events need to be recorded, -the first trace file of the stream is cleared and used again. +Default: +{default_channel_tracefile_count}+. ++ +You must also use the option:--tracefile-size option with this option. option:--tracefile-size='SIZE':: - Set the maximum size of each trace file written by - this channel within a stream to 'SIZE' bytes. 0 means unlimited. - Default: {default_channel_tracefile_size}. + Set the maximum size of each trace file which LTTng writes for + this channel to __SIZE__{nbsp}bytes. ++ +'SIZE' set to `0` means ``unlimited''. ++ +Default: +{default_channel_tracefile_size}+. + -Note: traces generated with this option may inaccurately report -discarded events as of CTF 1.8. +NOTE: Data streams which LTTng writes for a channel configured with this +option may inaccurately report discarded event records as of +CTF{nbsp}1.8. Timers ~~~~~~ -option:--monitor-timer:: - Set the channel's monitor timer's period to 'PERIODUS' µs. 0 means a - disabled monitor timer. +option:--monitor-timer='PERIODUS':: + Set the period of the monitor timer of the channel to + __PERIODUS__{nbsp}µs. ++ +Set 'PERIODUS' to `0` to disable the monitor timer. + Default values: + -* option:--userspace and option:--buffers-uid options: - {default_ust_uid_channel_monitor_timer} -* option:--userspace and option:--buffers-pid options: - {default_ust_pid_channel_monitor_timer} -* option:--kernel option: {default_kernel_channel_monitor_timer} - -option:--read-timer:: - Set the channel's read timer's period to 'PERIODUS' µs. 0 means a - disabled read timer. +option:--userspace and option:--buffers-uid options::: + +{default_ust_uid_channel_monitor_timer}+ +option:--userspace and option:--buffers-pid options::: + +{default_ust_pid_channel_monitor_timer}+ +option:--kernel and option:--buffers-global options::: + +{default_kernel_channel_monitor_timer}+ + +option:--read-timer='PERIODUS':: + Set the period of the read timer of the channel to + __PERIODUS__{nbsp}µs. ++ +Set 'PERIODUS' to `0` to disable the read timer. + Default values: + -* option:--userspace and option:--buffers-uid options: - {default_ust_uid_channel_read_timer} -* option:--userspace and option:--buffers-pid options: - {default_ust_pid_channel_read_timer} -* option:--kernel option: {default_kernel_channel_read_timer} -* `metadata` channel: {default_metadata_read_timer} +option:--userspace and option:--buffers-uid options::: + +{default_ust_uid_channel_read_timer}+ +option:--userspace and option:--buffers-pid options::: + +{default_ust_pid_channel_read_timer}+ +option:--kernel and option:--buffers-global options::: + +{default_kernel_channel_read_timer}+ +`metadata` channel::: + +{default_metadata_read_timer}+ option:--switch-timer='PERIODUS':: - Set the channel's switch timer's period to 'PERIODUS' µs. 0 means - a disabled switch timer. + Set the period of the switch timer of the channel to + __PERIODUS__{nbsp}µs. ++ +Set 'PERIODUS' to `0` to disable the switch timer. + Default values: + -* option:--userspace and option:--buffers-uid options: - {default_ust_uid_channel_switch_timer} -* option:--userspace and option:--buffers-pid options: - {default_ust_pid_channel_switch_timer} -* option:--kernel option: {default_kernel_channel_switch_timer} -* `metadata` channel: {default_metadata_switch_timer} +option:--userspace and option:--buffers-uid options::: + +{default_ust_uid_channel_switch_timer}+ +option:--userspace and option:--buffers-pid options::: + +{default_ust_pid_channel_switch_timer}+ +option:--kernel and option:--buffers-global options::: + +{default_kernel_channel_switch_timer}+ +`metadata` channel::: + +{default_metadata_switch_timer}+ include::common-cmd-help-options.txt[] -[[limitations]] -LIMITATIONS ------------ -As of this version of LTTng, it is not possible to perform the following -actions with the `lttng enable-channel` command: - -* Reconfigure a channel once it is created. -* Re-enable a disabled channel once its tracing session has been active - at least once. -* Create a channel once its tracing 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. - - include::common-cmd-footer.txt[] SEE ALSO -------- -man:lttng-disable-channel(1), man:lttng(1), -man:lttng-ust(3) +man:lttng-concepts(7), +man:lttng-disable-channel(1), +man:lttng-list(1) diff --git a/doc/man/lttng-enable-event.1.txt b/doc/man/lttng-enable-event.1.txt index 6acdbcd29..5b096227e 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: 13 April 2021 +:revdate: 3 May 2021 NAME @@ -50,98 +50,42 @@ The `lttng enable-event` command does one of: * Create one or more recording event rules. -* Enable one or more existing, disabled recording event rules. +* Enable one or more disabled recording event rules. + See the <> section below. -An _instrumentation point_ is a point, within a piece of software, -which, when executed, creates an LTTng _event_. +See man:lttng-concepts(7) to learn more about instrumentation points, +events, recording event rules, and event records. -LTTng offers various types of instrumentation; see the -<> section -below to learn about them. - -An _event rule_ is a set of conditions to match a set of events. A -_recording event rule_ is a specific type of event rule of which the -associated action is to serialize and record the matched event. - -When LTTng creates an event{nbsp}__E__, a recording event -rule{nbsp}__ER__ is said to __match__{nbsp}__E__ when{nbsp}__E__ -satisfies *all* the conditions of{nbsp}__ER__. This concept is similar -to a regular expression which matches a set of strings. - -When a recording event rule matches an event, LTTng _emits_ the event, -therefore attempting to serialize and record it to one of the -sub-buffers of its attached channel (see man:lttng-enable-channel(1) to -learn more about LTTng channels). - -Without the option:--channel option, the `enable-event` command selects -the channel named `channel0`. When the `enable-event` command creates a -recording event rule, it automatically creates the `channel0` channel -(for the specified tracing domain in the selected tracing session) if it -doesn't exist. - -When multiple matching recording event rules are attached to the same -channel, LTTng attempts to serialize and record the matched event -_once_. In the following example, the second recording event -rule is redundant when both are enabled: - -[role="term"] ----- -$ lttng enable-event --userspace hello:world -$ lttng enable-event --userspace hello:world --loglevel=TRACE_INFO ----- +The recording event rule(s) to create or enable belong to: -Without the option:--session option, the `enable-event` command selects -the current tracing session (see man:lttng-create(1) and -man:lttng-set-session(1) to learn more about the current tracing -session). +With the option:--session='SESSION' option:: + The tracing session named 'SESSION'. -[NOTE] -==== -The event creation and emission processes are documentation concepts to -help understand the journey from an instrumentation point to the -serialization and recording of an event. - -The actual creation of an event can be costly because LTTng needs to -evalute the arguments of the instrumentation point. - -In practice, LTTng implements various optimizations for the Linux kernel -and user space tracing domains (option:--kernel and option:--userspace -options) to avoid actually creating an event when the tracer knows, -thanks to properties which are independent from the event payload and -current context, that it would never emit such an event. Those -properties are: - -* The status of the rule itself (enabled or disabled). -* The status of the channel (enabled or disabled; see - man:lttng-enable-channel(1) and man:lttng-disable-channel(1)). -* The activity of the tracing session (started or stopped; see - man:lttng-start(1) and man:lttng-stop(1)). -* The instrumentation point type (see the - <> section below). -* The instrumentation point name (or event name) - (see the <> section below). -* The instrumentation point log level (see the - <> - section below). - -In other words: if, for a given instrumentation point{nbsp}__IP__, the -LTTng tracer knows that it would never emit and record an event, -executing{nbsp}__IP__ represents a simple boolean variable check and, -for the kernel tracer, a few process attribute checks. -==== +Without the option:--session option:: + The current tracing session (see man:lttng-concepts(7) to learn more + about the current tracing session). + +With the option:--channel='CHANNEL' option:: + The channel named 'CHANNEL'. -List the existing recording event rules of a given tracing session -and/or channel with the man:lttng-list(1) command. +Without the option:--channel option:: + The channel named `channel0`. ++ +If such a channel doesn't exist, the `enable-event` automatically +creates it. -Disable an existing, enabled recording event rule with the +List the recording event rules of a specific tracing session +and/or channel with the man:lttng-list(1) and man:lttng-status(1) +commands. + +Disable an enabled recording event rule with the man:lttng-disable-event(1) command. -Recording event rule overview -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Overview of recording event rule conditions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ For LTTng to emit and record an event{nbsp}__E__,{nbsp}__E__ must satisfy *all* the conditions of a recording event rule{nbsp}__ER__, that is: @@ -183,15 +127,13 @@ Implicit conditions:: + A recording event rule is enabled on creation. + -Enable an existing, disabled recording event rule with the -`enable-event` command. +Enable a disabled recording event rule with the `enable-event` command. * The channel to which{nbsp}__ER__ is attached is enabled. + A channel is enabled on creation. + -Enable an existing, disabled channel with the -man:lttng-enable-channel(1) command. +Enable a disabled channel with the man:lttng-enable-channel(1) command. * The tracing session of{nbsp}__ER__ is active (started). + @@ -199,8 +141,8 @@ A tracing session is inactive (stopped) on creation. + Start an inactive tracing session with the man:lttng-start(1) command. -* The process for which LTTng creates{nbsp}__E__ to match is allowed to - record events. +* The process for which LTTng creates{nbsp}__E__ is allowed to record + events. + All processes are allowed to record events on tracing session creation. @@ -608,8 +550,8 @@ Event record name ~~~~~~~~~~~~~~~~~ When LTTng records an event{nbsp}__E__, the resulting event record has a name which depends on the instrumentation point type condition (see the -<> section) -of the recording event rule which matched{nbsp}__E__: +<> section +above) of the recording event rule which matched{nbsp}__E__: LTTng tracepoint (option:--kernel/option:--userspace and option:--tracepoint options):: Full name of the tracepoint from which LTTng creates{nbsp}__E__. @@ -663,8 +605,8 @@ Linux kretprobe (option:--kernel and option:--function options):: [[enable]] Enable a disabled recording event rule ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The `enable-event` command can enable an existing, disabled recording -event rule, as listed in the output of the man:lttng-list(1) command. +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 @@ -912,6 +854,7 @@ include::common-cmd-footer.txt[] SEE ALSO -------- man:lttng(1), +man:lttng-concepts(7), man:lttng-disable-event(1), man:lttng-enable-channel(1), man:lttng-list(1), diff --git a/doc/man/lttng-enable-rotation.1.txt b/doc/man/lttng-enable-rotation.1.txt index cd8de7309..d8ec88e75 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: 21 April 2021 +:revdate: 3 May 2021 NAME ---- -lttng-enable-rotation - Set a tracing session rotation schedule +lttng-enable-rotation - Set an LTTng tracing session rotation schedule SYNOPSIS @@ -24,12 +24,11 @@ With the option:--session='SESSION' option:: The tracing session named 'SESSION'. Without the option:--session option:: - The current tracing session (see man:lttng-create(1) and - man:lttng-set-session(1) to learn more about the current tracing - session). + The current tracing session (see man:lttng-concepts(7) to learn more + about the current tracing session). -See man:lttng-rotate(1) for more information about the concepts of a -tracing session _rotation_ and a _trace chunk_. +See man:lttng-concepts(7) to learn more about the tracing session +rotation and trace chunk concepts. With the option:--timer='PERIODUS' option, the `enable-rotation` command sets a rotation schedule so that LTTng performs an automatic rotation at @@ -43,7 +42,7 @@ 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 man:lttng-enable-channel(1)). This means that: +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 @@ -58,26 +57,26 @@ relies on the precision of the platform implementation of POSIX timers. You may combine the option:--timer and option:--size options. -The naming convention of a trace chunk archive which an automatic -rotation operation creates is the same as with the immediate rotation -command, man:lttng-rotate(1). +See the man:lttng-concepts(7) to learn how LTTng names a trace chunk +archive directory. Unset a tracing session rotation schedule with the man:lttng-disable-rotation(1) command. [IMPORTANT] ==== -The `enable-rotation` command only works when: +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)). * No channel was created with a configured trace file count or size limit (see the nloption:--tracefile-size and - nloption:--tracefile-count options of man:lttng-enable-channel(1)). + nloption:--tracefile-count options of the man:lttng-enable-channel(1) + command). For a given tracing session, LTTng only performs an automatic rotation -when no other rotation is currently happening. +when it's not currently performing a rotation. ==== @@ -95,8 +94,8 @@ The `k`{nbsp}(KiB), `M`{nbsp}(MiB), and `G`{nbsp}(GiB) suffixes are supported. option:--timer='PERIODUS':: - Set a rotation schedule so that LTTng performs an automatic rotation at - least every 'PERIODUS' microseconds. + Set a rotation schedule so that LTTng performs an automatic rotation + approximately every 'PERIODUS' microseconds. + The `ms`{nbsp}(milliseconds), `s`{nbsp}(seconds), `m`{nbsp}(minutes), and `h`{nbsp}(hours) suffixes are supported. @@ -118,6 +117,7 @@ include::common-cmd-footer.txt[] SEE ALSO -------- man:lttng(1), +man:lttng-concepts(7), man:lttng-create(1), man:lttng-disable-rotation(1), man:lttng-rotate(1) diff --git a/doc/man/lttng-event-rule.7.txt b/doc/man/lttng-event-rule.7.txt index b28d23aae..3fad65c86 100644 --- a/doc/man/lttng-event-rule.7.txt +++ b/doc/man/lttng-event-rule.7.txt @@ -1,6 +1,6 @@ lttng-event-rule(7) =================== -:revdate: 19 April 2021 +:revdate: 3 May 2021 NAME @@ -14,26 +14,26 @@ Specify an event rule to match Linux kernel tracepoint or system call events: [verse] -option:--domain=kernel option:--type=(tracepoint | syscall[:entry|:exit|:entry+exit])] +option:--domain=**kernel** option:--type=(**tracepoint** | **syscall**[**:entry**|**:exit**|**pass:[:entry+exit]**])] pass:[[]option:--name='NAME'] [option:--filter='EXPR'] Specify an event rule to match Linux kernel kprobe or user space probe events: [verse] -option:--domain=kernel option:--type=(kprobe | uprobe) option:--location='LOC' +option:--domain=**kernel** option:--type=(**kprobe** | **uprobe**) option:--location='LOC' pass:[[]option:--event-name='EVENTNAME'] [option:--filter='EXPR'] Specify an event rule to match user space tracepoint events: [verse] -option:--domain=user [option:--type=tracepoint] [option:--name='NAME'] [option:--exclude-name='XNAME']... +option:--domain=**user** [option:--type=**tracepoint**] [option:--name='NAME'] [option:--exclude-name='XNAME']... pass:[[]option:--log-level=('LOGLEVEL' | 'LOGLEVEL'.. | ..)] [option:--filter='EXPR'] Specify an event rule to match Java/Python logging events: [verse] -option:--domain=(jul | log4j | python) [option:--type=logging] [option:--name='NAME'] +option:--domain=(**jul** | **log4j** | **python**) [option:--type=**logging**] [option:--name='NAME'] pass:[[]option:--log-level=('LOGLEVEL' | 'LOGLEVEL'.. | ..)] [option:--filter='EXPR'] @@ -46,6 +46,9 @@ As of LTTng{nbsp}{lttng_version}, the command-line options documented here only apply to the `event-rule-matches` trigger condition specifier (see man:lttng-add-trigger(1)). +See man:lttng-concepts(7) to learn more about instrumentation points, +events, and event rules. + [NOTE] ==== This manual page only describes the common event rule options. The @@ -58,57 +61,8 @@ condition. ==== -Core concepts -~~~~~~~~~~~~~ -An _instrumentation point_ is a point, within a piece of software, -which, when executed, creates an LTTng _event_. - -LTTng offers various types of instrumentation; see the -<> section -below to learn about them. - -An _event rule_ is a set of conditions to match a set of events. - -When LTTng creates an event{nbsp}__E__, a event rule{nbsp}__ER__ is said -to __match__{nbsp}__E__ when{nbsp}__E__ satisfies *all* the conditions -of{nbsp}__ER__. This concept is similar to a regular expression which -matches a set of strings. - -When an event rule matches an event, LTTng _emits_ the event, -therefore attempting to execute one or more actions. - -[NOTE] -==== -The event creation and emission processes are documentation concepts to -help understand the journey from an instrumentation point to the -execution of actions. - -The actual creation of an event can be costly because LTTng needs to -evalute the arguments of the instrumentation point. - -In practice, LTTng implements various optimizations for the Linux kernel -and user space tracing domains (option:--domain=++kernel++ and -option:--domain=++user++ options) to avoid actually creating an event -when the tracer knows, thanks to properties which are independent from -the event payload and current context, that it would never emit such an -event. Those properties are: - -* The instrumentation point type (see the - <> section below). -* The instrumentation point name (or event name) - (see the <> section below). -* The instrumentation point log level (see the - <> - section below). - -In other words: if, for a given instrumentation point{nbsp}__IP__, the -LTTng tracer knows that it would never emit an event, -executing{nbsp}__IP__ represents a simple boolean variable check. -==== - - -Event rule overview -~~~~~~~~~~~~~~~~~~~ +Overview of event rule condtions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ For LTTng to emit an event{nbsp}__E__,{nbsp}__E__ must satisfy *all* the conditions of an event rule, that is: @@ -802,7 +756,12 @@ option:-f 'EXPR', option:--filter='EXPR':: event payload and current context fields, is _true_. +include::common-footer.txt[] + + SEE ALSO -------- man:lttng(1), -man:lttng-add-trigger(1) +man:lttng-add-trigger(1), +man:lttng-concepts(7), +man:lttng-list(1) diff --git a/doc/man/lttng-help.1.txt b/doc/man/lttng-help.1.txt index 1de72c55b..3b1d7b50e 100644 --- a/doc/man/lttng-help.1.txt +++ b/doc/man/lttng-help.1.txt @@ -27,7 +27,7 @@ Without the 'COMMAND' argument:: The `help` command is equivalent to: [verse] -*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] ['COMMAND'] --help +*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] ['COMMAND'] nloption:--help The `help` command attempts to launch `/usr/bin/man` to view this the manual page of the command. Override the manual pager path with the diff --git a/doc/man/lttng-list-triggers.1.txt b/doc/man/lttng-list-triggers.1.txt index f6308141d..83919a2c6 100644 --- a/doc/man/lttng-list-triggers.1.txt +++ b/doc/man/lttng-list-triggers.1.txt @@ -1,6 +1,6 @@ lttng-list-triggers(1) ====================== -:revdate: 3 March 2021 +:revdate: 3 May 2021 NAME @@ -16,10 +16,11 @@ SYNOPSIS DESCRIPTION ----------- -The `lttng list-triggers` command lists the available LTTng triggers -of your Unix user and their properties. +The `lttng list-triggers` command lists the available LTTng triggers of +your Unix user, or of all users if your Unix user is `root`, and their +properties. -See man:lttng-add-trigger(1) to learn more about triggers. +See man:lttng-concepts(7) to learn more about triggers. OPTIONS @@ -31,6 +32,7 @@ include::common-cmd-footer.txt[] SEE ALSO -------- +man:lttng(1), man:lttng-add-trigger(1), -man:lttng-remove-trigger(1), -man:lttng(1) +man:lttng-concepts(7), +man:lttng-remove-trigger(1) diff --git a/doc/man/lttng-list.1.txt b/doc/man/lttng-list.1.txt index af3b13f71..319ec5052 100644 --- a/doc/man/lttng-list.1.txt +++ b/doc/man/lttng-list.1.txt @@ -1,103 +1,156 @@ lttng-list(1) ============= -:revdate: 28 November 2016 +:revdate: 3 May 2021 NAME ---- -lttng-list - List LTTng tracing sessions, domains, channels, and events +lttng-list - List LTTng tracing sessions and instrumentation points SYNOPSIS -------- -List existing tracing sessions: +List the tracing sessions: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *list* -List available event sources: +List the tracing domains with at least one channel of a tracing session: [verse] -*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *list* [option:--fields] - [option:--kernel [option:--syscall]] [option:--userspace] [option:--jul] [option:--log4j] [option:--python] +*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *list* option:--domain 'SESSION' -List tracing session's domains: +List the channels and recording event rules of a tracing session: [verse] -*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *list* option:--domain 'SESSION' +*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *list* [option:--channel='CHANNEL'] 'SESSION' + [option:--kernel] [option:--userspace] [option:--jul] [option:--log4j] [option:--python] -List tracing session's channels and recording event rules: +List the available LTTng tracepoints, Linux system calls, and/or +Java/Python loggers: [verse] -*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *list* [option:--channel='CHANNEL'] 'SESSION' +*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *list* [option:--fields] + [option:--kernel [option:--syscall]] [option:--userspace] [option:--jul] [option:--log4j] [option:--python] DESCRIPTION ----------- -The `lttng list` command lists tracing sessions, tracing domains, -channels, and events. - -Without arguments, `lttng list` lists the existing tracing sessions -and shows if they are active or not. - -With one or more of the option:--kernel, option:--userspace, -option:--jul, option:--log4j, and option:--python domain options, the -command lists the available event sources of the selected domain on the -system. The JUL, log4j, and Python domains list the names of their -available _loggers_. The option:--syscall option can be used alongside -the option:--kernel option to get a list of traceable Linux system -calls. The option:--fields option can be used to show the fields of the -listed event sources. - -Providing a tracing session name 'SESSION' targets a specific tracing -session. If the option:--domain option is used, domains containing at -least one channel in the selected tracing session are listed. Otherwise, -all the domains, channels, and recording event rules of the selected -tracing session are listed along with its details (trace path, for -example), except when the option:--channel option is used to isolate a -specific channel by name. +The `lttng list` command lists: + +Without arguments:: + The tracing 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 +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 + 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'. + + Without the option:--channel option:::: + The channels of the tracing session named 'SESSION' and + their recording event rules. ++ +Use the dedicated tracing domain options (option:--kernel, +option:--userspace, option:--jul, option:--log4j, and option:--python) +to only show specific channels. + +Without the 'SESSION' argument and with at least one dedicated tracing domain option:: ++ +-- +With the option:--kernel option:: + Without the option:--syscall option::: + The available LTTng kernel tracepoints. + With the option:--syscall option::: + The available, instrumented Linux system calls. +With the option:--userspace option:: + The available LTTng user space tracepoints. +With the option:--jul, option:--log4j, and/or option:--python options:: + The available `java.util.logging`, Apache log4j, and/or Python + logger names. +-- ++ +Also list the available instrumentation point fields with the +option:--fields option. + +See man:lttng-concept(7) to learn more about tracing sessions, tracing +domains, channels, recording event rules, and instrumentation points. + +List the channels and recording event rules of the current tracing +session (see man:lttng-concept(7) to learn more) with the +man:lttng-status(1) command. include::common-cmd-options-head.txt[] -Domain -~~~~~~ +Tracing domain +~~~~~~~~~~~~~~ option:-j, option:--jul:: - List event sources in the `java.util.logging` (JUL) domain. + Without the 'SESSION' argument::: + List the `java.util.logging` logger names. + With the 'SESSION' argument::: + Only list the `java.util.logging` channels and their recording + event rules. option:-k, option:--kernel:: - List event sources in the Linux kernel domain. + Without the 'SESSION' argument::: + List the LTTng kernel instrumentation points. + With the 'SESSION' argument::: + Only list the Linux kernel channels and their recording event + rules. option:-l, option:--log4j:: - List event sources in the Apache log4j domain. + Without the 'SESSION' argument::: + List the Apache log4j logger names. + With the 'SESSION' argument::: + Only list the Apache log4j channels and their recording event + rules. option:-p, option:--python:: - List event sources in the Python domain. + Without the 'SESSION' argument::: + List the Python logger names. + With the 'SESSION' argument::: + Only list the Python channels and their recording event rules. option:-u, option:--userspace:: - List event sources in the user space domain. + Without the 'SESSION' argument::: + List the LTTng user space tracepoints. + With the 'SESSION' argument::: + Only list the user space channels and their recording event + rules. -Target -~~~~~~ +Filtering +~~~~~~~~~ option:-c 'CHANNEL', option:--channel='CHANNEL':: - Only list the details of the channel named 'CHANNEL'. - + Only list the properties and recording event rules of the channel + named 'CHANNEL'. ++ +Only available with the 'SESSION' argument. -Listing -~~~~~~~ option:-d, option:--domain:: - Show the domains of the target tracing session in which at least one - channel exists. + Show the tracing domains with at least one channel of the tracing + session named 'SESSION'. option:-f, option:--fields:: - When listing the event sources with one of the domain options, - also show their fields. + When listing instrumentation points, also show their fields if + they're available. option:--syscall:: - When listing the event sources of the Linux kernel domain, list - the traceable system calls instead of the kernel tracepoints. + When listing LTTng kernel instrumentation points, only list Linux + system calls. include::common-cmd-help-options.txt[] @@ -108,4 +161,5 @@ include::common-cmd-footer.txt[] SEE ALSO -------- -man:lttng(1) +man:lttng(1), +man:lttng-concepts(7) diff --git a/doc/man/lttng-load.1.txt b/doc/man/lttng-load.1.txt index 253b86d3c..f5cc3e203 100644 --- a/doc/man/lttng-load.1.txt +++ b/doc/man/lttng-load.1.txt @@ -1,6 +1,6 @@ lttng-load(1) ============= -:revdate: 28 November 2016 +:revdate: 30 April 2021 NAME @@ -12,7 +12,7 @@ SYNOPSIS -------- [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *load* [option:--force] [option:--input-path='PATH'] - [option:--override-url='URL'] ['SESSION' [option:--override-name='NAME']] + [option:--override-url='URL'] [option:--all | 'SESSION' [option:--override-name='NAME']] DESCRIPTION @@ -20,54 +20,63 @@ DESCRIPTION The `lttng load` command loads the configurations of one or more tracing sessions from files. -The `lttng load` command is used in conjunction with the -man:lttng-save(1) command to save and restore the complete -configurations of tracing sessions. This includes the enabled channels -and recording event rules, the context added to channels, the tracing +See man:lttng-concepts(7) to learn more about tracing 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 activity, and more. -Once one or more tracing session configurations are loaded, they appear +Once LTTng loads one or more tracing session configurations, they appear exactly as they were saved from the user's point of view. -The following directories are searched, non-recursively, in this order -for configuration files: +LTTng searches the following directories, non-recursively, in this order +for tracing session configuration files: . `$LTTNG_HOME/.lttng/sessions` (`$LTTNG_HOME` defaults to `$HOME`) . +{system_sessions_dir}+ -The input path can be overridden with the option:--input-path option. -When this option is specified, the default directories are :not: -searched for configuration files. When it's not specified, _both_ -default directories are searched for configuration files. +Override the input path with the option:--input-path='PATH' option. With +this option, LTTng does :not: search the default directories above. +'PATH' can be the path of one of: + +A directory:: + With the 'SESSION' argument::: + LTTng searches for the tracing session configuration named + 'SESSION' in all the files of the directory 'PATH' and loads it + if found. -If the input path is a *directory*, then: + 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'. -* If 'SESSION' is specified, the tracing session configuration named - 'SESSION' is searched for in all the files of this directory and - loaded if found. -* If 'SESSION' is not specified, the option:--all option is implicit: - all the tracing session configurations found in all the files in this - directory are loaded. +A file:: + With the 'SESSION' argument::: + LTTng searches for the tracing session configuration named + 'SESSION' in the file 'PATH' and loads it if found. -If the input path is a *file*, then: + Without the 'SESSION' argument::: + The option:--all option is implicit: LTTng loads all the tracing + session configurations found in the file 'PATH'. -* If 'SESSION' is specified, the tracing session configuration named - 'SESSION' is searched for in this file and loaded if found. -* If 'SESSION' is not specified, the option:--all option is implicit: - all the tracing session configurations found in this file are loaded. +Override the output URL of the loaded tracing session configurations +with the option:--override-url option. -Aspects of the loaded configurations can be overridden at load time -using the option:--override-url and option:--override-name options. +With the 'SESSION' argument, override the name of the loaded tracing +session configuration with the option:--override-name option. -By default, existing tracing sessions are not overwritten when loading: -the command fails. The option:--force option can be used to allow this. +By default, the `load` command does :not: overwrite existing tracing +sessions: the command fails. Allow the `load` command to overwrite +existing tracing sessions with the option:--force option. include::common-cmd-options-head.txt[] option:-a, option:--all:: - Load all tracing session configurations (default). + Load all the tracing session configurations (default). option:-f, option:--force:: Overwrite existing tracing sessions when loading. @@ -80,12 +89,9 @@ option:-i 'PATH', option:--input-path='PATH':: option:--override-name='NAME':: Override the name of the loaded tracing session configuration, 'SESSION', with 'NAME'. -+ -You must specify a tracing session name to load ('SESSION') and :not: -use the option:--all option when using this option. option:--override-url='URL':: - Override the URL of the loaded tracing session configurations + Override the output URL of the loaded tracing session configurations with 'URL'. + This is the equivalent of the nloption:--set-url option of @@ -102,5 +108,6 @@ include::common-cmd-footer.txt[] SEE ALSO -------- -man:lttng-save(1), -man:lttng(1) +man:lttng(1), +man:lttng-concepts(7), +man:lttng-save(1) diff --git a/doc/man/lttng-metadata.1.txt b/doc/man/lttng-metadata.1.txt index 5d9864be7..220225b31 100644 --- a/doc/man/lttng-metadata.1.txt +++ b/doc/man/lttng-metadata.1.txt @@ -1,22 +1,22 @@ lttng-metadata(1) ================= -:revdate: 28 November 2016 +:revdate: 30 April 2021 NAME ---- -lttng-metadata - Manage an LTTng tracing session's metadata generation +lttng-metadata - Manage the metadata generation of an LTTng tracing session SYNOPSIS -------- [verse] -*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *metadata regenerate* [option:--session='SESSION'] +*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *metadata* *regenerate* [option:--session='SESSION'] DESCRIPTION ----------- -WARNING: This command is **deprecated**; it has been replaced by +WARNING: This command is **deprecated**; it's been replaced with `lttng regenerate metadata` (see man:lttng-regenerate(1)). @@ -24,27 +24,20 @@ include::common-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. + 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 + session). include::common-cmd-help-options.txt[] -LIMITATIONS ------------ -The `lttng metadata regenerate` command can only be used on kernel and -user space tracing sessions (using per-user buffering), in non-live -mode. - -See man:lttng-enable-channel(1) for more information about -buffering schemes and man:lttng-create(1) for more information -about the different tracing session modes. - - include::common-cmd-footer.txt[] SEE ALSO -------- -man:lttng(1) +man:lttng(1), +man:lttng-concepts(7), +man:lttng-regenerate(1) diff --git a/doc/man/lttng-regenerate.1.txt b/doc/man/lttng-regenerate.1.txt index a22055188..d3f645fc6 100644 --- a/doc/man/lttng-regenerate.1.txt +++ b/doc/man/lttng-regenerate.1.txt @@ -1,56 +1,87 @@ lttng-regenerate(1) =================== -:revdate: 18 January 2018 +:revdate: 30 April 2021 NAME ---- -lttng-regenerate - Manage an LTTng tracing session's data regeneration +lttng-regenerate - Regenerate specific data of an LTTng tracing session SYNOPSIS -------- -Regenerate the metadata of a session: +Regenerate the metadata of a tracing session: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *regenerate metadata* [option:--session='SESSION'] -Regenerate the state dump of a session: +Regenerate the state dump event records of a tracing session: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *regenerate statedump* [option:--session='SESSION'] + DESCRIPTION ----------- -The `lttng regenerate` command regenerates specific data of a tracing session. - -As of this version, the `metadata` and `statedump` actions are -available. +The `lttng regenerate` command regenerates specific data of: +With the option:--session='SESSION' option:: + The tracing session named 'SESSION'. -Regenerating a tracing session's metadata -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The `lttng regenerate metadata` action can be used to resample the offset -between the system's monotonic clock and the wall-clock time. +Without the option:--session option:: + The current tracing session (see man:lttng-concepts(7) to learn more + about the current tracing session). -This action is meant to be used to resample the wall-clock time following a -major link:https://en.wikipedia.org/wiki/Network_Time_Protocol[NTP] correction. -As such, a system booting with an incorrect wall time can be traced before its -wall time is NTP-corrected. Regenerating the tracing session's metadata ensures -that trace viewers can accurately determine the events time relative to Unix -Epoch. +See man:lttng-concepts(7) to learn more about tracing sessions. -If you use man:lttng-rotate(1) or man:lttng-enable-rotation(1) to make -tracing session rotations, this action regenerates the current and -next trace chunks's metadata files. +As of this version, the `metadata` and `statedump` targets are +available. -Regenerating a tracing session's state dump -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The `lttng regenerate statedump` action can be used to collect up-to-date state -dump information during the tracing session. This is particularly useful in -snapshot (see man:lttng-snapshot(1)) or trace file rotation (see -man:lttng-enable-channel(1)) modes where the state dump information may be +Regenerate the metadata of a tracing 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] +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 +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 +metadata stream files of the current and next trace chunks. + +[IMPORTANT] +==== +You can only use the `metadata` target when the selected +tracing session: + +* Is not in live mode (nloption:--live option of + man:lttng-create(1)). + +* If it has user space channels, they're configured to use a + per-user buffering scheme (nloption:--buffers-uid option of + man:lttng-enable-channel(1)). ++ +See man:lttng-concepts(7) to learn more about channels. +==== + + +Regenerate the state dump event records of a tracing 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 +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 lost. @@ -58,27 +89,17 @@ include::common-cmd-options-head.txt[] option:-s 'SESSION', option:--session='SESSION':: - Regenerate the data of the tracing session named 'SESSION' + Regenerate specific data of the tracing session named 'SESSION' instead of the current tracing session. include::common-cmd-help-options.txt[] -LIMITATIONS ------------ -The `lttng regenerate metadata` command can only be used on kernel and -user space tracing sessions (using per-user buffering), in non-live -mode. - -See man:lttng-enable-channel(1) for more information about -buffering schemes and man:lttng-create(1) for more information -about the different tracing session modes. - - include::common-cmd-footer.txt[] SEE ALSO -------- -man:lttng(1) +man:lttng(1), +man:lttng-concepts(7) diff --git a/doc/man/lttng-relayd.8.txt b/doc/man/lttng-relayd.8.txt index 5171b93d9..694eb4995 100644 --- a/doc/man/lttng-relayd.8.txt +++ b/doc/man/lttng-relayd.8.txt @@ -1,11 +1,13 @@ lttng-relayd(8) =============== -:revdate: 2 April 2020 +:revdate: 30 April 2021 +:daemon-bin-name: lttng-relayd +:daemon-ini-section: relayd NAME ---- -lttng-relayd - LTTng 2 relay daemon +lttng-relayd - LTTng relay daemon SYNOPSIS @@ -13,39 +15,52 @@ SYNOPSIS [verse] *lttng-relayd* [option:--background | option:--daemonize] [option:--config='PATH'] [option:--control-port='URL'] [option:--data-port='URL'] [option:--fd-pool-size='COUNT'] - [option:--live-port='URL'] [option:--output='PATH'] - [option:-v | option:-vv | option:-vvv] [option:--working-directory='PATH'] - [option:--group-output-by-session] [option:--disallow-clear] + [option:--live-port='URL'] [option:--output='DIR'] [option:--group='GROUP'] + [option:--verbose]... [option:--working-directory='DIR'] + [option:--group-output-by-host | option:--group-output-by-session] [option:--disallow-clear] DESCRIPTION ----------- -The https://lttng.org/[_Linux Trace Toolkit: next generation_] is an open -source software package used for correlated tracing of the Linux kernel, -user applications, and user libraries. +include::common-intro.txt[] -LTTng consists of Linux kernel modules (for Linux kernel tracing) and -dynamically loaded libraries (for user application and library tracing). +An LTTng relay daemon, `lttng-relayd`, is a program which receives trace +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. -The _LTTng relay daemon_ is responsible for receiving trace data from -possibly remote LTTng session/consumer daemons and for writing it to -the local file system. The relay daemon also accepts _LTTng live_ -connections from compatible viewers; this is the official approach to -viewing LTTng events as they are emitted. +By default, a relay daemon listens on all network interfaces to receive +trace data, but only on `localhost` for LTTng live connections. Override +the listening URLs with the option:--control-port, option:--data-port, +and option:--live-port options (see the <> +section below). For example, use the +option:--live-port=+tcp://0.0.0.0:{default_network_viewer_port}+ option +to make a relay daemon listen to LTTng live connections on all network +interfaces. -The relay daemon listens by default on all network interfaces to gather -trace data, but only on localhost for LTTng live connections. +Once LTTng has completely sent a trace to a relay daemon{nbsp}__RD__, +any LTTng trace reader can read the trace located on the local file +system of{nbsp}__RD__. -The relay daemon does not require any particular permissions, as long as -it can write to the output directory and listen on the configured ports. -If a user is within a secured network and/or has proper firewall -settings, `lttng-relayd` can listen to LTTng live connections from _all_ -network interfaces by specifying -+--live-port=tcp://0.0.0.0:{default_network_viewer_port}+. +By default, `lttng-relayd` doesn't start as a daemon. Make it a daemon +with the option:--daemonize or option:--background option. With those +options, `lttng-relayd` ensures the daemon is listening to incoming +connections before it exits. -Once a trace has been streamed completely, the trace can be processed by -any tool that can process an LTTng trace located on the local -file system. + +include::common-daemon-cfg.txt[] + +INI configuration file example: + +[source,ini] +---- +[relayd] +daemonize=yes +live-port=tcp://0.0.0.0:4567 +disallow-clear=yes +---- [[output-directory]] @@ -54,20 +69,21 @@ Output directory The relay daemon uses different output path patterns depending on: * Its configuration. -* The connected peer's tracing session configuration. -* The connected peer's LTTng session daemon (see man:lttng-sessiond(8)) - version. ++ +See the <> section above. + +* The tracing session configuration of the connected peer. +* The LTTng session daemon (see man:lttng-sessiond(8)) version + of the connected peer. Consider the following variables: 'BASE':: - Base output directory: `$LTTNG_HOME/lttng-traces` or the - argument of the option:--output option. -+ -NOTE: `$LTTNG_HOME` defaults to `$HOME`. + Base output directory: `$LTTNG_HOME/lttng-traces` (`$LTTNG_HOME` + defaults to `$HOME`) or the argument of the option:--output option. 'HOSTNAME':: - Peer's hostname. + Hostname of the connected peer. 'SESSION':: Tracing session name. @@ -75,68 +91,61 @@ NOTE: `$LTTNG_HOME` defaults to `$HOME`. 'DATETIME':: Unique tracing session date/time. -'TRACEPATH':: - Custom trace path ('TRACEPATH' part of the man:lttng-create(1) - command's nloption:--set-url option's argument, if any). +'TRACEDIR':: + Custom trace directory path ('TRACEDIR' part of the argument of the + nloption:--set-url option of the man:lttng-create(1) command, if + any). + +'SESSIONDV':: + The version of the LTTng session daemon of the connected peer. The relay daemon output path patterns are: -Hostname grouping (without option:--group-output-by-session):: - Without a custom trace path::: +With the option:--group-output-by-host option (hostname grouping):: + Without a custom trace directory::: + --- [verse] 'BASE'/'HOSTNAME'/'SESSION'-'DATETIME' --- -With a custom trace path::: +With a custom trace directory::: + --- [verse] -'BASE'/'HOSTNAME'/'TRACEPATH' --- +'BASE'/'HOSTNAME'/'TRACEDIR' -Tracing session grouping (with option:--group-output-by-session):: - Without a custom trace path::: - The peer's LTTng session daemon version is at least 2.4:::: +With the option:--group-output-by-session option (tracing session grouping):: + Without a custom trace directory::: + 'SESSIONDV' is at least{nbsp}2.4:::: + --- [verse] 'BASE'/'SESSION'/'HOSTNAME'-'DATETIME' --- Otherwise:::: Defaults to the hostname grouping pattern: + --- [verse] 'BASE'/'HOSTNAME'/'SESSION'-'DATETIME' --- -With a custom trace path::: - The peer's LTTng session daemon version is at least 2.4:::: +With a custom trace directory::: + 'SESSIONDV' is at least 2.4:::: + --- [verse] -'BASE'/'SESSION'/'HOSTNAME'-'DATETIME'/'TRACEPATH' --- +'BASE'/'SESSION'/'HOSTNAME'-'DATETIME'/'TRACEDIR' Otherwise:::: Defaults to the hostname grouping pattern: + --- [verse] -'BASE'/'HOSTNAME'/'TRACEPATH' --- +'BASE'/'HOSTNAME'/'TRACEDIR' [[url-format]] URL format ~~~~~~~~~~ -The option:--control-port, option:--data-port, and option:--live-port -options specify URLs. +The argument of the option:--control-port='URL', +option:--data-port='URL', and option:--live-port='URL' options is an +URL. -The format of those URLs is: +The format of 'URL' is: [verse] tcp://('HOST' | 'IPADDR'):__PORT__ @@ -144,30 +153,43 @@ tcp://('HOST' | 'IPADDR'):__PORT__ with: ('HOST' | 'IPADDR'):: - Binding hostname or IP address (IPv6 address *must* be enclosed in - brackets (`[` and `]`); see - https://www.ietf.org/rfc/rfc2732.txt[RFC 2732]). + Binding hostname or IP address. ++ +IPv6 address must be enclosed in square brackets (`[` and{nbsp}`]`); +see https://www.ietf.org/rfc/rfc2732.txt[RFC{nbsp}2732]. 'PORT':: TCP port. +[[options]] OPTIONS ------- -Daemon -~~~~~~ +General daemon configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ option:-b, option:--background:: - Start as Unix daemon, but keep file descriptors (console) open. - Use the option:--daemonize option instead to close the file - descriptors. + Start as a Unix daemon, but keep file descriptors (console) open. ++ +With this option, `lttng-relayd` ensures the daemon is listening +to incoming connections before it exits. ++ +Use the option:--daemonize option instead to close the file descriptors. option:-f 'PATH', option:--config='PATH':: - Load relay daemon configuration from path 'PATH'. + Configure the daemon using the INI configuration file 'PATH' in + addition to the default configuration files and the command-line + options. ++ +See the <> section above. option:-d, option:--daemonize:: - Start as Unix daemon, and close file descriptors (console). Use the - option:--background option instead to keep the file descriptors - open. + Start as a Unix daemon and close file descriptors (console). ++ +With this option, `lttng-relayd` ensures the daemon is listening +to incoming connections before it exits. ++ +Use the option:--background option instead to keep the file descriptors +open. option:-x, option:--disallow-clear:: Disallow clearing operations (see man:lttng-clear(1)). @@ -175,161 +197,183 @@ option:-x, option:--disallow-clear:: See also the `LTTNG_RELAYD_DISALLOW_CLEAR` environment variable. option:--fd-pool-size='SIZE':: - Set the size of the file descriptor pool to 'SIZE'. + Set the size of the file descriptor pool to 'SIZE' file descriptors. + -'SIZE' is the maximum number of file descriptors that may be kept opened -simultaneously by the relay daemon. +'SIZE' is the maximum number of file descriptors that the relay daemon +may keep open simultaneously. + Default: the soft `RLIMIT_NOFILE` resource limit of the process (see man:getrlimit(2)). option:-g 'GROUP', option:--group='GROUP':: - Use 'GROUP' as Unix tracing group (default: `tracing`). + Set the Unix tracing group to 'GROUP' instead of `tracing`. ++ +This option is only meaningful when the `root` Unix user starts +`lttng-relayd`. ++ +Members of the Unix tracing group may connect to the health check socket +of the relay daemon. ++ +See also the `LTTNG_RELAYD_HEALTH` environment variable. -option:-w 'PATH', option:--working-directory='PATH':: +option:-w 'DIR', option:--working-directory='DIR':: Set the working directory of the processes the relay daemon creates - to 'PATH'. + to 'DIR'. + See also the `LTTNG_RELAYD_WORKING_DIRECTORY` environment variable. option:-v, option:--verbose:: Increase verbosity. + -Three levels of verbosity are available, which are triggered by -appending additional `v` letters to the option -(that is, `-vv` and `-vvv`). +Specify this option up to three times to get more levels of verbosity. Output ~~~~~~ -See the <> section above for more -information. +See the <> section above to learn +more. option:-p, option:--group-output-by-host:: - Group the written trace directories by hostname (default). + Group the written trace directories by hostname. ++ +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. -option:-o 'PATH', option:--output='PATH':: +option:-o 'DIR', option:--output='DIR':: Set the base output directory of the written trace directories to - 'PATH'. + 'DIR'. Ports ~~~~~ -See the <> section above for more information -about the syntax of the following 'URL' argument. +See the <> section above to learn more about the +syntax of the 'URL' argument of the following options. option:-C 'URL', option:--control-port='URL':: - Listen to control data on URL 'URL' (default: - +tcp://{default_network_control_bind_address}:{default_network_control_port}+). + Listen to control data on URL 'URL'. ++ +Default: ++tcp://{default_network_control_bind_address}:{default_network_control_port}+. option:-D 'URL', option:--data-port='URL':: - Listen to trace data on URL 'URL' (default: - +tcp://{default_network_data_bind_address}:{default_network_data_port}+). + Listen to trace data on URL 'URL'. ++ +Default: ++tcp://{default_network_data_bind_address}:{default_network_data_port}+. option:-L 'URL', option:--live-port='URL':: - Listen to LTTng live connections on URL 'URL' - (default: - +tcp://{default_network_viewer_bind_address}:{default_network_viewer_port}+). + Listen to LTTng live connections on URL 'URL'. ++ +Default: ++tcp://{default_network_viewer_bind_address}:{default_network_viewer_port}+. Program information ~~~~~~~~~~~~~~~~~~~ -option:-h, option:--help:: - Show help. +include::common-help-option.txt[] option:-V, option:--version:: - Show version. + Show version and quit. ENVIRONMENT VARIABLES --------------------- `LTTNG_ABORT_ON_ERROR`:: - Set to 1 to abort the process after the first error is encountered. + Set to `1` to abort the process after the first error is + encountered. `LTTNG_NETWORK_SOCKET_TIMEOUT`:: - Socket connection, receive and send timeout (milliseconds). A value - of 0 or -1 uses the timeout of the operating system (default). + Socket connection, receive, and send timeout (milliseconds). ++ +Set to `0` or `-1` to set an infinite timeout (default). `LTTNG_RELAYD_DISALLOW_CLEAR`:: - Set to 1 to disallow clearing operations (see man:lttng-clear(1)). + Set to `1` to disallow clearing operations (see man:lttng-clear(1)). + -The option:--disallow-clear option overrides this variable. +The option:--disallow-clear option overrides this environment variable. `LTTNG_RELAYD_HEALTH`:: - Path to relay daemon health's socket. + Path to the health check socket of the relay daemon. `LTTNG_RELAYD_TCP_KEEP_ALIVE`:: - Set to 1 to enable TCP keep-alive. + Set to `1` to enable TCP keep-alive. + The TCP keep-alive mechanism allows the detection of dead peers -(man:lttng-sessiond(8)) in cases of unclean termination -(for example, a hard reset) of a peer. +(man:lttng-sessiond(8)) in cases of unclean termination (for example, a +hard reset) of a peer. + Supported on Linux and Solaris only. The default behaviour of the TCP keep-alive mechanism is OS-specific. + -Search for `tcp_keepalive` in man:tcp(7) for more information. +Search for `tcp_keepalive` in man:tcp(7) to learn more. `LTTNG_RELAYD_TCP_KEEP_ALIVE_ABORT_THRESHOLD`:: - The time threshold in seconds to abort a TCP connection after the keep-alive - probing mechanism has failed. + The time threshold (seconds) to abort a TCP connection after the + keep-alive probing mechanism has failed. + -Set to 0 or -1 to use the value chosen by the operating system (default). +Set to `0` or `-1` to use the value chosen by the operating system +(default). + Supported on Solaris 11 only. + -Search for `tcp_keepalive_abort_threshold` in man:tcp(7) for more information. +Search for `tcp_keepalive_abort_threshold` in man:tcp(7) to learn more. `LTTNG_RELAYD_TCP_KEEP_ALIVE_IDLE_TIME`:: Number of seconds a connection needs to be idle before TCP begins sending out keep-alive probes. + -Set to 0 or -1 to use the value chosen by the operating system (default). +Set to `0` or `-1` to use the value chosen by the operating system +(default). + Supported on Linux and Solaris 11 only. + -On Solaris{nbsp}11, the accepted values are -1, 0, and 10 to 864000. +On Solaris{nbsp}11, the accepted values are `-1`, `0`, and `10` to +`864000`. + Search for `tcp_keepalive_time` and `tcp_keepalive_interval` -in man:tcp(7) on Solaris 11 for more information. +in man:tcp(7) on Solaris{nbsp}11 to learn more. `LTTNG_RELAYD_TCP_KEEP_ALIVE_MAX_PROBE_COUNT`:: Maximum number of TCP keep-alive probes to send before giving up and killing the connection if no response is obtained from the other end. + -Set to 0 or -1 to use the value chosen by the operating system (default). +Set to `0` or `-1` to use the value chosen by the operating system +(default). + Supported on Linux only. + -Search for `tcp_keepalive_probes` in man:tcp(7) for more information. +Search for `tcp_keepalive_probes` in man:tcp(7) to learn more. `LTTNG_RELAYD_TCP_KEEP_ALIVE_PROBE_INTERVAL`:: Number of seconds between TCP keep-alive probes. + -Set to 0 or -1 to use the value chosen by the operating system (default). +Set to `0` or `-1` to use the value chosen by the operating system +(default). + Supported on Linux only. + -Search for `tcp_keepalive_intvl` in man:tcp(7) for more information. +Search for `tcp_keepalive_intvl` in man:tcp(7) to learn more. `LTTNG_RELAYD_WORKING_DIRECTORY`:: Working directory of the processes the relay daemon creates. + -The option:--working-directory option overrides this variable. +The option:--working-directory option overrides this environment +variable. FILES ----- `$LTTNG_HOME/.lttng`:: - User LTTng runtime and configuration directory. + Unix user's LTTng runtime and configuration directory. `$LTTNG_HOME/lttng-traces`:: - Default base output directory of LTTng traces. This can be - overridden with the option:--output option. + Default base output directory of LTTng traces. ++ +Override this path with the option:--output option. NOTE: `$LTTNG_HOME` defaults to `$HOME`. @@ -346,19 +390,6 @@ EXIT STATUS Fatal error -LIMITATIONS ------------ -As of this version, only the TCP protocol is supported for both control -and data ports. In future versions, TCP will remain the sole available -protocol for control data since those communications are low-volume and -need absolute reliability; trace data could be carried over UDP. - -For an unprivileged user running `lttng-relayd`, the maximum number of -file descriptors per process is usually 1024. This limits the number of -connections and opened trace files. This limit can be configured with -*ulimit*(3). - - include::common-footer.txt[] @@ -366,6 +397,4 @@ SEE ALSO -------- man:lttng(1), man:lttng-sessiond(8), -man:lttng-crash(1), -man:lttng-ust(3), man:babeltrace2(1) diff --git a/doc/man/lttng-remove-trigger.1.txt b/doc/man/lttng-remove-trigger.1.txt index e51fd10d0..59d5da122 100644 --- a/doc/man/lttng-remove-trigger.1.txt +++ b/doc/man/lttng-remove-trigger.1.txt @@ -1,6 +1,6 @@ lttng-remove-trigger(1) ======================= -:revdate: 5 March 2021 +:revdate: 29 April 2021 NAME @@ -18,10 +18,10 @@ DESCRIPTION ----------- The `lttng remove-trigger` command removes the trigger named 'NAME'. -See man:lttng-add-trigger(1) to learn more about LTTng triggers. +See man:lttng-concepts(7) to learn more about LTTng triggers. -List the available triggers and their name with the -man:lttng-list-triggers(1) command. +List the triggers of your Unix user, or of all users if your +Unix user is `root`, with the man:lttng-list-triggers(1) command. The `remove-trigger` command removes a trigger which belong to your Unix user. If your Unix user is `root`, you can remove the trigger of another @@ -47,6 +47,7 @@ include::common-cmd-footer.txt[] SEE ALSO -------- +man:lttng(1), man:lttng-add-trigger(1), -man:lttng-list-triggers(1), -man:lttng(1) +man:lttng-concepts(7), +man:lttng-list-triggers(1) diff --git a/doc/man/lttng-rotate.1.txt b/doc/man/lttng-rotate.1.txt index c582126bd..baebea94b 100644 --- a/doc/man/lttng-rotate.1.txt +++ b/doc/man/lttng-rotate.1.txt @@ -1,11 +1,11 @@ lttng-rotate(1) =============== -:revdate: 18 October 2019 +:revdate: 30 April 2021 NAME ---- -lttng-rotate - Archive a tracing session's current trace chunk +lttng-rotate - Archive the current trace chunk of an LTTng tracing session SYNOPSIS @@ -16,138 +16,78 @@ SYNOPSIS DESCRIPTION ----------- -The `lttng rotate` command archives the current trace chunk of the -current tracing session, or of the tracing session named 'SESSION' if -provided, to the file system. This action is called a tracing session -_rotation_. - -Once LTTng archives a trace chunk, it does not manage it anymore: you -can read it, modify it, move it, or remove it. - -An _archived trace chunk_ is a collection of metadata and data stream -files which form a self-contained LTTng trace. - -The _current trace chunk_ of a given tracing session includes: - -* The stream files already written 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 with - man:lttng-start(1). -** The last rotation, either an immediate one with `lttng rotate`, or an - automatic one from a rotation schedule previously set with - man:lttng-enable-rotation(1). -* The content of all the non-flushed sub-buffers of the tracing - session's channels. - -You can use `lttng rotate`: - -* At any time when the tracing session is active (see - man:lttng-start(1)). -* A single time once the tracing session becomes inactive - (see man:lttng-stop(1)). - -By default, the `lttng rotate` command ensures that LTTng finished -performing the tracing session rotation before it prints the archived -trace chunk's path and exits. The printed path is absolute when the -tracing session was created in normal mode and relative to the relay -daemon's output directory (see the nloption:--output option in -man:lttng-relayd(8)) when it was created in network streaming mode (see -man:lttng-create(1)). - -With the option:--no-wait option, the command finishes immediately, so -that LTTng might not have completed the rotation when the command exits. -In this case, there is no easy way to know when the current trace chunk -becomes archived, and the command does not print the archived trace -chunk's path. +The `lttng rotate` command archives to the file system +the current trace chunk of: -Because when LTTng performs a tracing session rotation, it flushes the -tracing session's current sub-buffers, 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. +With the 'SESSION' argument:: + The tracing session named 'SESSION'. -See <> for important limitations regarding -this command. +Without the 'SESSION' argument:: + The current tracing session (see man:lttng-concepts(7) to learn more + about the current tracing session). +This action is called a _tracing session rotation_. -Trace chunk archive naming -~~~~~~~~~~~~~~~~~~~~~~~~~~ -A trace chunk archive is a subdirectory of the `archives` subdirectory -within a tracing session's output directory (see the nloption:--output -option in man:lttng-create(1) and man:lttng-relayd(8)). +See man:lttng-concepts(7) to learn more about the tracing session +rotation and trace chunk concepts. -A trace chunk archive contains, through tracing domain and possibly -UID/PID subdirectories, metadata and data stream files. +You can use the `rotate` command: -A trace chunk archive is, at the same time: +* Any time the tracing session is active. -* A self-contained LTTng trace. -* A member of a set of trace chunk archives which form the complete - trace of a tracing session. +* A single time once the tracing session becomes inactive. -In other words, an LTTng trace reader can read both the tracing -session output directory (all the trace chunk archives), or a -single trace chunk archive. +See man:lttng-concepts(7) to learn more about the activity of a +tracing session. -When LTTng performs a tracing session rotation, it names the resulting -trace chunk archive as such, relative to the tracing session's output -directory: +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 +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 +man:lttng-create(1)). -[verse] -archives/__BEGIN__-__END__-__ID__ - -__BEGIN__:: - Date and time of the beginning of the trace chunk archive with - the ISO{nbsp}8601-compatible `YYYYmmddTHHMMSS±HHMM` form, where - `YYYYmmdd` is the date and `HHMMSS±HHMM` is the time with the - time zone offset from UTC. -+ -Example: `20171119T152407-0500` - -__END__:: - Date and time of the end of the trace chunk archive with - the ISO{nbsp}8601-compatible `YYYYmmddTHHMMSS±HHMM` form, where - `YYYYmmdd` is the date and `HHMMSS±HHMM` is the time with the - time zone offset from UTC. -+ -Example: `20180118T152407+0930` - -__ID__:: - Unique numeric identifier of the trace chunk within its tracing - session. - -Trace chunk archive name example: +Make the command exit immediately with the option:--no-wait option. In +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. ----- -archives/20171119T152407-0500-20171119T151422-0500-3 ----- +Because LTTng flushes the current sub-buffers of the selected tracing +session when it performs a tracing 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)). -include::common-cmd-options-head.txt[] +[IMPORTANT] +==== +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)). -option:-n, option:--no-wait:: - Do not ensure that the rotation is done before returning to - the prompt. +* 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). +* LTTng is not currently performing an immediate rotation (this + command). +==== -include::common-cmd-help-options.txt[] +include::common-cmd-options-head.txt[] -[[limitations]] -LIMITATIONS ------------ -The `lttng rotate` command only works when: -* The tracing session is created in normal mode or in network streaming - mode (see man:lttng-create(1)). +option:-n, option:--no-wait:: + Do not ensure that the tracing session rotation operation is + completed before exiting. -* No channel was created with a configured trace file count or size - limit (see the nloption:--tracefile-size and - nloption:--tracefile-count options in man:lttng-enable-channel(1)). -* No immediate rotation (`lttng rotate`) is currently happening. +include::common-cmd-help-options.txt[] include::common-cmd-footer.txt[] @@ -155,6 +95,7 @@ include::common-cmd-footer.txt[] SEE ALSO -------- -man:lttng-enable-rotation(1), +man:lttng(1), +man:lttng-concepts(7), man:lttng-disable-rotation(1), -man:lttng(1) +man:lttng-enable-rotation(1) diff --git a/doc/man/lttng-save.1.txt b/doc/man/lttng-save.1.txt index 1f526ef66..baf51fded 100644 --- a/doc/man/lttng-save.1.txt +++ b/doc/man/lttng-save.1.txt @@ -1,6 +1,6 @@ lttng-save(1) ============= -:revdate: 28 November 2016 +:revdate: 3 May 2021 NAME @@ -11,49 +11,62 @@ lttng-save - Save LTTng tracing session configurations SYNOPSIS -------- [verse] -*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *save* [option:--force] [option:--output-path='PATH'] ['SESSION'] +*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *save* [option:--force] [option:--output-path='DIR'] ['SESSION'] DESCRIPTION ----------- -The `lttng save` command saves the configurations of one or more -tracing sessions to files. +The `lttng save` command saves to files the configurations of: -The `lttng save` command is used in conjunction with the -man:lttng-load(1) command to save and restore the complete -configurations of tracing sessions. This includes the enabled channels -and recording event rules, the context added to channels, the tracing -activity, and more. `lttng save` does not save tracing data, only the -tracing session parameters. +With the 'SESSION' argument:: + The tracing session named 'SESSION'. -If 'SESSION' is omitted, all the existing tracing session configurations -are saved (equivalent to using the option:--all option). Otherwise, -'SESSION' is the name of an existing tracing session. `lttng list` -outputs all the existing tracing sessions (see man:lttng-list(1)). +Without the 'SESSION' argument:: + *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)). ++ +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. + +Use the `save` command in conjunction with the man:lttng-load(1) command +to save and restore the complete configurations of tracing sessions. + +The `save` command does :not: save tracing data, only the tracing +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`). Each tracing session configuration -file is named `SESSION.lttng`, where `SESSION` is the original tracing -session name. The default output directory path can be overridden with -the option:--output-path option. +(`$LTTNG_HOME` defaults to `$HOME`). Override the default output +directory path with the option:--output-path option. Each tracing +session configuration file is named __SNAME__++.lttng++, +where{nbsp}__SNAME__ is the original tracing session name. -By default, existing tracing session configuration files are not -overwritten when saving; the command fails. The option:--force option -can be used to allow this. +By default, the `save` command does :not: overwrite existing tracing +session configuration files: the command fails. Allow the `save` command +to overwrite existing tracing session configuration files with the +option:--force option. include::common-cmd-options-head.txt[] option:-a, option:--all:: - Save all tracing session configurations (default). + 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'. option:-f, option:--force:: Overwrite existing tracing session configuration files when saving. -option:-o 'PATH', option:--output-path='PATH':: - Set output directory path to 'PATH'. +option:-o 'DIR', option:--output-path='DIR':: + Save tracing session configuration files to the directory 'DIR' + instead of `$LTTNG_HOME/.lttng/sessions` (`$LTTNG_HOME` defaults to + `$HOME`). include::common-cmd-help-options.txt[] @@ -64,5 +77,6 @@ include::common-cmd-footer.txt[] SEE ALSO -------- -man:lttng-load(1), -man:lttng(1) +man:lttng(1), +man:lttng-concepts(7), +man:lttng-load(1) diff --git a/doc/man/lttng-sessiond.8.txt b/doc/man/lttng-sessiond.8.txt index 8edb004b7..e9ec73d16 100644 --- a/doc/man/lttng-sessiond.8.txt +++ b/doc/man/lttng-sessiond.8.txt @@ -1,6 +1,8 @@ lttng-sessiond(8) ================= :revdate: 21 April 2021 +:daemon-bin-name: lttng-sessiond +:daemon-ini-section: sessiond NAME @@ -36,8 +38,8 @@ include::common-intro.txt[] An LTTng session daemon, `lttng-sessiond`, is a program which: -* Manages tracing sessions (see man:lttng-create(1) to learn more about - tracing sessions). +* Manages tracing sessions (see man:lttng-concepts(7) to learn more + about tracing sessions). * Controls the various components (like tracers and consumer daemons) of LTTng. @@ -71,46 +73,19 @@ commands before it exits. NOTE: The LTTng project recommends that you start the session daemon at boot time for stable and long-term tracing. +[NOTE] +==== +For an unprivileged Unix user running `lttng-sessiond`, the maximum +number of file descriptors per process is usually 1024. This limits the +number of traceable applications, since, for each instrumented +application, there are two file descriptors per CPU as well as one +socket for bidirectional communication. -[[cfg]] -Daemon configuration -~~~~~~~~~~~~~~~~~~~~ -When you run `lttng-sessiond`, it configures itself from, in this order: - -. The INI configuration file +{system_lttng_conf}+, if any. - -. The INI configuration file `$LTTNG_HOME/.lttng/lttng.conf`, if any. -+ -`$LTTNG_HOME` defaults to `$HOME`. - -. With the option:--config='PATH' option: the INI configuration file - 'PATH'. - -. The command-line options. - -Each step can override a previous configuration property. - -In INI configuration files, the session daemon only reads the properties -under the `sessiond` INI section. Each INI property is: - -Key:: - The long name of a command-line option to set (see the - <> section below). - -Value:: - The selected command-line option accepts an argument::: - Option argument (string). +For the `root` user, the limit is usually 65,535. +==== - The selected command-line option is a switch::: - `true`:::: - `yes`:::: - `on`:::: - Enable the option. - `false`:::: - `no`:::: - `off`:::: - Disable the option. +include::common-daemon-cfg.txt[] INI configuration file example: @@ -153,8 +128,8 @@ With the option:--load='PATH' option:: [[options]] OPTIONS ------- -Daemon configuration -~~~~~~~~~~~~~~~~~~~~ +General daemon configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ option:-b, option:--background:: Start as a Unix daemon, but keep file descriptors (console) open. + @@ -211,11 +186,15 @@ option:--extra-kmod-probes='PROBE'[,'PROBE']...:: For each 'PROBE' argument, load the LTTng kernel probe module named ++lttng-probe-++__PROBE__++.ko++, in addition to loading the default LTTng kernel probe modules. ++ +See also the `LTTNG_EXTRA_KMOD_PROBES` environment variable. option:--kmod-probes='PROBE'[,'PROBE']...:: Only load, for each 'PROBE' argument, the LTTng kernel probe module named ++lttng-probe-++__PROBE__++.ko++, instead of loading the default LTTng kernel probe modules. ++ +See also the `LTTNG_KMOD_PROBES` environment variable. option:--no-kernel:: Disable Linux kernel tracing. @@ -236,15 +215,23 @@ option:-c 'PATH', option:--client-sock='PATH':: option:--consumerd32-libdir='PATH':: Set the 32-bit consumer daemon library directory to 'PATH'. ++ +See also the `LTTNG_CONSUMERD32_LIBDIR` environment variable. option:--consumerd32-path='PATH':: Set the 32-bit consumer daemon binary path to 'PATH'. ++ +See also the `LTTNG_CONSUMERD32_BIN` environment variable. option:--consumerd64-libdir='PATH':: Set the 64-bit consumer daemon library directory to 'PATH'. ++ +See also the `LTTNG_CONSUMERD64_LIBDIR` environment variable. option:--consumerd64-path='PATH':: Set the 64-bit consumer daemon binary path to 'PATH'. ++ +See also the `LTTNG_CONSUMERD32_BIN` environment variable. option:--kconsumerd-cmd-sock='PATH':: Set the command Unix socket path of the Linux kernel consumer daemon @@ -334,28 +321,33 @@ Default: +{default_app_socket_rw_timeout}+. `LTTNG_CONSUMERD32_BIN`:: 32-bit consumer daemon binary path. + -The option:--consumerd32-path option overrides this variable. +The option:--consumerd32-path option overrides this environment +variable. `LTTNG_CONSUMERD32_LIBDIR`:: 32-bit consumer daemon library directory path. + -The option:--consumerd32-libdir option overrides this variable. +The option:--consumerd32-libdir option overrides this environment +variable. `LTTNG_CONSUMERD64_BIN`:: 64-bit consumer daemon binary path. + -The option:--consumerd64-path option overrides this variable. +The option:--consumerd64-path option overrides this environment +variable. `LTTNG_CONSUMERD64_LIBDIR`:: 64-bit consumer daemon library directory path. + -The option:--consumerd64-libdir option overrides this variable. +The option:--consumerd64-libdir option overrides this environment +variable. `LTTNG_DEBUG_NOCLONE`:: Set to `1` to disable the use of man:clone(2)/man:fork(2). + -Setting this variable is considered insecure, but it's required to allow -debuggers to work with `lttng-sessiond` on some operating systems. +Setting this environment variable is considered insecure, but it's +required to allow debuggers to work with `lttng-sessiond` on some +operating systems. `LTTNG_EXTRA_KMOD_PROBES`:: Extra LTTng kernel probe modules to load. @@ -429,20 +421,10 @@ EXIT STATUS Fatal error -LIMITATIONS ------------ -For an unprivileged Unix user running `lttng-sessiond`, the maximum -number of file descriptors per process is usually 1024. This limits the -number of traceable applications, since, for each instrumented -application, there are two file descriptors per CPU as well as one -socket for bidirectional communication. - -For the `root` user, the limit is usually 65,535. - - include::common-footer.txt[] SEE ALSO -------- -man:lttng(1) +man:lttng(1), +man:lttng-concepts(7) diff --git a/doc/man/lttng-set-session.1.txt b/doc/man/lttng-set-session.1.txt index 2e97c055b..6c04caf92 100644 --- a/doc/man/lttng-set-session.1.txt +++ b/doc/man/lttng-set-session.1.txt @@ -1,6 +1,6 @@ lttng-set-session(1) ==================== -:revdate: 21 April 2021 +:revdate: 29 April 2021 NAME @@ -19,36 +19,14 @@ DESCRIPTION The `lttng set-session` command sets the current tracing session of your Unix user to the tracing session named 'SESSION'. -See man:lttng-create(1) to learn more about the current tracing session. - -The following man:lttng(1) commands select the current tracing session -if you don't specify one: - -* man:lttng-add-context(1) -* man:lttng-clear(1) -* man:lttng-destroy(1) -* man:lttng-disable-channel(1) -* man:lttng-disable-event(1) -* man:lttng-disable-rotation(1) -* man:lttng-enable-channel(1) -* man:lttng-enable-event(1) -* man:lttng-enable-rotation(1) -* man:lttng-regenerate(1) -* man:lttng-rotate(1) -* man:lttng-save(1) -* man:lttng-snapshot(1) -* man:lttng-start(1) -* man:lttng-status(1) -* man:lttng-stop(1) -* man:lttng-track(1) -* man:lttng-untrack(1) -* man:lttng-view(1) +See man:lttng-concepts(7) to learn more about the current tracing session. The `set-session` command effectively updates the `$LTTNG_HOME/.lttngrc` file. -List the tracing sessions of your Unix user with the man:lttng-list(1) -command. +List the tracing 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. include::common-cmd-options-head.txt[] @@ -62,6 +40,7 @@ include::common-cmd-footer.txt[] SEE ALSO -------- +man:lttng(1), +man:lttng-concepts(7), man:lttng-create(1), -man:lttng-destroy(1), -man:lttng(1) +man:lttng-destroy(1) diff --git a/doc/man/lttng-snapshot.1.txt b/doc/man/lttng-snapshot.1.txt index d60d6fcef..94bf7c9f5 100644 --- a/doc/man/lttng-snapshot.1.txt +++ b/doc/man/lttng-snapshot.1.txt @@ -1,139 +1,184 @@ lttng-snapshot(1) ================= -:revdate: 9 November 2018 +:revdate: 3 May 2021 NAME ---- -lttng-snapshot - Take LTTng snapshots and configure snapshot outputs +lttng-snapshot - Take a snapshot of an LTTng tracing session SYNOPSIS -------- -Add a snapshot output: +Take a tracing session snapshot: [verse] -*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot add-output* [option:--max-size='SIZE'] +*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') + [option:--ctrl-url='URL' option:--data-url='URL' | 'URL'] -Remove a snapshot output: +Add a snapshot output to a tracing session: [verse] -*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot del-output* [option:--session='SESSION'] - ('ID' | 'NAME') +*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') -List current snapshot outputs: +Show the snapshot output of a tracing session: [verse] -*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot list-output* [option:--session='SESSION'] +*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot* *list-output* [option:--session='SESSION'] -Take a snapshot: +Remove the snapshot output from a tracing session: [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') +*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot* *del-output* [option:--session='SESSION'] *1* DESCRIPTION ----------- -The `lttng snapshot` command manages the snapshot outputs and takes -snapshots. - -A _snapshot_ is a dump of the current sub-buffers of all the channels -of a given tracing session. When a snapshot is taken, the memory dump -is sent to the registered snapshot outputs. +The `lttng snapshot` command can take a snapshot of, add or remove a +snapshot output, and show the snapshot output of: -The tracing session should be created in _snapshot mode_ to make sure -that taking snapshots is allowed. This is done at tracing session -creation time using the man:lttng-create(1) command's -nloption:--snapshot option. +With the option:--session='SESSION' option:: + The tracing session named 'SESSION'. -Note that, when a snapshot is taken, the sub-buffers are not cleared. -This means that different recorded snapshots may contain the same -events. - -If you want, instead, to keep all the trace data, but divide it into -archived chunks which are then free to process (just like snapshots), -see the lttng-rotate(1) and lttng-enable-rotation(1) commands. Trace -chunk archives do not overlap like snapshots can. - - -Snapshot outputs -~~~~~~~~~~~~~~~~ -Snapshot outputs are the destinations of snapshot files when a -snapshot is taken using the `record` action. +Without the option:--session option:: + The current tracing session (see man:lttng-concepts(7) to learn more + about the current tracing session). -As of this version, only one snapshot output is allowed. +See man:lttng-concepts(7) to learn more about tracing sessions. -A snapshot output can be added using the `add-output` action. The -output destination URL is set using either the 'URL' positional -argument, or both the option:--ctrl-url and option:--data-url options. -See man:lttng-create(1) to learn more about the URL format. +A _snapshot_ is a dump of the current sub-buffers of all the channels of +the selected tracing session. -A name can be assigned to an output when adding it using the -option:--name option. This name is part of the names of the -snapshot files written to this output. +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 +<> section below to learn more. -By default, the snapshot files can be as big as the sum of the -sizes of all the sub-buffers or all the channels of the selected -tracing session. The maximum total size of all the snapshot files can -be configured using the option:--max-size option. +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. -Snapshot outputs can be listed using the `list-output` action. +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. -Snapshot outputs can be removed using the `del-output` action. The -configured name can be used when removing an output, or an ID as -listed by the `list-output` action. +A `snapshot-session` trigger action can also take a tracing session +snapshot (see man:lttng-add-trigger(1)). +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. -Taking a snapshot -~~~~~~~~~~~~~~~~~ -Taking a snapshot of the current tracing session is as easy as: +[NOTE] +==== +Before you take a snapshot on a system with a high event throughput, the +LTTng project recommends that you first run the man:lttng-stop(1) +command. Otherwise, the snapshot could contain ``holes'', the result of +the tracers overwriting unconsumed trace packets during the snapshot +operation. -[role="term"] ----- -$ lttng snapshot record ----- +After LTTng writes the snapshot trace data, you can restart the tracing +session with the man:lttng-start(1) command. +==== -This writes the snapshot files to the configured output. It is possible -to use a custom, unregistered output at record time using the same -options supported by the `add-output` action. -NOTE: Before taking a snapshot on a system with a high event throughput, -it is recommended to first run `lttng stop` (see -man:lttng-stop(1)). Otherwise, the snapshot could contain "holes", -the result of the tracers overwriting unconsumed trace packets during -the record operation. After the snapshot is recorded, the tracers can be -started again with `lttng start` (see man:lttng-start(1)). +[[output]] +Snapshot output +~~~~~~~~~~~~~~~ +When you take a tracing 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:: + The output defined by the 'URL' non-option argument or by the + arguments of the options. ++ +See man:lttng-create(1) for the format of 'URL'. + +Otherwise:: + The snapshot output of the selected tracing 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. ++ +When you create a snapshot mode tracing 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: ++ +-- +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. + +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. +-- ++ +Show the current snapshot output of a tracing session with the +`list-output` action. ++ +Remove the snapshot output of a tracing session with the +`del-output` action. + +For both the `record` and `add-output` actions: + +* Assign a name to a snapshot output with the option:--name='NAME' + option. ++ +'NAME' becomes part of the snapshot trace file names which LTTng sends +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 + session. ++ +Set the maximum total size of all the snapshot trace files LTTng writes +with the option:--max-size option. include::common-cmd-options-head.txt[] -Target -~~~~~~ +Recording target +~~~~~~~~~~~~~~~~ option:-s 'SESSION', option:--session='SESSION':: - Take a snapshot of the sub-buffers of the channels contained in - the tracing session named 'SESSION' instead of the current - tracing session. + Take a snapshot of the sub-buffers of the tracing session named + 'SESSION' instead of the current tracing session. -Snapshot output -~~~~~~~~~~~~~~~ +Output +~~~~~~ +See the <> section above. + option:-C 'URL', option:--ctrl-url='URL':: - Set control path URL to 'URL' (must use option:--data-url option - also). + Set the control path URL to 'URL'. ++ +You must also use the option:--data-url option. ++ +See man:lttng-create(1) for the format of 'URL'. option:-D 'URL', option:--data-url='URL':: - Set data path URL to 'URL' (must use option:--ctrl-url option - also). + Set the trace data path URL to 'URL'. ++ +You must also use the option:--ctrl-url option. ++ +See man:lttng-create(1) for the format of 'URL'. option:-m 'SIZE', option:--max-size='SIZE':: - Limit the total size of all the snapshot files written when - recording a snapshot to 'SIZE' bytes. The `k` (kiB), `M` (MiB), - and `G` (GiB) suffixes are supported. + Set the maximum total size of all the snapshot trace files LTTng + writes when taking a snapshot to 'SIZE' bytes. ++ +The `k`{nbsp}(KiB), `M`{nbsp}(MiB), and `G`{nbsp}(GiB) suffixes are +supported. option:-n 'NAME', option:--name='NAME':: Assign the name 'NAME' to the snapshot output. @@ -147,4 +192,6 @@ include::common-cmd-footer.txt[] SEE ALSO -------- -man:lttng(1) +man:lttng(1), +man:lttng-concepts(7), +man:lttng-create(1) diff --git a/doc/man/lttng-start.1.txt b/doc/man/lttng-start.1.txt index a5f8c2f50..53b1c8aa7 100644 --- a/doc/man/lttng-start.1.txt +++ b/doc/man/lttng-start.1.txt @@ -1,6 +1,6 @@ lttng-start(1) ============== -:revdate: 21 April 2021 +:revdate: 29 April 2021 NAME @@ -23,17 +23,14 @@ With the 'SESSION' argument:: The tracing session named 'SESSION'. Without the 'SESSION' argument:: - The current tracing session (see man:lttng-create(1) and - man:lttng-set-session(1) to learn more about the current tracing - session). + The current tracing session (see man:lttng-concepts(7) to learn more + about the current tracing session). + +See man:lttng-concepts(7) to learn more about tracing sessions. The selected tracing session must be inactive (stopped). A tracing session is inactive on creation (see man:lttng-create(1)). -An active tracing session is an implicit recording event rule condition -(see man:lttng-enable-event(1)). In other words, a recording event rule -cannot match an event when its tracing session is inactive. - A `start-session` trigger action can also start a tracing session (see man:lttng-add-trigger(1)). @@ -53,6 +50,7 @@ SEE ALSO -------- man:lttng(1), man:lttng-add-trigger(1), +man:lttng-concepts(7), man:lttng-create(1), man:lttng-enable-event(1), man:lttng-stop(1) diff --git a/doc/man/lttng-status.1.txt b/doc/man/lttng-status.1.txt index caeac9703..81f755d57 100644 --- a/doc/man/lttng-status.1.txt +++ b/doc/man/lttng-status.1.txt @@ -1,6 +1,6 @@ lttng-status(1) =============== -:revdate: 21 April 2021 +:revdate: 29 April 2021 NAME @@ -17,8 +17,8 @@ SYNOPSIS DESCRIPTION ----------- The `lttng status` command shows the status of the current tracing -session (see man:lttng-create(1) and man:lttng-set-session(1) to learn -more about the current tracing session). +session (see man:lttng-concepts(7) to learn more about the current +tracing session). This command is equivalent to: @@ -40,6 +40,7 @@ include::common-cmd-footer.txt[] SEE ALSO -------- man:lttng(1), +man:lttng-concepts(7), man:lttng-create(1), man:lttng-list(1), man:lttng-set-session(1) diff --git a/doc/man/lttng-stop.1.txt b/doc/man/lttng-stop.1.txt index 5c21c6ce4..c6f63c36c 100644 --- a/doc/man/lttng-stop.1.txt +++ b/doc/man/lttng-stop.1.txt @@ -1,6 +1,6 @@ lttng-stop(1) ============= -:revdate: 21 April 2021 +:revdate: 29 April 2021 NAME @@ -23,18 +23,15 @@ With the 'SESSION' argument:: The tracing session named 'SESSION'. Without the 'SESSION' argument:: - The current tracing session (see man:lttng-create(1) and - man:lttng-set-session(1) to learn more about the current tracing - session). + The current tracing session (see man:lttng-concepts(7) to learn more + about the current tracing session). + +See man:lttng-concepts(7) to learn more about tracing sessions. The selected tracing session must be active (started; see man:lttng-start(1)). A tracing session is inactive on creation (see man:lttng-create(1)). -An active tracing session is an implicit recording event rule condition -(see man:lttng-enable-event(1)). In other words, a recording event rule -cannot match an event when its tracing session is inactive. - A `stop-session` trigger action can also stop a tracing session (see man:lttng-add-trigger(1)). @@ -74,6 +71,7 @@ SEE ALSO -------- man:lttng(1), man:lttng-add-trigger(1), +man:lttng-concepts(7), man:lttng-create(1), man:lttng-enable-event(1), man:lttng-rotate(1), diff --git a/doc/man/lttng-track.1.txt b/doc/man/lttng-track.1.txt index 6157bcd43..0e6cfceba 100644 --- a/doc/man/lttng-track.1.txt +++ b/doc/man/lttng-track.1.txt @@ -1,79 +1,108 @@ lttng-track(1) ============== -:revdate: 4 March 2020 +:revdate: 1 May 2021 NAME ---- -lttng-track - Add one or more values to an LTTng process attribute tracker +lttng-track - Allow specific processes to record LTTng events SYNOPSIS -------- -Add specific process attribute values to a Linux kernel domain tracker: +Allow specific processes to record Linux kernel events: [verse] -*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* option:--kernel +*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* option:--kernel [option:--session='SESSION'] (option:--pid=PID[,PID]... | option:--vpid=VPID[,VPID]... | - option:--uid=UID[,UID]... | option:--vuid=VUID[,VUID]... | - option:--gid=GID[,GID]... | option:--vgid=VGID[,VGID]... )... + option:--uid=UID[,UID]... | option:--vuid=VUSER[,VUSER]... | + option:--gid=GID[,GID]... | option:--vgid=VGROUP[,VGROUP]...)... -Add all possible process attribute values to a Linux kernel domain tracker: [verse] -*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* option:--kernel - option:--all (option:--pid | option:--vpid | option:--uid | - option:--vuid | option:--gid | option:--vgid )... +*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* option:--kernel [option:--session='SESSION'] + option:--all (option:--pid | option:--vpid | option:--uid | option:--vuid | option:--gid | option:--vgid)... -Add specific process attribute values to a user space domain tracker: +Allow specific processes to record user space events: [verse] -*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* option:--userspace - (option:--vpid=VPID[,VPID]... | option:--vuid=VUID[,VUID]... | option:--vgid=VGID[,VGID]...)... - -Add all possible process attribute values to a user space domain tracker: +*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* option:--userspace [option:--session='SESSION'] + (option:--vpid=VPID[,VPID]... | option:--vuid=VUSER[,VUSER]... | + option:--vgid=VGROUP[,VGROUP]...)... [verse] -*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* option:--userspace +*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* option:--userspace [option:--session='SESSION'] option:--all (option:--vpid | option:--vgid | option:--vuid)... DESCRIPTION ----------- -The `lttng track` commands adds one or more values to a -process attribute tracker. +The `lttng track` command allows one or more processes to record LTTng +events based on their attributes within: -A process attribute tracker is an _inclusion set_ of process attributes. -Tracked processes are allowed to emit events, provided those events are -targeted by enabled recording event rules (see -man:lttng-enable-event(1)). +With the option:--session='SESSION' option:: + The tracing session named 'SESSION'. -Tracker values can be removed from an inclusion set with -man:lttng-untrack(1). +Without the option:--session option:: + The current tracing session (see man:lttng-concepts(7) to learn more + about the current tracing session). -The available process attribute trackers are: +See man:lttng-concepts(7) to learn more about tracing sessions and +recording event rules. -* Process ID (PID) -* Virtual PID (VPID) -* User ID (UID) -* Virtual UID (VUID) -* Group ID (GID) -* Virtual GID (VGID) +The `track` command adds values to _inclusion sets_ of process +attributes. The available inclusion sets are, for a given tracing +session: +With the option:--kernel option:: ++ +* Process ID (PID). -A tracker follows one or more process attribute values; only the -processes with a tracked value are allowed to emit events. By default, -all possible values on the system are tracked: any process may emit -enabled events, the equivalent of: +* Virtual process ID (VPID). ++ +This is the PID as seen by the application. -[role="term"] ----- -$ lttng track --kernel --pid --vpid --uid --vuid --gid --vgid --all -$ lttng track --userspace --vpid --vuid --vgid --all ----- +* Unix user ID (UID). -With the PID tracker, for example, you can record all system calls of a -given process: +* Virtual Unix user ID (VUID). ++ +This is the UID as seen by the application. + +* Unix group ID (GID). + +* Virtual Unix group ID (VGID). ++ +This is the GID as seen by the application. + +With the option:--userspace option:: ++ +* VPID +* VUID +* VGID + +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 +of{nbsp}__ER__. + +By default, on tracing 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 +process attribute values. + +If a given inclusion set{nbsp}__IS__ contains all the possible values +(option:--all option), then using the `track` command to add one or more +values{nbsp}__V__ to{nbsp}__IS__: + +. Removes all the values from{nbsp}__IS__. ++ +This effectively makes{nbsp}__IS__ empty. + +. Adds{nbsp}__V__ to{nbsp}__IS__. + +Example: with the PID inclusion set, you can record all the system calls +of a given process: [role="term"] ---- @@ -82,173 +111,181 @@ $ lttng track --kernel --pid=2345 $ lttng start ---- -If all the PIDs are tracked (with the option:--pid and option:--all -options), which is the default state of all domains when creating a -tracing session), then using the track command with one or more -specific PIDs has the effect of first removing all the PIDs from the -inclusion set, then adding the specified PIDs. +Remove values from an inclusion set with the man:lttng-untrack(1) +command. -Example -~~~~~~~ -Assume the maximum system PID is 7 for this example. +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. -Initial inclusion set: +Assume the maximum system PID is 7 for this example. +. Initial inclusion set: ++ ------------------------------- [0] [1] [2] [3] [4] [5] [6] [7] ------------------------------- -Command: - +. Command: ++ [role="term"] ---- $ lttng track --kernel --pid=3,6,7 ---- - -inclusion set: - ++ +Inclusion set is now: ++ ------------------------------- [ ] [ ] [ ] [3] [ ] [ ] [6] [7] ------------------------------- -Command: - +. Command: ++ [role="term"] ---- $ lttng untrack --kernel --pid=7 ---- - -inclusion set: - ++ +Inclusion set is now: ++ ------------------------------- [ ] [ ] [ ] [3] [ ] [ ] [6] [ ] ------------------------------- -Command: - +. Command: ++ [role="term"] ---- $ lttng track --kernel --pid=1,5 ---- - -inclusion set: - ++ +Inclusion set is now: ++ ------------------------------- [ ] [1] [ ] [3] [ ] [5] [6] [ ] ------------------------------- -See the man:lttng-untrack(1) for more details about removing -values from the inclusion set. +Remove values from an inclusion set with the man:lttng-untrack(1) +command. include::common-cmd-options-head.txt[] -Domain -~~~~~~ +Tracing domain +~~~~~~~~~~~~~~ One of: option:-k, option:--kernel:: - Track process attributes in the Linux kernel domain. + Add values to one or more Linux kernel inclusion sets. option:-u, option:--userspace:: - Track process attributes in the user space domain. - + Add values to one or more user space inclusion sets. -Target -~~~~~~ +Recording target +~~~~~~~~~~~~~~~~ option:-s 'SESSION', option:--session='SESSION':: - Track process attributes in the tracing session named 'SESSION' instead of - the current tracing session. + Add values to one or more inclusion sets of the tracing session + named 'SESSION' instead of the current tracing session. -Tracking -~~~~~~~~ -option:-a, option:--all:: - Used in conjunction with a single, empty option:--pid, - option:--vpid, option:--uid, option:--vuid, option:--gid, - or option:--vgid option: track _all_ possible process attribute - values (add all values to the inclusion set). - +Inclusion set selection +~~~~~~~~~~~~~~~~~~~~~~~ option:-p ['PID'[,'PID']...], option:--pid[='PID'[,'PID']...]:: - Track process ID values 'PID' (add them to the process ID inclusion - set). + For each 'PID' argument, add 'PID' to the process ID inclusion set + of the selected tracing session and domain. + -'PID' is the process ID attribute of a process as seen from the _root -PID namespace_ (see man:pid_namespaces(7)). It can only be used with -the option:--kernel domain option. +'PID' is the process ID attribute of a process as seen from the root +PID namespace (see man:pid_namespaces(7)). + -The 'PID' argument must be omitted when also using the option:--all -option. +Only available with option:--kernel option. option:--vpid[='VPID'[,'VPID']...]:: - Track virtual process ID values 'VPID' (add them to the virtual - process ID inclusion set). + For each 'VPID' argument, add 'VPID' to the virtual process ID + inclusion set of the selected tracing 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)). -+ -The 'VPID' argument must be omitted when also using the option:--all -option. +the PID namespace of the process (see man:pid_namespaces(7)). option:--uid[='USER'[,'USER']...]:: - Track user ID process attribute values 'USER' (add them to the - user ID inclusion set). + For each 'USER' argument, add 'USER' to the user ID inclusion set of + the selected tracing session and domain. + -'USER' is the real user ID (see man:getuid(3)) of a process as seen -from the _root user namespace_ (see man:user_namespaces(7)). It can -only be used with the option:--kernel domain option. +'USER' is either: + -'USER' can also be a user name. The user name resolution is performed -by the session daemon (see man:lttng-sessiond(8)) on addition to the -user ID inclusion set. +-- +* The real user ID (see man:getuid(3)) of a process as seen + from the root user namespace (see man:user_namespaces(7)). + +* A user name. ++ +The connected LTTng session daemon (see man:lttng-sessiond(8)) performs +the user name resolution on addition to the user ID inclusion set. +-- + -The 'USER' argument must be omitted when also using the option:--all -option. +Only available with option:--kernel option. -option:--vuid[='USER'[,'USER']...]:: - Track virtual user ID process attribute values 'USER' (add them to - the virtual user ID inclusion set). +option:--vuid[='VUSER'[,'VUSER']...]:: + For each 'VUSER' argument, add 'VUSER' to the virtual user ID + inclusion set of the selected tracing session and domain. + -'USER' is the real user ID (see man:getuid(3)) of a process as seen -from the _user namespace_ of the process (see man:user_namespaces(7)). +'VUSER' is either: + -'USER' can also be a user name. The user name resolution is performed -by the session daemon (see man:lttng-sessiond(8)) on addition to the -virtual user ID inclusion set. +-- +* The real user ID (see man:getuid(3)) of a process as seen + from the user namespace (see man:user_namespaces(7)). + +* A user name. + -The 'USER' argument must be omitted when also using the option:--all -option. +The connected LTTng session daemon (see man:lttng-sessiond(8)) performs +the user name resolution on addition to the virtual user ID inclusion +set. +-- option:--gid[='GROUP'[,'GROUP']...]:: - Track group ID process attribute values 'GROUP' (add them to the - group ID inclusion set). + For each 'GROUP' argument, add 'GROUP' to the group ID + inclusion set of the selected tracing session and domain. + -'GROUP' is the real group ID (see man:getgid(3)) of a process as seen -from the _root user namespace_ (see man:user_namespaces(7)). It can -only be used with the option:--kernel domain option. +'GROUP' is either: + -'GROUP' can also be a group name. The group name resolution is -performed by the session daemon (see man:lttng-sessiond(8)) on addition -to the group ID inclusion set. +-- +* The real group ID (see man:getgid(3)) of a process as seen from the + root user namespace (see man:user_namespaces(7)). + +* A group name. ++ +The connected LTTng session daemon (see man:lttng-sessiond(8)) performs +the group name resolution on addition to the group ID inclusion set. +-- + -The 'GROUP' argument must be omitted when also using the option:--all -option. +Only available with option:--kernel option. -option:--vgid[='GROUP'[,'GROUP']...]:: - Track virtual group ID process attribute values 'GROUP'(add them to - the virtual group ID inclusion set). +option:--vgid[='VGROUP'[,'VGROUP']...]:: + For each 'VGROUP' argument, add 'VGROUP' to the virtual group ID + inclusion set of the selected tracing session and domain. + -'GROUP' is the real group ID (see man:getgid(3)) of a process as seen -from the _user namespace_ of the process (see man:user_namespaces(7)). +'VGROUP' is either: + -'GROUP' can also be a group name. The group name resolution is performed -by the session daemon (see man:lttng-sessiond(8)) on addition to the -virtual group ID inclusion set. +-- +* The real group ID (see man:getgid(3)) of a process as seen + from the user namespace (see man:user_namespaces(7)). + +* A group name. + -The 'GROUP' argument must be omitted when also using the option:--all -option. +The connected LTTng session daemon (see man:lttng-sessiond(8)) performs +the group name resolution on addition to the virtual group ID inclusion +set. +-- + + +Inclusion set operation +~~~~~~~~~~~~~~~~~~~~~~~ +option:-a, option:--all:: + With one or more empty option:--pid, option:--vpid, option:--uid, + option:--vuid, option:--gid, and option:--vgid options: add *all* + the possible values to the selected inclusion sets. include::common-cmd-help-options.txt[] @@ -259,5 +296,6 @@ include::common-cmd-footer.txt[] SEE ALSO -------- -man:lttng-untrack(1), -man:lttng(1) +man:lttng(1), +man:lttng-concepts(7), +man:lttng-untrack(1) diff --git a/doc/man/lttng-untrack.1.txt b/doc/man/lttng-untrack.1.txt index f1a872024..01e82b1b4 100644 --- a/doc/man/lttng-untrack.1.txt +++ b/doc/man/lttng-untrack.1.txt @@ -1,94 +1,95 @@ lttng-untrack(1) ================ -:revdate: 4 March 2020 +:revdate: 1 May 2021 NAME ---- -lttng-untrack - Remove one or more values from an LTTng process attribute tracker +lttng-untrack - Disallow specific processes to record LTTng events SYNOPSIS -------- -Remove specific process attribute values from a Linux kernel domain tracker: +Disallow specific processes to record Linux kernel events: [verse] -*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *untrack* option:--kernel +*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *untrack* option:--kernel [option:--session='SESSION'] (option:--pid=PID[,PID]... | option:--vpid=VPID[,VPID]... | - option:--uid=UID[,UID]... | option:--vuid=VUID[,VUID]... | - option:--gid=GID[,GID]... | option:--vgid=VGID[,VGID]... )... - -Remove all possible process attribute values from a Linux kernel domain tracker: + option:--uid=UID[,UID]... | option:--vuid=VUSER[,VUSER]... | + option:--gid=GID[,GID]... | option:--vgid=VGROUP[,VGROUP]...)... [verse] -*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *untrack* option:--kernel - option:--all (option:--pid | option:--vpid | option:--uid | - option:--vuid | option:--gid | option:--vgid )... +*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *untrack* option:--kernel [option:--session='SESSION'] + option:--all (option:--pid | option:--vpid | option:--uid | option:--vuid | option:--gid | option:--vgid)... -Remove specific process attribute values from a user space domain tracker: +Disallow specific processes to record user space events: [verse] -*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *untrack* option:--userspace - (option:--vpid=VPID[,VPID]... | option:--vuid=VUID[,VUID]... | option:--vgid=VGID[,VGID]...)... - -Remove all possible process attribute values from a user space domain tracker: +*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *untrack* option:--userspace [option:--session='SESSION'] + (option:--vpid=VPID[,VPID]... | option:--vuid=VUSER[,VUSER]... | + option:--vgid=VGROUP[,VGROUP]...)... [verse] -*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *untrack* option:--userspace +*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *untrack* option:--userspace [option:--session='SESSION'] option:--all (option:--vpid | option:--vgid | option:--vuid)... DESCRIPTION ----------- -The `lttng untrack` commands removes one or more values from a -process attribute tracker. +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'. -See man:lttng-track(1) to learn more about LTTng trackers. +Without the option:--session option:: + The current tracing session (see man:lttng-concepts(7) to learn more + about the current tracing session). -The untrack command removes specific process attribute values from a -tracker's inclusion set. The attributes to remove must have been -precedently added by man:lttng-track(1). It is also possible to remove -all the possible values of a process attribute from the inclusion set -using the option:--all option. +See man:lttng-concepts(7) to learn more about tracing sessions and +recording event rules. + +The `untrack` command removes values from _inclusion sets_ of process +attributes. See man:lttng-track(1) to learn more about inclusion sets. Example ~~~~~~~ -One common operation is to create a tracing session -(see man:lttng-create(1)), remove all the entries from the PID -tracker inclusion set, start tracing, and then manually track PIDs -while tracing is active. +A common operation is to create a tracing session (see +man:lttng-create(1)), remove all the entries from the PID tracker +inclusion set, start tracing, and then manually track PIDs while the +tracing session is active. Assume the maximum system PID is 7 for this example. -Command: - +. Command: ++ [role="term"] ---- $ lttng create ---- - ++ Initial inclusion set: - ++ ------------------------------- [0] [1] [2] [3] [4] [5] [6] [7] ------------------------------- -Command: - +. Command: ++ [role="term"] ---- $ lttng untrack --kernel --pid --all ---- - -inclusion set: - ++ +Inclusion set: ++ ------------------------------- [ ] [ ] [ ] [ ] [ ] [ ] [ ] [ ] ------------------------------- -Commands: - +. Commands: ++ [role="term"] ---- $ lttng enable-event --kernel ... @@ -96,22 +97,22 @@ $ lttng start $ # ... $ lttng track --kernel --pid=3,5 ---- - -inclusion set: - ++ +Inclusion set: ++ ------------------------------- [ ] [ ] [ ] [3] [ ] [5] [ ] [ ] ------------------------------- -Command: - +. Command: ++ [role="term"] ---- $ lttng track --kernel --pid=2 ---- - -inclusion set: - ++ +Inclusion set: ++ ------------------------------- [ ] [ ] [2] [3] [ ] [5] [ ] [ ] ------------------------------- @@ -120,106 +121,119 @@ inclusion set: include::common-cmd-options-head.txt[] -Domain -~~~~~~ +Tracing domain +~~~~~~~~~~~~~~ One of: option:-k, option:--kernel:: - Track process attributes in the Linux kernel domain. + Remove values from one or more Linux kernel inclusion sets. option:-u, option:--userspace:: - Track process attributes in the user space domain. + Remove values from one or more user space inclusion sets. -Target -~~~~~~ +Recording target +~~~~~~~~~~~~~~~~ option:-s 'SESSION', option:--session='SESSION':: - Untrack process attributes in the tracing session named 'SESSION' - instead of the current tracing session. + Remove values from one or more inclusion sets of the tracing session + named 'SESSION' instead of the current tracing session. -Untracking -~~~~~~~~~~ -option:-a, option:--all:: - Used in conjunction with a single, empty option:--pid, - option:--vpid, option:--uid, option:--vuid, option:--gid, - or option:--vgid option: untrack _all_ possible process attribute - values (remove all values from the inclusion set). - +Inclusion set selection +~~~~~~~~~~~~~~~~~~~~~~~ option:-p ['PID'[,'PID']...], option:--pid[='PID'[,'PID']...]:: - Untrack process ID values 'PID' (remove them from the process ID - inclusion set). + For each 'PID' argument, remove 'PID' from the process ID inclusion + set of the selected tracing session and domain. + -'PID' is the process ID attribute of a process as seen from the _root -PID namespace_ (see man:pid_namespaces(7)). It can only be used with -the option:--kernel domain option. +'PID' is the process ID attribute of a process as seen from the root +PID namespace (see man:pid_namespaces(7)). + -The 'PID' argument must be omitted when also using the option:--all -option. +Only available with option:--kernel option. option:--vpid[='VPID'[,'VPID']...]:: - Untrack virtual process ID values 'VPID' (remove them from the - virtual process ID inclusion set). + For each 'VPID' argument, remove 'VPID' from the virtual process ID + inclusion set of the selected tracing 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)). -+ -The 'VPID' argument must be omitted when also using the option:--all -option. +the PID namespace of the process (see man:pid_namespaces(7)). option:--uid[='USER'[,'USER']...]:: - Untrack user ID process attribute values 'USER' (remove them from - the user ID inclusion set). + For each 'USER' argument, remove 'USER' from the user ID inclusion + set of the selected tracing session and domain. ++ +'USER' is either: + -'USER' is the real user ID (see man:getuid(3)) of a process as seen -from the _root user namespace_ (see man:user_namespaces(7)). It can -only be used with the option:--kernel domain option. +-- +* The real user ID (see man:getuid(3)) of a process as seen + from the root user namespace (see man:user_namespaces(7)). + +* A user name. + -'USER' can also be a user name. No name resolution is performed; -'USER' will be matched against the names in the inclusion set. +The connected LTTng session daemon (see man:lttng-sessiond(8)) performs +the user name resolution on removal from the user ID inclusion set. +-- + -The 'USER' argument must be omitted when also using the option:--all -option. +Only available with option:--kernel option. -option:--vuid[='USER'[,'USER']...]:: - Untrack virtual user ID process attribute values 'USER' (remove - them from the virtual user ID inclusion set). +option:--vuid[='VUSER'[,'VUSER']...]:: + For each 'VUSER' argument, remove 'VUSER' from the virtual user ID + inclusion set of the selected tracing session and domain. + -'USER' is the real user ID (see man:getuid(3)) of a process as seen -from the _user namespace_ of the process (see man:user_namespaces(7)). +'VUSER' is either: + -'USER' can also be a user name. No name resolution is performed; -'USER' will be matched against the names in the inclusion set. +-- +* The real user ID (see man:getuid(3)) of a process as seen + from the user namespace (see man:user_namespaces(7)). + +* A user name. + -The 'USER' argument must be omitted when also using the option:--all -option. +The connected LTTng session daemon (see man:lttng-sessiond(8)) performs +the user name resolution on removal from the virtual user ID inclusion +set. +-- option:--gid[='GROUP'[,'GROUP']...]:: - Untrack group ID process attribute values 'GROUP' (remove them - from the group ID inclusion set). + For each 'GROUP' argument, remove 'GROUP' from the group ID + inclusion set of the selected tracing session and domain. ++ +'GROUP' is either: + -'GROUP' is the real group ID (see man:getgid(3)) of a process as seen -from the _root user namespace_ (see man:user_namespaces(7)). It can -only be used with the option:--kernel domain option. +-- +* The real group ID (see man:getgid(3)) of a process as seen from the + root user namespace (see man:user_namespaces(7)). + +* A group name. + -'GROUP' can also be a group name. No name resolution is performed; -'GROUP' will be matched against the names in the inclusion set. +The connected LTTng session daemon (see man:lttng-sessiond(8)) performs +the group name resolution on removal from the group ID inclusion set. +-- + -The 'GROUP' argument must be omitted when also using the option:--all -option. +Only available with option:--kernel option. -option:--vgid[='GROUP'[,'GROUP']...]:: - Untrack virtual group ID process attribute values 'GROUP'(remove - them from the virtual group ID inclusion set). +option:--vgid[='VGROUP'[,'VGROUP']...]:: + For each 'VGROUP' argument, remove 'VGROUP' from the virtual group + ID inclusion set of the selected tracing session and domain. + -'GROUP' is the real group ID (see man:getgid(3)) of a process as seen -from the _user namespace_ of the process (see man:user_namespaces(7)). +'VGROUP' is either: + -'GROUP' can also be a group name. No name resolution is performed; -'GROUP' will be matched against the names in the inclusion set. +-- +* The real group ID (see man:getgid(3)) of a process as seen + from the user namespace (see man:user_namespaces(7)). + +* A group name. + -The 'GROUP' argument must be omitted when also using the option:--all -option. +The connected LTTng session daemon (see man:lttng-sessiond(8)) performs +the group name resolution on removal from the virtual group ID inclusion +set. +-- + + +Inclusion set operation +~~~~~~~~~~~~~~~~~~~~~~~ +option:-a, option:--all:: + With one or more empty option:--pid, option:--vpid, option:--uid, + option:--vuid, option:--gid, and option:--vgid options: clear the + selected inclusion sets. include::common-cmd-help-options.txt[] @@ -230,5 +244,6 @@ include::common-cmd-footer.txt[] SEE ALSO -------- -man:lttng-track(1), -man:lttng(1) +man:lttng(1), +man:lttng-concepts(7), +man:lttng-track(1) diff --git a/doc/man/lttng-view.1.txt b/doc/man/lttng-view.1.txt index 6874aad3c..afb39fe0a 100644 --- a/doc/man/lttng-view.1.txt +++ b/doc/man/lttng-view.1.txt @@ -1,6 +1,6 @@ lttng-view(1) ============= -:revdate: 21 April 2021 +:revdate: 29 April 2021 NAME @@ -27,9 +27,8 @@ With the option:--trace-path='DIR' option:: The local file system directory 'DIR'. Otherwise:: - The current tracing session (see man:lttng-create(1) and - man:lttng-set-session(1) to learn more about the current tracing - session). + The current tracing session (see man:concepts(1) to learn more about + the current tracing session). With the option:--session option or without the option:--trace-path option, the mode of the selected tracing session may :not: be network diff --git a/doc/man/lttng.1.txt b/doc/man/lttng.1.txt index 06f3a362a..1b5d5ee31 100644 --- a/doc/man/lttng.1.txt +++ b/doc/man/lttng.1.txt @@ -1,17 +1,17 @@ lttng(1) ======== -:revdate: 16 October 2019 +:revdate: 3 May 2021 NAME ---- -lttng - LTTng 2 tracer control command-line tool +lttng - Control LTTng tracing SYNOPSIS -------- [verse] -*lttng* [option:--group='GROUP'] [option:--mi=xml] [option:--no-sessiond | option:--sessiond-path='PATH'] +*lttng* [option:--group='GROUP'] [option:--mi=**xml**] [option:--no-sessiond | option:--sessiond-path='PATH'] [option:--quiet | option:-verbose...] '<>' ['COMMAND OPTIONS'] @@ -24,7 +24,7 @@ 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-create(1) to learn more +* Manages tracing sessions (see man:lttng-concepts(7) to learn more about tracing sessions). * Controls the various components (like tracers and consumer daemons) of @@ -41,6 +41,12 @@ daemon with the option:--no-sessiond option. NOTE: The LTTng project recommends that you start the session daemon at boot time for stable and long-term tracing. +See man:lttng-concepts(7) to learn more about the foundational concepts +of LTTng. + +The `lttng` tool offers a subcommand-based command-line interface. The +<> section below lists the available commands. + Session daemon connection ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -80,9 +86,9 @@ Without the nloption:--group option of the root session daemon:: `tracing` LTTng-instrumented user applications automatically register to both the -root session daemon and the user session daemon. This makes it possible -for both session daemons to list the available traceable applications -and known instrumentation points (see man:lttng-list(1)). +root and user session daemons. This makes it possible for both session +daemons to list the available instrumented applications and their +instrumentation points (see man:lttng-list(1)). OPTIONS @@ -244,6 +250,6 @@ include::common-cmd-footer.txt[] SEE ALSO -------- -man:babeltrace2(1), +man:lttng-concepts(7) man:lttng-relayd(8), man:lttng-sessiond(8)