From 484b2a0cbefcf0c7072622a5a411ea5ed849da28 Mon Sep 17 00:00:00 2001 From: Philippe Proulx Date: Wed, 3 Mar 2021 15:18:30 -0500 Subject: [PATCH] Update some manual pages for LTTng-tools 2.13 MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit This patch updates some manual pages for LTTng-tools 2.13. A few pages still remain to be updated, a task which is reserved for a subsequent patch. This patch: * Improves the consistency of the the command descriptions in `configure.ac`. * Adds `common-help-option.txt` which is the description of any `--help` option. * Adds `common-intro.txt` which is a common description introduction for the top-level manual pages. * Adds `lttng-event-rule.7.txt` which describes the common way to specify an event rule on the command-line. lttng-event-rule(7) has a "Migration from a recording event rule specification" section with a table which shows the relationship between lttng-enable-event(1) command-line arguments and lttng-event-rule(7) options. As of this patch, only `lttng-add-trigger.1.txt` references it, for the `event-rule-matches` trigger condition. `Makefile.am` is also updated to build and include manual pages of section 7. * 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. More specifically: lttng-add-context(1): Specify that this command adds context fields to be recorded to the event records of one or more channels. In other words, this is a recording-related command. You don't need to use it to access context fields with the filter expression of an event rule, for example. lttng-add-trigger(1): * Update the "NAME" section. * Add internal option links where missing. * Improve the description. Add links to the lttng-remove-trigger(1) and lttng-list-triggers(1) manual pages and explain what those commands are used for. Use "condition specifier" and "action specifier" terms to describe those groups of options. For condition and action specifiers, use localized synopses. For action specifiers, add links to the corresponding LTTng command manual pages. * Document the `--owner-id` option. * Group option descriptions. * Use "name" instead of "ID". * Refer to the new lttng-event-rule(7) manual page. * Remove the "no context field" limitation for `ERSPEC`. * Fix verse blocks nested in lists. lttng-create(1): * Add more documentation about tracing sessions. * Specify that the `create` command can spawn a session daemon. * Add the "Current tracing session" section to explain this concept and where it applies. * Clarify the "URL format" section. lttng-disable-event(1): Explain how this command can only find recording event rules to disable by instrumentation point type and event name condition. lttng-enable-event(1): I more or less completely rewrote this page. The document now clearly explains the related core concepts, shows the explicit and implicit conditions of a recording event rule, has one section for each condition explaining how an event can satisfy it, and more. The synopsis is more accurate. I added an "Event record name" section to indicate what's the name of a matched event depending on the instrumentation point type and some command-line arguments. I also added an "Enable a disabled recording event rule" section to explain how the `enable-event` command enables existing, disabled events. This manual page now documents all the options, even if they're the default, as defaults may change in the future. The new lttng-event-rule(7) manual page is based on this one, but with its own ways to specify event rule conditions. lttng-remove-trigger(1): * Use "name" instead of "ID". * Use `--owner-id` instead of `--user-id`. lttng-sessiond(8): * Explain what an LTTng session daemon does. * Clarify everything related to the tracing group and root session daemon. * Add a "Daemon configuration" section which explains the INI configuration files and the `--config` option. * Make the "Tracing session configuration loading" section (renamed) much more straightforward, with less text. * Specify that the `--daemonize` and `--background` options make `lttng-sessiond` only exit when the daemon is ready to receive client commands. lttng-set-session(1): List which commands rely on the current tracing session concept. lttng(1): * Add a "Session daemon connection" section which shows how the `lttng` tool (or any LTTng tracing control application) connects to a session daemon (user-specific vs. root session daemon). * Use tables to list the available commands. Signed-off-by: Philippe Proulx Signed-off-by: Jérémie Galarneau Change-Id: I6b98f4907d94763f3bfcb6576e4add9cfc59a2e3 --- .gitignore | 1 + configure.ac | 45 +- doc/man/Makefile.am | 28 +- doc/man/asciidoc-attrs.conf.in | 3 + doc/man/common-cmd-footer.txt | 67 +- doc/man/common-cmd-help-options.txt | 10 +- doc/man/common-cmd-options-head.txt | 2 +- doc/man/common-help-option.txt | 9 + doc/man/common-intro.txt | 6 + doc/man/lttng-add-context.1.txt | 163 ++-- doc/man/lttng-add-trigger.1.txt | 387 +++++---- doc/man/lttng-clear.1.txt | 55 +- doc/man/lttng-crash.1.txt | 57 +- doc/man/lttng-create.1.txt | 409 ++++++---- doc/man/lttng-destroy.1.txt | 81 +- doc/man/lttng-disable-channel.1.txt | 36 +- doc/man/lttng-disable-event.1.txt | 142 ++-- doc/man/lttng-disable-rotation.1.txt | 26 +- doc/man/lttng-enable-channel.1.txt | 4 +- doc/man/lttng-enable-event.1.txt | 1077 +++++++++++++++++--------- doc/man/lttng-enable-rotation.1.txt | 139 ++-- doc/man/lttng-event-rule.7.txt | 808 +++++++++++++++++++ doc/man/lttng-help.1.txt | 29 +- doc/man/lttng-list-triggers.1.txt | 9 +- doc/man/lttng-list.1.txt | 10 +- doc/man/lttng-load.1.txt | 4 +- doc/man/lttng-relayd.8.txt | 4 +- doc/man/lttng-remove-trigger.1.txt | 30 +- doc/man/lttng-save.1.txt | 6 +- doc/man/lttng-sessiond.8.txt | 411 ++++++---- doc/man/lttng-set-session.1.txt | 43 +- doc/man/lttng-start.1.txt | 46 +- doc/man/lttng-status.1.txt | 24 +- doc/man/lttng-stop.1.txt | 85 +- doc/man/lttng-track.1.txt | 6 +- doc/man/lttng-version.1.txt | 18 +- doc/man/lttng-view.1.txt | 58 +- doc/man/lttng.1.txt | 322 ++++---- src/bin/lttng/commands/list.c | 2 +- src/bin/lttng/lttng.c | 7 +- 40 files changed, 3164 insertions(+), 1505 deletions(-) create mode 100644 doc/man/common-help-option.txt create mode 100644 doc/man/common-intro.txt create mode 100644 doc/man/lttng-event-rule.7.txt diff --git a/.gitignore b/.gitignore index 972f00fb5..cbd57ea72 100644 --- a/.gitignore +++ b/.gitignore @@ -161,6 +161,7 @@ compile_commands.json # man pages /doc/man/*.1 /doc/man/*.3 +/doc/man/*.7 /doc/man/*.8 /doc/man/*.xml /doc/man/*.html diff --git a/configure.ac b/configure.ac index 65fc8a6d6..f67312d0b 100644 --- a/configure.ac +++ b/configure.ac @@ -426,33 +426,34 @@ _AC_DEFINE_AND_SUBST([DEFAULT_ROTATE_PENDING_TIMER], [500000]) _AC_DEFINE_AND_SUBST([DEFAULT_EVENT_NOTIFIER_ERROR_COUNT_MAP_SIZE], [4096]) # Command short descriptions -_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_ADD_CONTEXT], [Add context fields to a channel]) -_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_CREATE], [Create a tracing session]) +_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_ADD_CONTEXT], [Add context fields to be recorded]) +_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_ADD_TRIGGER], [Add a trigger]) _AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_CLEAR], [Clear a tracing session]) -_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_DESTROY], [Tear down tracing sessions]) -_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_DISABLE_CHANNEL], [Disable tracing channels]) -_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_DISABLE_EVENT], [Disable event rules]) +_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_ENABLE_CHANNEL], [Create or enable tracing channels]) -_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_ENABLE_EVENT], [Create or enable event rules]) +_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_HELP], [Display help information about a command]) -_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_LIST], [List tracing sessions, domains, channels, and events]) +_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_TRIGGERS], [List triggers]) _AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_LOAD], [Load tracing session configurations]) -_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_REGENERATE], [Manage an LTTng tracing session's data regeneration]) -_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_ROTATE], [Archive a tracing session's current trace chunk]) +_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_REGENERATE], [Regenerate specific tracing session data]) +_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_REMOVE_TRIGGER], [Remove a trigger]) +_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_ROTATE], [Archive the current trace chunk of a tracing session]) _AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_SAVE], [Save tracing session configurations]) -_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_SET_SESSION], [Set current tracing session]) -_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_SNAPSHOT], [Snapshot buffers of current tracing session]) -_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_START], [Start tracing]) -_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_STATUS], [Get the status of the current tracing session]) -_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_STOP], [Stop tracing]) -_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_DISABLE_ROTATION], [Unset a rotation schedule]) -_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_ENABLE_ROTATION], [Set a rotation schedule]) -_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_TRACK], [Track specific system resources]) -_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_UNTRACK], [Untrack specific system resources]) -_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_VERSION], [Show version information]) -_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_VIEW], [Start trace viewer]) +_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_SET_SESSION], [Set the current tracing session]) +_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_SNAPSHOT], [Take a tracing session snapshot]) +_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_START], [Start a tracing session]) +_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_STATUS], [Show the status of the current tracing session]) +_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_STOP], [Stop a tracing session]) +_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_TRACK], [Track process attrbutes]) +_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_UNTRACK], [Untrack process attributes]) +_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]) if test "x$prefix" = "xNONE"; then prefix=$ac_default_prefix diff --git a/doc/man/Makefile.am b/doc/man/Makefile.am index 5ae6ffbe3..869494db9 100644 --- a/doc/man/Makefile.am +++ b/doc/man/Makefile.am @@ -40,18 +40,20 @@ MAN1_NAMES = \ lttng-add-trigger \ lttng-remove-trigger \ lttng-list-triggers - MAN3_NAMES = +MAN7_NAMES = lttng-event-rule MAN8_NAMES = lttng-sessiond lttng-relayd MAN1_NO_ASCIIDOC_NAMES = MAN3_NO_ASCIIDOC_NAMES = lttng-health-check +MAN7_NO_ASCIIDOC_NAMES = MAN8_NO_ASCIIDOC_NAMES = # AsciiDoc sources and outputs MAN1_TXT = $(call manaddsuffix,.1.txt,$(MAN1_NAMES)) MAN3_TXT = $(call manaddsuffix,.3.txt,$(MAN3_NAMES)) +MAN7_TXT = $(call manaddsuffix,.7.txt,$(MAN7_NAMES)) MAN8_TXT = $(call manaddsuffix,.8.txt,$(MAN8_NAMES)) -MAN_TXT = $(MAN1_TXT) $(MAN3_TXT) $(MAN8_TXT) +MAN_TXT = $(MAN1_TXT) $(MAN3_TXT) $(MAN7_TXT) $(MAN8_TXT) MAN_XML = $(patsubst $(srcdir)/%.txt,%.xml,$(MAN_TXT)) # common AsciiDoc source files @@ -59,7 +61,9 @@ COMMON_TXT = \ $(srcdir)/common-footer.txt \ $(srcdir)/common-cmd-footer.txt \ $(srcdir)/common-cmd-options-head.txt \ - $(srcdir)/common-cmd-help-options.txt + $(srcdir)/common-cmd-help-options.txt \ + $(srcdir)/common-help-option.txt \ + $(srcdir)/common-intro.txt # config ASCIIDOC_CONF = $(srcdir)/asciidoc.conf @@ -72,11 +76,13 @@ COMMON_DEPS = $(ASCIIDOC_CONF) $(COMMON_TXT) # man pages destinations MAN1 = $(addsuffix .1,$(MAN1_NAMES)) MAN3 = $(addsuffix .3,$(MAN3_NAMES)) +MAN7 = $(addsuffix .7,$(MAN7_NAMES)) MAN8 = $(addsuffix .8,$(MAN8_NAMES)) MAN1_NO_ASCIIDOC = $(addsuffix .1,$(MAN1_NO_ASCIIDOC_NAMES)) MAN3_NO_ASCIIDOC = $(addsuffix .3,$(MAN3_NO_ASCIIDOC_NAMES)) +MAN7_NO_ASCIIDOC = $(addsuffix .7,$(MAN7_NO_ASCIIDOC_NAMES)) MAN8_NO_ASCIIDOC = $(addsuffix .8,$(MAN8_NO_ASCIIDOC_NAMES)) -MAN = $(MAN1) $(MAN3) $(MAN8) +MAN = $(MAN1) $(MAN3) $(MAN7) $(MAN8) # initially empty CLEANFILES = @@ -146,6 +152,12 @@ COMMON_DEPS += $(ASCIIDOC_ATTRS_CONF) %.3: %.3.xml $(XSL_FILE) $(XTO) $< 2>/dev/null +%.7.xml: $(srcdir)/%.7.txt $(COMMON_DEPS) + $(ADOC_DOCBOOK) -o $@ $< + +%.7: %.7.xml $(XSL_FILE) + $(XTO) $< 2>/dev/null + %.8.xml: $(srcdir)/%.8.txt $(COMMON_DEPS) $(ADOC_DOCBOOK) -o $@ $< @@ -168,6 +180,10 @@ ERR_MSG += "Make sure both tools are installed and run the configure script agai @echo $(ERR_MSG) @false +%.7: $(srcdir)/%.7.txt $(COMMON_DEPS) + @echo $(ERR_MSG) + @false + %.8: $(srcdir)/%.8.txt $(COMMON_DEPS) @echo $(ERR_MSG) @false @@ -177,12 +193,14 @@ endif # MAN_PAGES_OPT # those are always installed since they are directly written in troff dist_man1_MANS = $(MAN1_NO_ASCIIDOC) dist_man3_MANS = $(MAN3_NO_ASCIIDOC) +dist_man7_MANS = $(MAN7_NO_ASCIIDOC) dist_man8_MANS = $(MAN8_NO_ASCIIDOC) if MAN_PAGES_OPT # building man pages: we can install and distribute them dist_man1_MANS += $(MAN1) dist_man3_MANS += $(MAN3) +dist_man7_MANS += $(MAN7) dist_man8_MANS += $(MAN8) endif # MAN_PAGES_OPT @@ -197,4 +215,4 @@ EXTRA_DIST = $(MAN_TXT) $(COMMON_TXT) $(XSL_FILE) \ $(ASCIIDOC_CONF) $(ASCIIDOC_ATTRS_CONF).in # keep generated man pages that can be considered intermediate files -.PRECIOUS: %.1 %.3 %.8 +.PRECIOUS: %.1 %.3 %.7 %.8 diff --git a/doc/man/asciidoc-attrs.conf.in b/doc/man/asciidoc-attrs.conf.in index e541c0c1c..0ea985a39 100644 --- a/doc/man/asciidoc-attrs.conf.in +++ b/doc/man/asciidoc-attrs.conf.in @@ -44,6 +44,7 @@ system_lttng_conf="@CONFDIR@/lttng/lttng.conf" # command short descriptions cmd_descr_add_context="@CMD_DESCR_ADD_CONTEXT@" +cmd_descr_add_trigger="@CMD_DESCR_ADD_TRIGGER@" cmd_descr_create="@CMD_DESCR_CREATE@" cmd_descr_destroy="@CMD_DESCR_DESTROY@" cmd_descr_disable_channel="@CMD_DESCR_DISABLE_CHANNEL@" @@ -54,8 +55,10 @@ cmd_descr_enable_event="@CMD_DESCR_ENABLE_EVENT@" cmd_descr_enable_rotation="@CMD_DESCR_ENABLE_ROTATION@" cmd_descr_help="@CMD_DESCR_HELP@" cmd_descr_list="@CMD_DESCR_LIST@" +cmd_descr_list_triggers="@CMD_DESCR_LIST_TRIGGERS@" cmd_descr_load="@CMD_DESCR_LOAD@" cmd_descr_regenerate="@CMD_DESCR_REGENERATE@" +cmd_descr_remove_trigger="@CMD_DESCR_REMOVE_TRIGGER@" cmd_descr_rotate="@CMD_DESCR_ROTATE@" cmd_descr_save="@CMD_DESCR_SAVE@" cmd_descr_set_session="@CMD_DESCR_SET_SESSION@" diff --git a/doc/man/common-cmd-footer.txt b/doc/man/common-cmd-footer.txt index 6d16c0351..dbeab32d6 100644 --- a/doc/man/common-cmd-footer.txt +++ b/doc/man/common-cmd-footer.txt @@ -1,60 +1,67 @@ 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_HOME`:: - Overrides the `$HOME` environment variable. Useful when the user - running the commands has a non-writable home directory. + Path to the LTTng home directory. ++ +Defaults to `$HOME`. ++ +Useful when the Unix user running the commands has a non-writable home +directory. `LTTNG_MAN_BIN_PATH`:: - Absolute path to the man pager to use for viewing help information - about LTTng commands (using man:lttng-help(1) or - `lttng COMMAND --help`). + Absolute path to the manual pager to use to read the LTTng + command-line help (with man:lttng-help(1) or with the + nloption:--help option) instead of `/usr/bin/man`. `LTTNG_SESSION_CONFIG_XSD_PATH`:: - Path in which the `session.xsd` session configuration XML - schema may be found. + Path to the directory containing the `session.xsd` tracing session + configuration XML schema. `LTTNG_SESSIOND_PATH`:: - Full session daemon binary path. + Absolute path to the LTTng session daemon (see + man:lttng-sessiond(8)) binary. + -The genoption:--sessiond-path option has precedence over this -environment variable. - -Note that the man:lttng-create(1) command can spawn an LTTng -session daemon automatically if none is running. See -man:lttng-sessiond(8) for the environment variables influencing -the execution of the session daemon. +The genoption:--sessiond-path general option overrides this environment +variable. ++ +NOTE: The man:lttng-create(1) command can spawn an LTTng session daemon +automatically if none is running. See man:lttng-sessiond(8) for the +environment variables affecting the execution of the session daemon. FILES ----- `$LTTNG_HOME/.lttngrc`:: - User LTTng runtime configuration. + Unix user's LTTng runtime configuration. + -This is where the per-user current tracing session is stored between -executions of man:lttng(1). The current tracing session can be set -with man:lttng-set-session(1). See man:lttng-create(1) for -more information about tracing sessions. +This is where LTTng stores the name of the Unix user's current tracing +session between executions of man:lttng(1). man:lttng-create(1) and +man:lttng-set-session(1) set the current tracing session. `$LTTNG_HOME/lttng-traces`:: - Default output directory of LTTng traces. This can be overridden - with the nloption:--output option of the man:lttng-create(1) - command. + Default output directory of LTTng traces in local and snapshot + modes. ++ +Override this path with the nloption:--output option of the +man:lttng-create(1) command. `$LTTNG_HOME/.lttng`:: - User LTTng runtime and configuration directory. + Unix user's LTTng runtime and configuration directory. `$LTTNG_HOME/.lttng/sessions`:: - Default location of saved user tracing sessions (see - man:lttng-save(1) and man:lttng-load(1)). + Default directory containing the Unix user's saved tracing session + configurations (see man:lttng-save(1) and man:lttng-load(1)). +{system_sessions_dir}+:: - System-wide location of saved tracing sessions - (see man:lttng-save(1) and man:lttng-load(1)). + Directory containing the system-wide saved tracing session + configurations (see man:lttng-save(1) and man:lttng-load(1)). -NOTE: `$LTTNG_HOME` defaults to `$HOME` when not explicitly set. +NOTE: `$LTTNG_HOME` defaults to the value of the `HOME` environment +variable. EXIT STATUS diff --git a/doc/man/common-cmd-help-options.txt b/doc/man/common-cmd-help-options.txt index 2e5bcf928..0e85fdc64 100644 --- a/doc/man/common-cmd-help-options.txt +++ b/doc/man/common-cmd-help-options.txt @@ -1,11 +1,3 @@ Program information ~~~~~~~~~~~~~~~~~~~ -option:-h, option:--help:: - Show command help. -+ -This option, like man:lttng-help(1), attempts to launch -`/usr/bin/man` to view the command's man page. The path to the man pager -can be overridden by the `LTTNG_MAN_BIN_PATH` environment variable. - -option:--list-options:: - List available command options. +include::common-help-option.txt[] diff --git a/doc/man/common-cmd-options-head.txt b/doc/man/common-cmd-options-head.txt index 362995ecb..c910e7137 100644 --- a/doc/man/common-cmd-options-head.txt +++ b/doc/man/common-cmd-options-head.txt @@ -1,3 +1,3 @@ OPTIONS ------- -linkgenoptions:(General options) are described in man:lttng(1). +See man:lttng(1) for 'linkgenoptions:(GENERAL OPTIONS)'. diff --git a/doc/man/common-help-option.txt b/doc/man/common-help-option.txt new file mode 100644 index 000000000..1797d985f --- /dev/null +++ b/doc/man/common-help-option.txt @@ -0,0 +1,9 @@ +option:-h, option:--help:: + Show help. ++ +This option attempts to launch `/usr/bin/man` to view this manual page. +Override the manual pager path with the `LTTNG_MAN_BIN_PATH` environment +variable. + +option:--list-options:: + List available command options and quit. diff --git a/doc/man/common-intro.txt b/doc/man/common-intro.txt new file mode 100644 index 000000000..018e69d18 --- /dev/null +++ b/doc/man/common-intro.txt @@ -0,0 +1,6 @@ +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. + +LTTng consists of Linux kernel modules (for Linux kernel tracing) and +dynamically loaded libraries (for user application and library tracing). diff --git a/doc/man/lttng-add-context.1.txt b/doc/man/lttng-add-context.1.txt index 640da1db1..512bdf154 100644 --- a/doc/man/lttng-add-context.1.txt +++ b/doc/man/lttng-add-context.1.txt @@ -1,16 +1,17 @@ lttng-add-context(1) ==================== -:revdate: 5 Februrary 2018 +:revdate: 8 April 2021 NAME ---- -lttng-add-context - Add context fields to an LTTng channel +lttng-add-context - Add context fields to be recorded by LTTng SYNOPSIS -------- -Add context fields to a channel: +Add context fields to be recorded to the LTTng event records of +one or more channels: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *add-context* @@ -18,7 +19,7 @@ Add context fields to a channel: [option:--session='SESSION'] [option:--channel='CHANNEL'] option:--type='TYPE' [option:--type='TYPE']... -List the available context fields: +List the available context field types: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *add-context* option:--list @@ -26,116 +27,138 @@ List the available context fields: DESCRIPTION ----------- -The `lttng add-context` command adds one or more context fields to a -channel. - -Channels are created with the man:lttng-enable-channel(1) command. - -When context fields are added to a channel, all the events emitted -within this channel contain the dynamic values of those context fields. - -If the option:--session option is omitted, the current tracing session -is used. If the option:--channel option is omitted, the context fields -are added to all the selected tracing session's channels. - -Many context fields can be added to a channel at once by repeating the -option:--type option. - -perf counters are available as per-CPU (`perf:cpu:` prefix) as well as -per-thread (`perf:thread:` prefix) counters. Currently, per-CPU counters -can only be used in the Linux kernel tracing domain, while per-thread -counters can only be used in the user space tracing domain. - -It is also possible to enable PMU counters by raw ID using the -`perf:cpu:raw:rN:NAME` (Linux kernel tracing domain) or -`perf:thread:raw:rN:NAME` (user space tracing domain), with: - -`N`:: - A hexadecimal event descriptor which is the same format as used - by man:perf-record(1): a concatenation of the event number and umask - value provided by the processor's manufacturer. The possible values - for this field are processor-specific. - -`NAME`:: +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. + +See man:lttng-enable-channel(1) to learn more about LTTng channels. + +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. + +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). + +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. + +perf counter context fields are available: + +Per-CPU:: + Prefix: `perf:cpu:`. ++ +Only available for Linux kernel (option:--kernel option) channels. + +Per-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: + +'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. + +'NAME':: Custom name to easily recognize the counter. -Application-specific context fields can be added to a channel using the -following syntax: +Add an application-specific context field with the following syntax: [verse] $app.'PROVIDER':__TYPE__ -with: - 'PROVIDER':: Provider name. 'TYPE':: Context type name. -NOTE: Make sure to **single-quote** the type when running the command -from a shell, as `$` is a special character for variable substitution in -most shells. +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. -Use the option:--list option without other arguments to list the -available context field names. +List the available context field types with the option:--list option and +without other arguments. + +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. -See the <> section below for a list of -limitations to consider. include::common-cmd-options-head.txt[] -Domain -~~~~~~ +Tracing domain +~~~~~~~~~~~~~~ One of: option:-j, option:--jul:: - Add context to channel in the `java.util.logging` (JUL) domain. + Add context fields to be recorded to the event records of one or + more channels of the `java.util.logging` (JUL) tracing domain. option:-k, option:--kernel:: - Add context to channel in the Linux kernel domain. + Add context fields to be recorded to the event records of one or + more channels of the Linux kernel tracing domain. option:-l, option:--log4j:: - Add context to channel in the Apache log4j domain. + Add context fields to be recorded to the event records of one or + more channels of the Apache log4j tracing domain. option:-u, option:--userspace:: - Add context to channel in the user space domain. + Add context fields to be recorded to the event records of one or + more channels of the user space tracing domain. -Target -~~~~~~ +Recording target +~~~~~~~~~~~~~~~~ option:-c 'CHANNEL', option:--channel='CHANNEL':: - Add context fields to a channel named 'CHANNEL' instead of adding - them to all the channels. + Add context fields to be recorded to the event records of a channel + named 'CHANNEL' instead of all the channels of the selected + tracing session. option:-s 'SESSION', option:--session='SESSION':: - Add context fields to a channel in the tracing session named 'SESSION' - instead of the current tracing session. + Add context fields to be recorded to the event records of one or + more channels of the tracing session named 'SESSION' instead of the + current tracing session. -Context -~~~~~~~ +Context field type +~~~~~~~~~~~~~~~~~~ option:--list:: - List the available context fields. Use this option alone. + List the available context field types. ++ +You may :not: use this option with the option:--channel, +option:--session, or option:--type options. option:-t 'TYPE', option:--type='TYPE':: - Add context field named 'TYPE'. This option can be repeated as - many times as needed on the command-line. + Add a context field having the type 'TYPE' to be recorded. ++ +Repeat this option to add more than one context field. include::common-cmd-help-options.txt[] -[[limitations]] -LIMITATIONS ------------ -As of this version of LTTng, it is not possible to add context fields to -a channel once its tracing session has been started (see man:lttng-start(1)) -at least once. include::common-cmd-footer.txt[] SEE ALSO -------- -man:lttng(1) +man:lttng(1), +man:lttng-enable-channel(1), +man:lttng-set-session(1) diff --git a/doc/man/lttng-add-trigger.1.txt b/doc/man/lttng-add-trigger.1.txt index 581dd1313..e183b8c3b 100644 --- a/doc/man/lttng-add-trigger.1.txt +++ b/doc/man/lttng-add-trigger.1.txt @@ -1,193 +1,310 @@ lttng-add-trigger(1) -===================== -:revdate: 27 May 2020 +==================== +:revdate: 23 April 2021 NAME ---- -lttng-add-trigger - Create LTTng triggers +lttng-add-trigger - Add an LTTng trigger SYNOPSIS -------- - [verse] -*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *add-trigger* [--id ID] - --condition CONDITION-NAME CONDITION-ARGS - --action ACTION-NAME ACTION-ARGS - [--action ACTION-NAME ACTION-ARGS]... - +*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *add-trigger* [option:--name='NAME'] [option:--owner-id='UID'] + option:--condition='CONDTYPE' ['CONDARGS'] + option:--action='ACTTYPE' ['ACTARGS'] [option:--action='ACTTYPE' ['ACTARGS']]... DESCRIPTION ----------- +The `lttng add-trigger` command creates and adds an LTTng _trigger_ to +the 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. -The `lttng add-trigger` command is used to create triggers. A -trigger is an association between a *condition* and one or more -*actions*. When the condition associated to a trigger is met, the -actions associated to that trigger are executed. The tracing does not -have to be active for the conditions to be met, and triggers are -independent from tracing sessions. +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. -The syntax by which conditions and actions are specified is described -below. +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 +option:--owner-id option. -[[conditions]] -Conditions -~~~~~~~~~~ +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. -Conditions are specified with the `--condition` option, followed by a -condition name, and possibly some more arguments, depending on the -specific condition. There must be exactly one condition given in the -`lttng add-trigger` invocation. +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. -The available conditions are: +Remove an existing trigger with the man:lttng-remove-trigger(1) command. -Event rule: `event-rule-matches [event rule arguments]`:: - This type of condition is met when the tracer encounters an event - matching the given event rule. The arguments describing the event - rule are the same as those describing the event rules of the - man:lttng-enable-event(1) command, with these exceptions: - - It is not possible to use filter operands that use values from - the context. +[[cond-spec]] +Condition specifier +~~~~~~~~~~~~~~~~~~~ +Synopsis: + +[verse] +option:--condition='CONDTYPE' ['CONDARGS'] +A condition specifier is the option:--condition option, which specifies +the type of condition 'CONDTYPE', followed, depending on 'CONDTYPE', +with zero or more arguments 'CONDARGS'. + +The available condition types are: + +[[er-matches-cond-spec]]`event-rule-matches`:: + Synopsis: ++ +[verse] +option:--condition=event-rule-matches [nloption:--capture='CDESCR']... 'ERSPEC' +{nbsp} + -Fields to capture can be specified with the option:--capture option, followed by -a capture expression. Zero or more captures can be configured. See the -<> section below for more information. +An `event-rule-matches` condition is considered satisfied when the event +rule specified with 'ERSPEC' matches an event. ++ +See man:lttng-event-rule(7) to learn how to specify an event rule +('ERSPEC' part). ++ +Capture event record and context fields with one or more +nloption:--capture options (see the <> +section below to learn more). When an `event-rule-matches` condition +with capture descriptors is satisfied, the captured field values are +available in the evaluation object of the condition using the +liblttng-ctl C{nbsp}API. ++ +IMPORTANT: Make sure to **single-quote** 'CDESCR' when you run the +`add-trigger` command from a shell, as capture descriptors can include +characters having a special meaning for most shells. -[[actions]] -Actions -~~~~~~~ -Actions are specified with the `--action` option, followed by an action -name, and possibly some more arguments, depending on the specific -action. There must be at least one action given in the -`lttng add-trigger` invocation. +[[capture-descr]] +Capture descriptor +~~~~~~~~~~~~~~~~~~ +A capture descriptor is a textual expression which describes how to read +an event record or context field. -The available actions are: +The argument of a nloption:--capture option, when using an +<> +(`event-rule-matches`), is a capture descriptor. -Notify: *notify*:: - This action causes the LTTng session daemon to send a notification, - through its notification mechanism (see man:lttng-sessiond(8)). - Some details about the condition evaluation are sent along with the - notification. +A capture descriptor expression is one of: -Start session: *start-session* session-name:: - This action causes the LTTng session daemon to start tracing for the - session with the given name. If no session with the given name exist - at the time the condition is met, nothing is done. +'NAME':: + An event record field named 'NAME'. ++ +The supported event record field types are: ++ +-- +* Integer +* Enumeration (integral value) +* Floating point number +* Static array of integers +* Dynamic array (``sequence'') of integers +* Text string +-- ++ +Examples: `my_field`, `target_cpu`, `ip`. -Stop session: *stop-session* session-name:: - This action causes the LTTng session daemon to stop tracing for the - session with the given name. If no session with the given name exist - at the time the condition is met, nothing is done. +++$ctx.++__NAME__:: + A statically-known context field named 'NAME'. ++ +List the available statically-known context field names with +man:lttng-add-context(1). ++ +Examples: `$ctx.prio`, `$ctx.preemptible`, +`$ctx.perf:cpu:stalled-cycles-frontend`. + +++$app.++__PROVIDER__++.++__NAME__:: + An application-specific context field named 'NAME' from the + provider 'PROVIDER'. ++ +See man:lttng-add-context(1) to learn more about application-specific +context fields. ++ +Example: `$app.server:cur_user`. -Rotate session: *rotate-session* session-name:: - This action causes the LTTng session daemon to rotate the session - with the given name. See man:lttng-rotate(1) for more information - about the session rotation concept. If no session with the given - name exist at the time the condition is met, nothing is done. +__EXPR__++[++__INDEX__++]++:: + The element at index 'INDEX' of the array field (static or dynamic) + identified by the expression 'EXPR'. ++ +'INDEX' must be a constant, positive integral value. ++ +Examples: `ip[3]`, `user_ids[15]`. -Snapshot session: *snapshot-session* session-name:: - This action causes the LTTng session daemon to take a snapshot of the - session with the given name. See man:lttng-snapshot(1) for more - information about the session snapshot concept. If no session with - the given name exist at the time the condition is met, nothing is - done. +If, when an event rule matches, a given capture descriptor doesn't +identify an existing event or context field, then the captured value is +reported as being unavailable. This applies to: +* A nonexistent event record field name. +* A nonexistent statically-known context field name. +* A nonexistent application-specific context field name. +* An out-of-bounds array field index. -[[capture-expr]] -Capture expression -~~~~~~~~~~~~~~~~~~ -A capture expression can be specified with the option:--capture option when -creating a new event-rule-matches condition. If the capture expression -corresponds with an event's field when tracing, the runtime dynamic value -corresponding to the capture expression is captured. +[[action-spec]] +Action specifier +~~~~~~~~~~~~~~~~ +Synopsis: -NOTE: Make sure to **single-quote** the capture expression when running -the command from a shell, as capture expressions typically include -characters having a special meaning for most shells. +[verse] +option:--action='ACTTYPE' ['ACTARGS'] + +An action specifier is the option:--action option, which specifies +the type of action 'ACTTYPE', followed, depending on 'ACTTYPE', with zero +or more arguments 'ACTARGS'. + +The available action types are: + +Notify:: + Synopsis: ++ +[verse] +option:--action=notify [nloption:--rate-policy='POLICY'] +{nbsp} ++ +Sends a notification through the notification +mechanism of the session daemon (see man:lttng-session(8)). ++ +The session daemon sends details about the condition evaluation along +with the notification. ++ +As of LTTng{nbsp}{lttng_version}, you can write a C/pass:[C++] program +to receive LTTng notifications (see the liblttng-ctl C{nbsp}headers). ++ +See below for the nloption:--rate-policy option. -* Supported field types: - - integer, - - unsigned integer, - - floating point value, - - fixed-size array of integers, - - variable-size array of integers (sequence), - - enumeration, - - text string, - - element of any allowing previous type. +Start a tracing session:: + Synopsis: ++ +[verse] +option:--action=start-session 'SESSION' [nloption:--rate-policy='POLICY'] +{nbsp} ++ +Starts the tracing session named 'SESSION' like man:lttng-start(1) +would. ++ +If no tracing session has the name 'SESSION' when LTTng is ready to +execute the action, LTTng does nothing. ++ +See below for the nloption:--rate-policy option. -* The dynamic value of an event field is captured by using its name as a C - identifier. +Stop a tracing session:: + Synopsis: + -The square bracket notation is available, like in the C -language, to access array/sequence field. -Only a constant, positive integer number can be used within square -brackets. If the index is out of bounds, the capture expression -evaluates to `unavailable`. +[verse] +option:--action=stop-session 'SESSION' [nloption:--rate-policy='POLICY'] +{nbsp} + -An enumeration field's value is an integer. +Stops the tracing session named 'SESSION' like man:lttng-stop(1) would. + -When the capture's field does not exist, the capture expression -evaluates to `unavailable`. +If no tracing session has the name 'SESSION' when LTTng is ready to +execute the action, LTTng does nothing. + -Examples: `my_field`, `target_cpu`, `seq[7]` +See below for the nloption:--rate-policy option. -* The dynamic value of a statically-known context field is captured by - prefixing its name with `$ctx.`. See man:lttng-add-context(1) to get a list of - available contexts. +Rotate a tracing session:: + Synopsis: ++ +[verse] +option:--action=rotate-session 'SESSION' [nloption:--rate-policy='POLICY'] +{nbsp} + -When the expression's statically-known context field does not exist, -the capture expression evaluates to `unavailable`. +Archives the current trace chunk of the tracing session named 'SESSION' +like man:lttng-rotate(1) would. + -Examples: `$ctx.prio`, `$ctx.preemptible`, -`$ctx.perf:cpu:stalled-cycles-frontend`. +If no tracing session has the name 'SESSION' when LTTng is ready to +execute the action, LTTng does nothing. + -NOTE: The statically-known context field does NOT need to be added using the -man:lttng-add-context(1) command. The statically-known context fields are -always available in the context of triggers. +See below for the nloption:--rate-policy option. -* The dynamic value of an application-specific context field is captured by - prefixing its name with `$app.` (follows the format used to add such a context - field with the man:lttng-add-context(1) command). +Take a tracing session snapshot:: + Synopsis: + -When the expression's application-specific context field does not exist, -the capture expression evaluates to `unavailable`. +[verse] +option:--action=snapshot-session 'SESSION' [nloption:--rate-policy='POLICY'] +{nbsp} + -Example: `$app.server:cur_user`. +Takes a snapshot of the tracing session named 'SESSION' like +man:lttng-snapshot(1) would. ++ +When the condition of the trigger is satisfied, the tracing session +named 'SESSION', if any, must be a snapshot-mode tracing session +(see man:lttng-create(1)). ++ +If no tracing session has the name 'SESSION' when LTTng is ready to +execute the action, LTTng does nothing. ++ +See below for the nloption:--rate-policy option. + +Common action options (as of LTTng{nbsp}{lttng_version}): + +nloption:--rate-policy='POLICY':: + Set the rate policy of the action to 'POLICY'. ++ +A trigger which ``fires'' (its condition is satisfied) leads to an +execution request for each of its actions, in order. An execution +request of a given action{nbsp}__A__ first increments the execution +request count{nbsp}__C__ of{nbsp}__A__. An execution request can then +become an actual execution when{nbsp}__C__ satisfies the rate policy +of{nbsp}__A__. ++ +The default action rate policy is `every:1` (always execute{nbsp}__A__). +Use this option to specify another rate policy. + -NOTE: The application-specific context field does NOT need to be added using the -man:lttng-add-context(1) command. The application-specific context fields fields -are always available in the context of triggers. +'POLICY' is one of: ++ +-- +++once-after:++__COUNT__:: + Only execute{nbsp}__A__ when{nbsp}__C__ is equal to 'COUNT'. ++ +In other words, execute{nbsp}__A__ a single time after 'COUNT' execution +requests. + +++every:++__COUNT__:: + Only execute{nbsp}__A__ when{nbsp}__C__ is a multiple of 'COUNT'. ++ +In other words, execute{nbsp}__A__ every 'COUNT' execution requests. +-- ++ +As of LTTng{nbsp}{lttng_version}, you can use this option with any +action type, but new action types in the future may not support it. OPTIONS ------- +Identification +~~~~~~~~~~~~~~ +option:--name='NAME':: + Set the unique name of the trigger to add to 'NAME' instead of the + `add-trigger` command automatically assigning one. + +option:--owner-id='UID':: + Add the trigger as the Unix user having the user ID 'UID'. ++ +You may only use this option if your Unix user is `root`. -option:--condition:: - Define the condition for the trigger. See the - <> section for more details. - -option:--action:: - Define an action for the trigger. See the <> - section for more details. -option:--id='ID':: - Set the id of the trigger to 'ID'. If omitted, an id will - automatically be assigned to the trigger by the session daemon. +Specifier +~~~~~~~~~ +option:--condition='CONDTYPE':: + Introductory option for a condition specifier of type 'CONDTYPE'. + -If a trigger with the specified 'ID' already exists, the trigger -creation will fail. +See the <> section above to learn more. -option:--fire-every 'N':: - Execute the trigger's actions every 'N' times the condition is met. +option:--action='ACTTYPE':: + Introductory option for an action specifier of type 'ACTTYPE'. ++ +See the <> section above to learn more. -option:--fire-once-after 'N':: - Execute the trigger's actions once after 'N' times the condition is - met, then never after that. include::common-cmd-help-options.txt[] @@ -197,6 +314,6 @@ include::common-cmd-footer.txt[] SEE ALSO -------- +man:lttng(1), man:lttng-list-triggers(1), -man:lttng-remove-trigger(1), -man:lttng(1) +man:lttng-remove-trigger(1) diff --git a/doc/man/lttng-clear.1.txt b/doc/man/lttng-clear.1.txt index 6a84ae084..7cec7f44e 100644 --- a/doc/man/lttng-clear.1.txt +++ b/doc/man/lttng-clear.1.txt @@ -1,6 +1,6 @@ lttng-clear(1) -=============== -:revdate: 2 April 2020 +============== +:revdate: 8 April 2021 NAME ---- @@ -16,43 +16,48 @@ SYNOPSIS DESCRIPTION ----------- The `lttng clear` command clears one or more tracing sessions, that is, -it deletes the contents of their tracing buffers and all their local and -streamed trace data. +it deletes the contents of their tracing buffers and of all their local +and streamed trace data. -If no options are specified, the current tracing session is cleared -(see man:lttng-create(1) for more information about the current -tracing session). +The `clear` command clears: -If 'SESSION' is specified, the existing tracing session named 'SESSION' -is cleared. +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. -With the option:--all option, *all* the tracing sessions, as listed in -the output of `lttng list` (see man:lttng-list(1)), are cleared. +With the 'SESSION' argument:: + The existing 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)). If a tracing session is configured in snapshot mode (see the -man:lttng-create(1) command's nloption:--snapshot option), only the -tracing buffers are cleared. +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)), only its tracing buffers and its current trace -chunk are cleared; its archived trace chunks are :not: cleared. +man:lttng-rotate(1)), 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 `LTTNG_RELAYD_DISALLOW_CLEAR` environment variable of man:lttng-relayd(8) can disable remote clearing operations. If LTTng -sends tracing data over the network for 'SESSION' (or for any tracing -session with the option:--all option) to a relay daemon configured as -such, `lttng clear` fails. +sends tracing data over the network for the selected tracing session(s) +to an LTTng relay daemon configured as such, the `clear` command fails. include::common-cmd-options-head.txt[] -Target -~~~~~~ +Recording target +~~~~~~~~~~~~~~~~ option:-a, option:--all:: - Clear all the tracing sessions instead of the current tracing - session or the tracing session named 'SESSION'. + 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'. include::common-cmd-help-options.txt[] @@ -63,8 +68,8 @@ include::common-cmd-footer.txt[] SEE ALSO -------- +man:lttng(1), man:lttng-create(1), -man:lttng-rotate(1), -man:lttng-set-session(1), man:lttng-relayd(8), -man:lttng(1) +man:lttng-rotate(1), +man:lttng-set-session(1) diff --git a/doc/man/lttng-crash.1.txt b/doc/man/lttng-crash.1.txt index a8a2c9f4d..a25fd4fbd 100644 --- a/doc/man/lttng-crash.1.txt +++ b/doc/man/lttng-crash.1.txt @@ -1,30 +1,25 @@ lttng-crash(1) ============== -:revdate: 2 April 2020 +:revdate: 8 April 2021 NAME ---- -lttng-crash - Recover and view LTTng 2 trace buffers in the event of a crash +lttng-crash - Recover and read LTTng trace buffers in the event of a crash SYNOPSIS -------- [verse] -*lttng-crash* [option:--extract='PATH' | option:--viewer='VIEWER'] [option:-v | option:-vv | option:-vvv] 'SHMDIR' +*lttng-crash* [option:--extract='DIR' | option:--viewer='READER'] [option:-verbose]... 'SHMDIR' 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). - -The `lttng-crash` command-line tool is used to recover and view -LTTng trace buffers in the event of a system crash. +The `lttng-crash` command-line tool recovers LTTng trace buffers in the +event of a system crash. `lttng-crash` reads files within the directory 'SHMDIR' and does one of: @@ -33,8 +28,9 @@ Without the option:--extract option:: Launches a trace reader (see the option:--viewer option) to view the recovered traces. -With the option:--extract option:: - Extracts them as uncorrupted LTTng traces on the file system. +With the option:--extract='DIR' option:: + Extracts the files as uncorrupted LTTng traces to the 'DIR' + directory. 'SHMDIR' is the directory specified as the argument of the nloption:--shm-path option of the man:lttng-create(1) command used to @@ -43,22 +39,21 @@ create the tracing session for which to recover the traces. OPTIONS ------- -option:-x 'PATH', option:--extract='PATH':: - Extract recovered traces to path 'PATH'; do not execute the trace - viewer. +option:-x 'DIR', option:--extract='DIR':: + Extract recovered traces to the directory 'DIR'; do :not: execute + any trace reader. 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`). - -option:-e 'VIEWER', option:--viewer='VIEWER':: - Use trace viewer 'VIEWER' to view the trace buffers. 'VIEWER' is the - absolute path to the viewer command to use, and it can contain - command arguments as well. The trace directory paths are passed to - the 'VIEWER' command as its last arguments. +Specify this option up to three times to get more levels of verbosity. + +option:-e 'READER', option:--viewer='READER':: + Use the trace reader 'READER' to read the trace buffers. ++ +'READER' is the absolute path to the reader command to use, and it can +contain command arguments as well. `lttng-crash` passes the trace +directory paths to the 'READER' command as its last arguments. + Without this option, `lttng crash` uses man:babeltrace2(1) if it's available. Otherwise, it tries to use man:babeltrace(1). @@ -66,11 +61,10 @@ available. Otherwise, it tries to use man:babeltrace(1). Program information ~~~~~~~~~~~~~~~~~~~ -option:-h, option:--help:: - Show help. +include::common-help-option.txt[] option:-V, option:--version:: - Show version. + Show version and quit. EXIT STATUS @@ -90,8 +84,9 @@ include::common-footer.txt[] SEE ALSO -------- +man:babeltrace2(1), man:lttng(1), -man:lttng-sessiond(8), +man:lttng-create(1), man:lttng-relayd(8), -man:lttng-ust(3), -man:babeltrace2(1) +man:lttng-sessiond(8), +man:lttng-ust(3) diff --git a/doc/man/lttng-create.1.txt b/doc/man/lttng-create.1.txt index d61918d6a..b1032fb5e 100644 --- a/doc/man/lttng-create.1.txt +++ b/doc/man/lttng-create.1.txt @@ -1,6 +1,6 @@ lttng-create(1) =============== -:revdate: 18 January 2018 +:revdate: 8 April 2021 NAME @@ -10,159 +10,273 @@ lttng-create - Create an LTTng tracing session SYNOPSIS -------- -Local mode: +Create a local mode tracing session: [verse] -*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] [option:--shm-path='PATH'] - [option:--no-output | option:--output='PATH' | option:--set-url=file://'PATH'] +*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] [option:--shm-path='DIR'] + [option:--no-output | option:--output='DIR' | option:--set-url=file://'DIR'] -Network streaming mode: +Create a network streaming mode tracing session: [verse] -*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] [option:--shm-path='PATH'] +*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] [option:--shm-path='DIR'] (option:--set-url='URL' | option:--ctrl-url='URL' option:--data-url='URL') -Snapshot mode: +Create a snapshot mode tracing session: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] option:--snapshot - [option:--shm-path='PATH'] [option:--set-url='URL' | option:--ctrl-url='URL' option:--data-url='URL'] + [option:--shm-path='DIR'] [option:--set-url='URL' | option:--ctrl-url='URL' option:--data-url='URL'] -Live mode: +Create a live mode tracing session: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] option:--live[='DELAYUS'] - [option:--shm-path='PATH'] [option:--set-url='URL' | option:--ctrl-url='URL' option:--data-url='URL'] + [option:--shm-path='DIR'] [option:--set-url='URL' | option:--ctrl-url='URL' option:--data-url='URL'] DESCRIPTION ----------- -The `lttng create` command creates a new tracing session. - -A tracing session is a named container of channels, which in turn -contain event rules. It is domain-agnostic, in that channels and event -rules can be enabled for the user space tracer and/or the Linux -kernel tracer. - -On execution, an `.lttngrc` file is created, if it does not exist, in the -user's home directory. This file contains the name of the current tracing -session. When creating a new tracing session with `lttng create`, the -current tracing session is set to this new tracing session. The -man:lttng-set-session(1) command can be used to set the current -tracing session without manually editing the `.lttngrc` file. - -If 'SESSION' is omitted, a session name is automatically created having -this form: `auto-YYYYmmdd-HHMMSS`. 'SESSION' *must not* contain the -character `/`. - -The option:--shm-path option can be used to specify the path to the -shared memory holding the ring buffers. Specifying a location on an -NVRAM file system makes it possible to retrieve the latest recorded -trace data when the system reboots after a crash. To view the events -of ring buffer files after a system crash, use the -man:lttng-crash(1) utility. - -Tracing sessions are destroyed using the man:lttng-destroy(1) +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. + +* 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)). + +Without the 'SESSION' argument, LTTng automatically generates a tracing +session name having the ++auto-++__YYYYmmdd__++-++__HHMMSS__ form, where +'YYYYmmdd' and 'HHMMSS' are the creation date and time. 'SESSION' may +:not: contain the character `/`. + +Specify the path of the directory containing the shared memory files +holding the channel ring buffers with the option:--shm-path option. +Specifying a location on an NVRAM file system makes it possible to +recover the latest recorded trace data when the system reboots after a +crash with the man:lttng-crash(1) utility. + +By default, the `create` command automatically spawns a session daemon +for your Unix user if none is currently running. Override the path of +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. +Start and stop a tracing session with the man:lttng-start(1) and +man:lttng-stop(1) commands. -Creation modes -~~~~~~~~~~~~~~ -There are four tracing session modes: +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 +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: [[local-mode]]Local mode:: - Traces the local system and writes the trace to the local - file system. The option:--output option specifies the trace path. - Using option:--set-url=file://'PATH' is the equivalent of using - option:--output='PATH'. The file system output can be disabled using - the option:--no-output option. + 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'. + -If none of the options mentioned above are used, then the trace is -written locally in the `$LTTNG_HOME/lttng-traces` directory -(`$LTTNG_HOME` defaults to `$HOME`). +Disable the file system output with the +option:--no-output option. ++ +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`). [[network-streaming-mode]]Network streaming mode:: - Traces the local system and sends the trace over the network to - a listening relay daemon (see man:lttng-relayd(8)). - The option:--set-url, or option:--ctrl-url and option:--data-url - options set the trace output destination (see the - <> section below). - -[[snapshot-mode]]Snapshot mode:: - Traces the local system without writing the trace to the local file - system (implicit option:--no-output option). Channels are automatically - configured to be snapshot-ready on creation (see - man:lttng-enable-channel(1)). The man:lttng-snapshot(1) - command is used to take snapshots of the current ring buffers. - The option:--set-url, or option:--ctrl-url and option:--data-url - options set the default snapshot output destination. - -[[live-mode]]Live mode:: - Traces the local system, sending trace data to an LTTng relay daemon - over the network (see man:lttng-relayd(8)). The - option:--set-url, or option:--ctrl-url and option:--data-url options - set the trace output destination. The live output URLs cannot use - the `file://` protocol (see the <> - section below). + Send the trace data over the network to a listening relay daemon + (see man:lttng-relayd(8)). ++ +Set the trace output destination with the option:--set-url option, or +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. ++ +LTTng automatically configures the channels of such a tracing session to +be snapshot-ready on creation (see man:lttng-enable-channel(1)). ++ +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)). +-- ++ +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). + +[[live-mode]]Live mode (option:--live option):: + Send the trace data over the network to a listening relay daemon + (see man:lttng-relayd(8)) for live reading. ++ +Set the trace output destination with the option:--set-url='URL' option, +or with the option:--ctrl-url='URL' and option:--data-url='URL' options +(see the <> section below). 'URL' may :not: start +with `file://`. [[url-format]] URL format ~~~~~~~~~~ -The option:--set-url, option:--ctrl-url, and option:--data-url options' -arguments are URLs. +The argument of the option:--set-url, option:--ctrl-url, and +option:--data-url options is an URL. -The format of those URLs is one of: +There are two available URL formats. +Local format:: ++ [verse] -file://'TRACEPATH' -'NETPROTO'://('HOST' | 'IPADDR')[:__CTRLPORT__[:__DATAPORT__]][/'TRACEPATH'] - -The `file://` protocol targets the *local file system* and can only -be used as the option:--set-url option's argument when the session is -created in <> or <> mode. - -'TRACEPATH':: - Absolute path to trace files on the local file system. - -The other version is available when the session is created in -<>, -<>, or <> mode. +file://'TRACEDIR' +{nbsp} ++ +The `file://` protocol targets the *local file system*: you may only use +such an URL with the option:--set-url option when you create the tracing +session in local or snapshot mode (see the <> section above). ++ +'TRACEDIR'::: + Absolute path to the directory containing the trace data on the + local file system. -'NETPROTO':: +Network format:: ++ +[verse] +'NETPROTO'://('HOST' | 'IPADDR')[:__CTRLPORT__[:__DATAPORT__]][/'TRACEDIR'] +{nbsp} ++ +This format is only available when you create the tracing session in +network streaming, snapshot, or live mode (see the <> section above). ++ +'NETPROTO'::: Network protocol, amongst: + -- `net`:: - TCP over IPv4; the default values of 'CTRLPORT' and 'DATAPORT' - are respectively {default_network_control_port} and - {default_network_data_port}. + TCP over IPv4. ++ +The default values of 'CTRLPORT' and 'DATAPORT' +are respectively {default_network_control_port} and +{default_network_data_port}. `net6`:: - TCP over IPv6: same default ports as the `net` protocol. + TCP over IPv6. ++ +The default values of 'CTRLPORT' and 'DATAPORT' +are respectively {default_network_control_port} and +{default_network_data_port}. `tcp`:: - Same as the `net` protocol; can only be used with the - option:--ctrl-url and option:--data-url options together. + Same as the `net` protocol. ++ +You may only use this with the option:--ctrl-url and option:--data-url +options together. `tcp6`:: - Same as the `net6` protocol; can only be used with the - option:--ctrl-url and option:--data-url options together. + Same as the `net6` protocol. ++ +You can only be use this with the option:--ctrl-url and +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]). -('HOST' | 'IPADDR'):: - Hostname or IP address (IPv6 address *must* be enclosed in brackets - (`[` and `]`); see https://www.ietf.org/rfc/rfc2732.txt[RFC 2732]). - -'CTRLPORT':: - Control port. +'CTRLPORT'::: + Control TCP port. -'DATAPORT':: - Data port. +'DATAPORT'::: + Data TCP port. -'TRACEPATH':: - Path of trace files on the remote file system. This path is relative - to the base output directory set on the relay daemon side; - see man:lttng-relayd(8). +'TRACEDIR'::: + Path of the directory containing the trace data on the remote file + system. ++ +This path is relative to the base output directory of the LTTng relay +daemon (see the nloption:--output option of man:lttng-relayd(8)). include::common-cmd-options-head.txt[] @@ -170,58 +284,74 @@ include::common-cmd-options-head.txt[] Mode selection ~~~~~~~~~~~~~~ +See the <> section above. + +At most one of: + option:--live[='DELAYUS']:: - Create the session in <>. + Create the tracing session in live mode. + -The optional 'DELAYUS' parameter, given in microseconds, is the -maximum time the user can wait for the data to be flushed. This mode -can be set with a network URL (options option:--set-url, or -option:--ctrl-url and option:--data-url) and must have a relay -daemon listening (see man:lttng-relayd(8)). +The optional 'DELAYUS' argument is the maximum time (in µs) you can wait +for the data to be flushed (sent to the connected LTTng relay daemon). +The default value of 'DELAYUS' is {default_lttng_live_timer}. + -By default, 'DELAYUS' is {default_lttng_live_timer} and the network URL -is set to `net://127.0.0.1`. +Set the URL of the relay daemon to connect to with the option:--set-url +option, or with the option:--ctrl-url and option:--data-url options, +instead of using `net://127.0.0.1`. ++ +The session daemon must be able to connect to a listening relay daemon +(see man:lttng-relayd(8)). option:--snapshot:: - Create the session in <>. - This is the equivalent of using the option:--no-output option and - creating all the channels of this new tracing session in overwrite - mode with an `mmap` output type. + 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)). Output ~~~~~~ option:--no-output:: - In <>, do not output any trace data. + In local mode (see the <> section + above), do :not: write any trace data. ++ +You may :not: use this option with the option:--output option. -option:-o 'PATH', option:--output='PATH':: - In <>, set trace output path to 'PATH'. +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. -option:--shm-path='PATH':: - Create shared memory holding buffers at 'PATH'. +option:--shm-path='DIR':: + Set the path of the directory containing the shared memory files + holding the channel ring buffers to 'DIR' on the local file sytem. URL ~~~ -See the <> section above for more information -about the syntax of the following options' 'URL' argument. +See the <> section above to learn more about the +syntax of the 'URL' argument of the following options. 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. 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. option:-U 'URL', option:--set-url='URL':: - Set URL destination of the trace data to 'URL'. It is persistent for - the session lifetime. This option sets both data - (option:--data-url option) and control (option:--ctrl-url option) - URLs at the same time. + 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. + -In <> mode, 'URL' must start with `file://` followed -by the destination path on the local file system. +In local mode (see the <> section above), +'URL' must start with `file://`, followed with the destination directory +path on the local file system. include::common-cmd-help-options.txt[] @@ -232,6 +362,13 @@ include::common-cmd-footer.txt[] SEE ALSO -------- +man:lttng(1), man:lttng-destroy(1), +man:lttng-enable-channel(1), +man:lttng-relayd(8), +man:lttng-rotate(1), +man:lttng-sessiond(8), man:lttng-set-session(1), -man:lttng(1) +man:lttng-start(1), +man:lttng-stop(1), +man:lttng-track(1) diff --git a/doc/man/lttng-destroy.1.txt b/doc/man/lttng-destroy.1.txt index e68ad77ae..2ddd05a99 100644 --- a/doc/man/lttng-destroy.1.txt +++ b/doc/man/lttng-destroy.1.txt @@ -1,11 +1,11 @@ lttng-destroy(1) ================ -:revdate: 18 January 2018 +:revdate: 12 April 2021 NAME ---- -lttng-destroy - Destroy an LTTng tracing session +lttng-destroy - Destroy LTTng tracing sessions SYNOPSIS @@ -16,48 +16,64 @@ SYNOPSIS DESCRIPTION ----------- -The `lttng destroy` command destroys one or more tracing sessions. +The `lttng destroy` command destroys one or more tracing sessions +previously created with the man:lttng-create(1) command. -If no options are specified, the current tracing session is destroyed -(see man:lttng-create(1) for more information about the current -tracing session). +``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. -If 'SESSION' is specified, the existing tracing session named 'SESSION' -is destroyed. `lttng list` outputs all the existing tracing sessions -(see man:lttng-list(1)). +Use the `destroy` command to destroy: -If the option:--all option is used, *all* the tracing sessions, as listed -in the output of `lttng list`, are destroyed. +With the 'SESSION' argument:: + The tracing session named 'SESSION'. -Destroying a tracing session stops any tracing running within the -latter. By default, the implicit man:lttng-stop(1) command invoked by -the `lttng destroy` command ensures that the tracing session's trace -data is valid before returning. With the option:--no-wait option, the -man:lttng-stop(1) command finishes immediately, hence a local trace -might not be valid when the command is done. In this case, there is no -way to know when the trace becomes valid. +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)). -Destroying a tracing session does not destroy the recorded trace data, -if any; it frees resources acquired by the session daemon and tracer -side, making sure to flush all trace data. +Otherwise:: + The current tracing session (see man:lttng-create(1) and + man:lttng-set-session(1) to learn more about the current tracing + session). ++ +In that case, the current tracing session becomes nonexistent. -If at least one rotation occurred during the chosen tracing session's -lifetime (see man:lttng-rotate(1) and man:lttng-enable-rotation(1)), and -without the option:--no-wait option, all the tracing session's output -directory's subdirectories are considered trace chunk archives once the -command returns: it is safe to read them, modify them, move them, or -remove them. +The `destroy` command stops any tracing activity within the selected +tracing session(s). By default, the command runs the 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. + +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. + +* 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. + +Then all the subdirectories of the output directory of{nbsp}__TS__ +(local or remote) are considered trace chunk archives once the `destroy` +command exits. In other words, it's safe to read them, modify them, move +them, or remove then. include::common-cmd-options-head.txt[] option:-a, option:--all:: - Destroy all tracing sessions. + Destroy all the tracing sessions of your Unix user, as listed in the + output of man:lttng-list(1). option:-n, option:--no-wait:: - Do not ensure that the chosen tracing session's trace data is valid - before returning to the prompt. + Do :not: ensure that the trace data of the tracing session(s) to + destroy is valid before exiting. include::common-cmd-help-options.txt[] @@ -68,6 +84,7 @@ include::common-cmd-footer.txt[] SEE ALSO -------- +man:lttng(1), man:lttng-create(1), -man:lttng-set-session(1), -man:lttng(1) +man:lttng-list(1), +man:lttng-set-session(1) diff --git a/doc/man/lttng-disable-channel.1.txt b/doc/man/lttng-disable-channel.1.txt index ccfb1a9fa..be845e65d 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: 28 November 2016 +:revdate: 21 April 2021 NAME ---- @@ -17,36 +17,40 @@ SYNOPSIS DESCRIPTION ----------- The `lttng disable-channel` command disables one or more channels -previously enabled by the man:lttng-enable-channel(1) command. +previously enabled with the man:lttng-enable-channel(1) command. -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 disabled using `lttng disable-channel` can -be specified using the option:--session option. If the option:--session -option is omitted, the current tracing session is targeted. +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). -Note that re-enabling a disabled channel once its tracing session -has been active at least once is currently not supported. +The `disable-channel` command disables one channel per 'CHANNEL' +argument. + +As of LTTng{nbsp}{lttng_version}, you may :not: enable a disabled +channel once its tracing session has ben started (see +man:lttng-start(1)) at least once. include::common-cmd-options-head.txt[] -Domain -~~~~~~ +Tracing domain +~~~~~~~~~~~~~~ One of: option:-k, option:--kernel:: - Disable channel in the Linux kernel domain. + Disable one or more Linux kernel channels. option:-u, option:--userspace:: - Disable channel in the user space domain. + Disable one or more user space channels. Target ~~~~~~ option:-s 'SESSION', option:--session='SESSION':: - Disable channels in the tracing session named 'SESSION' + Disable one or more channels of the tracing session named 'SESSION' instead of the current tracing session. @@ -58,5 +62,5 @@ include::common-cmd-footer.txt[] SEE ALSO -------- -man:lttng-disable-channel(1), -man:lttng(1) +man:lttng(1), +man:lttng-enable-channel(1) diff --git a/doc/man/lttng-disable-event.1.txt b/doc/man/lttng-disable-event.1.txt index 096d921b1..9719a631c 100644 --- a/doc/man/lttng-disable-event.1.txt +++ b/doc/man/lttng-disable-event.1.txt @@ -1,109 +1,144 @@ lttng-disable-event(1) ====================== -:revdate: 28 November 2016 +:revdate: 21 April 2021 NAME ---- -lttng-disable-event - Disable LTTng event rules +lttng-disable-event - Disable LTTng recording event rules SYNOPSIS -------- +Disable one or more recording event rules matching Linux kernel +events: + +[verse] +*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *disable-event* option:--kernel + [option:--tracepoint | option:--syscall | option:--probe | option:--function] + (option:--all-events | 'NAME'[,'NAME']...) + [option:--session='SESSION'] [option:--channel='CHANNEL'] + +Disable one or more recording event rules matching user space +tracepoint or Java/Python logging events: + [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *disable-event* - (option:--kernel [option:--probe | option:--function | option:--syscall] | - option:--userspace | option:--jul | option:--log4j | option:--python) + (option:--userspace | option:--jul | option:--log4j | option:--python) [option:--tracepoint] + (option:--all-events | 'NAME'[,'NAME']...) [option:--session='SESSION'] [option:--channel='CHANNEL'] - (option:--all-events | 'EVENT'[,'EVENT']...) + DESCRIPTION ----------- -The `lttng disable-event` command disables one or more event rules -previously enabled by the man:lttng-enable-event(1) command. +The `lttng disable-event` command disables one or more enabled recording +event rules previously created with the man:lttng-enable-event(1) +command. -Event rules are always assigned to a channel when they are created. If -the option:--channel option is omitted, the default channel named -`channel0` is used. +As of LTTng{nbsp}{lttng_version}, the `disable-event` command can only +find recording event rules to disable by their instrumentation point +type and event name conditions. Therefore, you cannot disable recording +event rules having a specific instrumentation point log level condition, +for example. -If the option:--session option is omitted, the chosen channel is picked -from the current tracing session. +List the existing recording event rules of a given tracing session +and/or channel with the man:lttng-list(1) command. -If the option:--all-events option is used, all the existing event rules -of the chosen domain are disabled. Otherwise, at least one event rule -to disable named 'EVENT' must be specified. +Without the option:--all-events option, the `disable-event` command +disables one recording event rule per 'NAME' argument. 'NAME' is the +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)). -With the option:--kernel option, the event source type can be specified -using one of the option:--tracepoint, option:--probe, -option:--function, or option:--syscall options. See -man:lttng-enable-event(1) for more details about event source -types. +Without the option:--channel option, the `disable-event` command selects +the channel named `channel0`. -Events can be disabled while tracing is active -(use man:lttng-start(1) to make a tracing session active). +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)). include::common-cmd-options-head.txt[] -Domain -~~~~~~ +Tracing domain +~~~~~~~~~~~~~~ One of: option:-j, option:--jul:: - Disable event rules in the `java.util.logging` (JUL) domain. + Disable recording event rules in the `java.util.logging` (JUL) + domain. option:-k, option:--kernel:: - Disable event rules in the Linux kernel domain. + Disable recording event rules in the Linux kernel domain. option:-l, option:--log4j:: - Disable event rules in the Apache log4j domain. + Disable recording event rules in the Apache log4j domain. option:-p, option:--python:: - Disable event rules in the Python domain. + Disable recording event rules in the Python domain. option:-u, option:--userspace:: - Disable event rules in the user space domain. + Disable recording event rules in the user space tracing domain. -Target -~~~~~~ +Recording target +~~~~~~~~~~~~~~~~ option:-c 'CHANNEL', option:--channel='CHANNEL':: - Disable event rules in the channel named 'CHANNEL' instead - of the default channel name `channel0`. + Disable recording event rules attached to the channel named + 'CHANNEL' instead of `channel0`. option:-s 'SESSION', option:--session='SESSION':: - Disable event rules in the tracing session named 'SESSION' + Disable recording event rules in the tracing session named 'SESSION' instead of the current tracing session. -Event source type -~~~~~~~~~~~~~~~~~ -One of: +Instrumentation point type condition +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +At most one of: option:--function:: - Linux kernel kretprobe. Only available with the option:--kernel - domain option. + Only disable recording event rules which match Linux kretprobe + events. ++ +Only available with the option:--kernel option. option:--probe:: - Linux kernel kprobe. Only available with the option:--kernel - domain option. + Only disable recording event rules which match Linux kprobe events. ++ +Only available with the option:--kernel option. option:--syscall:: - Linux kernel system call. Only available with the option:--kernel - domain option. + Only disable recording event rules which match Linux system call + events. ++ +Only available with the option:--kernel option. option:--tracepoint:: - Linux kernel or application tracepoint. Only available - with the option:--kernel domain option (default Linux kernel - domain event source type). - - -Disabling -~~~~~~~~~ + Only disable recording event rules which match: ++ +-- +With the option:--kernel or option:--userspace option::: + LTTng tracepoint events. +With the option:--jul, option:--log4j, or option:--python option::: + Logging events. +-- ++ +As of LTTng{nbsp}{lttng_version}, this is the default instrumentation +point type condition option, but this may change in the future. + + +Event name condition +~~~~~~~~~~~~~~~~~~~~ option:-a, option:--all-events:: - Disable all enabled event rules in the chosen tracing session, - tracing domain, and channel. + Disable recording event rules regardless of their event name + condition is. + include::common-cmd-help-options.txt[] @@ -113,5 +148,6 @@ include::common-cmd-footer.txt[] SEE ALSO -------- +man:lttng(1), man:lttng-enable-event(1), -man:lttng(1) +man:lttng-list(1) diff --git a/doc/man/lttng-disable-rotation.1.txt b/doc/man/lttng-disable-rotation.1.txt index ef03c0bef..f9255a94e 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: 8 November 2018 +:revdate: 21 April 2021 NAME ---- -lttng-disable-rotation - Unset a tracing session's rotation schedule +lttng-disable-rotation - Unset a tracing session rotation schedule SYNOPSIS @@ -17,9 +17,16 @@ SYNOPSIS DESCRIPTION ----------- -The `lttng disable-rotation` command unsets a rotation schedule for the -current tracing session, or for the tracing session named 'SESSION' if -provided, previously set with the man:lttng-enable-rotation(1) command. +The `lttng disable-rotation` command unsets a rotation schedule, +previously set with the man:lttng-enable-rotation(1) command, for: + +With the option:--session='SESSION' option:: + The tracing session named 'SESSION'. + +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). include::common-cmd-options-head.txt[] @@ -36,10 +43,10 @@ option:--timer:: option of the man:lttng-enable-rotation(1) command. -Target -~~~~~~ +Recording target +~~~~~~~~~~~~~~~~ option:-s 'SESSION', option:--session='SESSION':: - Unset a rotation schedule in the tracing session named 'SESSION' + Unset a rotation schedule for the tracing session named 'SESSION' instead of the current tracing session. @@ -51,5 +58,6 @@ include::common-cmd-footer.txt[] SEE ALSO -------- +man:lttng(1), man:lttng-enable-rotation(1), -man:lttng(1) +man:lttng-rotate(1) diff --git a/doc/man/lttng-enable-channel.1.txt b/doc/man/lttng-enable-channel.1.txt index 7ddbe48b4..b9c6d1696 100644 --- a/doc/man/lttng-enable-channel.1.txt +++ b/doc/man/lttng-enable-channel.1.txt @@ -44,8 +44,8 @@ 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. Event, -rules, when created using man:lttng-enable-event(1), are always +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. diff --git a/doc/man/lttng-enable-event.1.txt b/doc/man/lttng-enable-event.1.txt index 87c831a4a..6acdbcd29 100644 --- a/doc/man/lttng-enable-event.1.txt +++ b/doc/man/lttng-enable-event.1.txt @@ -1,121 +1,91 @@ lttng-enable-event(1) ===================== -:revdate: 4 April 2019 +:revdate: 13 April 2021 NAME ---- -lttng-enable-event - Create or enable LTTng event rules +lttng-enable-event - Create or enable LTTng recording event rules SYNOPSIS -------- -Create or enable Linux kernel event rules: +Create or enable one or more recording event rules to match Linux kernel +tracepoint or system call events: [verse] -*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* option:--kernel - [option:--probe='SOURCE' | option:--function='SOURCE' | option:--syscall | - option:--userspace-probe='SOURCE'] - [option:--filter='EXPR'] [option:--session='SESSION'] - [option:--channel='CHANNEL'] 'EVENT'[,'EVENT']... +*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* option:--kernel [option:--tracepoint | option:--syscall] + (option:--all | 'NAME'[,'NAME']...) [option:--filter='EXPR'] + [option:--session='SESSION'] [option:--channel='CHANNEL'] -Create or enable an "all" Linux kernel event rule: +Create or enable a recording event rule to match Linux kernel events +created from a dynamic instrumentation point: [verse] -*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* option:--kernel option:--all [option:--syscall] +*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* option:--kernel + (option:--probe='LOC' | option:--function='LOC' | option:--userspace-probe='LOC') 'RECORDNAME' [option:--filter='EXPR'] [option:--session='SESSION'] [option:--channel='CHANNEL'] -Create or enable application/library event rules: +Create or enable one or more recording event rules to match +user space tracepoint events: [verse] -*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* - (option:--userspace | option:--jul | option:--log4j | option:--python) - [option:--filter='EXPR'] [option:--exclude='EVENT'[,'EVENT']...] - [option:--loglevel='LOGLEVEL' | option:--loglevel-only='LOGLEVEL'] - [option:--session='SESSION'] [option:--channel='CHANNEL'] (option:--all | 'EVENT'[,'EVENT']...) +*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* option:--userspace [option:--tracepoint] + (option:--all | 'NAME'[,'NAME']...) [option:--exclude='XNAME'[,'XNAME']...] + [option:--loglevel='LOGLEVEL' | option:--loglevel-only='LOGLEVEL'] [option:--filter='EXPR'] + [option:--session='SESSION'] [option:--channel='CHANNEL'] +Create or enable one or more recording event rules to match +Java/Python logging events: + +[verse] +*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* (option:--jul | option:--log4j | option:--python) + [option:--tracepoint] (option:--all | 'NAME'[,'NAME']...) + [option:--loglevel='LOGLEVEL' | option:--loglevel-only='LOGLEVEL'] [option:--filter='EXPR'] + [option:--session='SESSION'] [option:--channel='CHANNEL'] DESCRIPTION ----------- -The `lttng enable-event` command can create a new event rule, or enable -one or more existing and disabled ones. - -An event rule created by `lttng enable-event` is a set of conditions -that must be satisfied in order for an actual event to be emitted by an -LTTng tracer when the execution of an application or a library or the -Linux kernel reaches an event source (tracepoint, system call, dynamic -probe). Event sources can be listed with the man:lttng-list(1) command. - -The man:lttng-disable-event(1) command can be used to disable -existing event rules. - -Event rules are always assigned to a channel when they are created. If -the option:--channel option is omitted, a default channel named -`channel0` is used (and created automatically if it does not exist for -the specified domain in the selected tracing session). - -If the option:--session option is omitted, the chosen channel is picked -from the current tracing session. - -Events can be enabled while tracing is active -(use man:lttng-start(1) to make a tracing session active). - - -Event source types -~~~~~~~~~~~~~~~~~~ -Five types of event sources are available in the Linux kernel tracing -domain (option:--kernel option): - -Tracepoint (option:--tracepoint option; default):: - A Linux kernel tracepoint, that is, a static instrumentation point - placed in the kernel source code. Standard tracepoints are designed - and placed in the source code by developers and record useful - payload fields. - -Dynamic kernel probe (option:--probe option):: - A Linux kernel kprobe, that is, an instrumentation point placed - dynamically in the compiled kernel code. Dynamic probe events do not - record any payload field. - -Dynamic user space probe (option:--userspace-probe option):: - A Linux kernel uprobe, that is, an instrumentation point placed - dynamically in the compiled user space application/library through - the kernel. Dynamic user space probe events do not record any - payload field. -+ -See the <> section for more -information. - -Function probe (option:--function option):: - A Linux kernel kretprobe, that is, two instrumentation points placed - dynamically where a function is entered and where it returns in the - compiled kernel code. Function probe events do not record any - payload field. - -System call (option:--syscall option):: - A Linux kernel system call. Two instrumentation points are - statically placed where a system call function is entered and where - it returns in the compiled kernel code. System call event sources - record useful payload fields. - -The application tracing domains (option:--userspace, option:--jul, -option:--log4j, or option:--python options) only support tracepoints. -In the cases of the JUL, Apache log4j, and Python domains, the event -names correspond to _logger_ names. - - -Understanding event rule conditions -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -When creating an event rule with `lttng enable-event`, conditions are -specified using options. The logical conjunction (logical AND) of all -those conditions must be true when an event source is reached by an -application or by the Linux kernel in order for an actual event -to be emitted by an LTTng tracer. - -Any condition that is not explicitly specified on creation is considered -a _don't care_. - -For example, consider the following commands: +The `lttng enable-event` command does one of: + +* Create one or more recording event rules. + +* Enable one or more existing, 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_. + +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"] ---- @@ -123,138 +93,422 @@ $ lttng enable-event --userspace hello:world $ lttng enable-event --userspace hello:world --loglevel=TRACE_INFO ---- -Here, two event rules are created. The first one has a single condition: -the tracepoint name must match `hello:world`. The second one has two -conditions: - -* The tracepoint name must match `hello:world`, _and_ -* The tracepoint's defined log level must be at least as severe as - the `TRACE_INFO` level. - -In this case, the second event rule is pointless because the first one -is more general: it does not care about the tracepoint's log level. -If an event source matching both event rules is reached by the -application's execution, only one event is emitted. - -The available conditions for the Linux kernel domain are: - -* Tracepoint/system call name ('EVENT' argument with option:--tracepoint - or option:--syscall options) or dynamic probe/function name/address - (option:--probe, option:--userspace-probe, and option:--function - option's argument) which must match event source's equivalent. -+ -You can use `*` characters at any place in the tracepoint or system -call name as wildcards to match zero or more characters. To use a -literal `*` character, use :escwc:. - -* Filter expression (option:--filter option) executed against the - dynamic values of event fields at execution time that must evaluate - to true. See the <> section - below for more information. - -The available conditions for the application domains are: - -* Tracepoint name ('EVENT' with option:--tracepoint option) which must - match event source's equivalent. -+ -You can use `*` characters at any place in the tracepoint name as -wildcards to match zero or more characters. To use a literal `*` -character, use :escwc:. When you create an event rule with a tracepoint -name containing a wildcard, you can exclude specific tracepoint names -from the match with the option:--exclude option. - -* Filter expression (option:--filter option) executed against the - dynamic values of event fields at execution time that must evaluate - to true. See the <> section - below for more information. -* Event's log level that must be at least as severe as a given - log level (option:--loglevel option) or match exactly a given log - level (option:--loglevel-only option). - -When using `lttng enable-event` with a set of conditions that does not -currently exist for the chosen tracing session, domain, and channel, -a new event rule is created. Otherwise, the existing event rule is -enabled if it is currently disabled -(see man:lttng-disable-event(1)). - -The option:--all option can be used alongside the option:--tracepoint -or option:--syscall options. When this option is used, no 'EVENT' -argument must be specified. This option defines a single event rule -matching _all_ the possible events of a given tracing domain for the -chosen channel and tracing session. It is the equivalent of an 'EVENT' -argument named `*` (wildcard). - - -[[filter-expr]] -Filter expression -~~~~~~~~~~~~~~~~~ -A filter expression can be specified with the option:--filter option -when creating a new event rule. If the filter expression evaluates -to true when executed against the dynamic values of an event's fields -when tracing, the filtering condition passes. +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). + +[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. +==== + +List the existing recording event rules of a given tracing session +and/or channel with the man:lttng-list(1) command. + +Disable an existing, enabled recording event rule with the +man:lttng-disable-event(1) command. + + +Recording event rule overview +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +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: + +Explicit conditions:: + You set the following conditions when you create or + enable{nbsp}__ER__ with the `enable-event` command: ++ +-- +* The instrumentation point type 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. ++ +See the <> section below. + +* 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. ++ +See the <> +section below. + +* The fields of the payload of{nbsp}__E__ and the current context fields + satisfy a filter expression. ++ +See the <> +section below. +-- + +Implicit conditions:: ++ +-- +* _ER_ itself is enabled. ++ +A recording event rule is enabled on creation. ++ +Enable an existing, 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. + +* The tracing session of{nbsp}__ER__ is active (started). ++ +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. ++ +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. +-- + +The dedicated command-line options of most conditions are optional: if +you don't specify the option, the associated condition is always +satisfied. + + +[[inst-point-type-cond]] +Instrumentation point type condition +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +An event{nbsp}__E__ satisfies the instrumentation point type condition +of a recording event rule if the instrumentation point from which LTTng +creates{nbsp}__E__ is: + +For the Linux kernel tracing domain (option:--kernel option):: + With the option:--tracepoint option or without any other instrumentation point type option::: + An LTTng kernel tracepoint, that is, a statically defined point + in the source code of the kernel image or of a kernel module + with LTTng kernel tracer macros. ++ +As of LTTng{nbsp}{lttng_version}, this is the default instrumentation +point type of the Linux kernel tracing domain, but this may change in +the future. ++ +List the available Linux kernel tracepoints with `lttng list --kernel`. +See man:lttng-list(1) to learn more. + + With the option:--syscall option::: + The entry and exit 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. + + With the option:--probe option::: + A Linux kprobe, that is, a single probe dynamically placed in + the compiled kernel code. ++ +The argument of the option:--probe option is the location of the +kprobe to insert, either a symbol or a +memory address, while 'RECORDNAME' is the name of the record +of{nbsp}__E__ (see the <> section below). ++ +The payload of a Linux kprobe event is empty. + + With the option:--userspace-probe option::: + A Linux user space probe, that is, a single probe dynamically + placed at the entry of a compiled user space application/library + function through the kernel. ++ +The argument of the option:--userspace-probe option is the location +of the user space probe to insert, one of: ++ +-- +* A path and symbol (ELF method). +* A path, provider name, and probe name (SystemTap User-level Statically + Defined Tracing (USDT) method; a DTrace-style marker). ++ +As of LTTng{nbsp}{lttng_version}, LTTng only supports USDT probes which +are :not: reference-counted. +-- ++ +'RECORDNAME' is the name of the record of{nbsp}__E__ (see the +<> section below). ++ +The payload of a Linux user space probe event is empty. + + With the option:--function option::: + A Linux kretprobe, that is, two probes dynamically placed at the + entry and exit of a function in the compiled kernel code. ++ +The argument of the option:--function option is the location of the +Linux kretprobe to insert, either a symbol or +a memory address, while 'RECORDNAME' is the name of the record +of{nbsp}__E__ (see the <> section below). ++ +The payload of a Linux kretprobe event is empty. + +For the user space tracing domain (option:--userspace option):: + With or without the option:--tracepoint option::: + An LTTng user space tracepoint, that is, a statically defined + point in the source code of a C/$$C++$$ application/library with + LTTng user space tracer macros. ++ +As of LTTng{nbsp}{lttng_version}, this is the default and sole +instrumentation point type of the user space tracing domain, but this +may change in the future. ++ +List the available user space tracepoints with `lttng list --userspace`. +See man:lttng-list(1) to learn more. + +For the `java.util.logging` (option:--jul option), Apache log4j (option:--log4j option), and Python (option:--python option) tracing domains:: + With or without the option:--tracepoint option::: + A logging statement. ++ +As of LTTng{nbsp}{lttng_version}, this is the default and sole +instrumentation point type of the `java.util.logging`, Apache log4j, and +Python tracing domains, but this may change in the future. ++ +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. -NOTE: Make sure to **single-quote** the filter expression when running -the command from a shell, as filter expressions typically include -characters having a special meaning for most shells. -The filter expression syntax is similar to C language conditional -expressions (expressions that can be evaluated by an `if` statement), -albeit with a few differences: +[[event-name-cond]] +Event name condition +~~~~~~~~~~~~~~~~~~~~ +An event{nbsp}__E__ satisfies the event name condition of a recording +event rule{nbsp}__ER__ if the two following statements are true: -* C integer and floating point number constants are supported, as well - as literal strings between double quotes (`"`). You can use `*` - characters at any place in a literal string as wildcards to match zero - or more characters. To use a literal `*` character, use :escwc:. +* You specify the option:--all option or, depending on the + instrumentation type condition (see the + <> section + above) of{nbsp}__ER__, 'NAME' matches: ++ +-- +LTTng tracepoint:: + The full name of the tracepoint from which LTTng creates{nbsp}__E__. + -Examples: `32`, `-0x17`, `0755`, `12.34`, -+"a :escbs:"literal string:escbs:""+, `"src/*/*.h"`. +Note that the full name of a user space tracepoint is +__PROVIDER__++:++__NAME__, where __PROVIDER__ is the tracepoint provider +name and __NAME__ is the tracepoint name. + +Logging statement:: + The name of the Java or Python logger from which LTTng + creates{nbsp}__E__. -* The dynamic value of an event field is read by using its name as a C - identifier. +Linux system call:: + The name of the system call, without any `sys_` prefix, from which + LTTng creates{nbsp}__E__. +-- + +* You don't specify the option:--exclude=__XNAME__[++,++__XNAME__]... + option or, depending on the instrumentation type condition + of{nbsp}__ER__, none of the 'XNAME' arguments matches the full name of + the user space tracepoint from which LTTng creates{nbsp}__E__. + -The dot and square bracket notations are available, like in the C -language, to access nested structure and array/sequence fields. -Only a constant, positive integer number can be used within square -brackets. If the index is out of bounds, the whole filter expression -evaluates to false (the event is discarded). +The option:--exclude option is only available with the option:--userspace +option. + +This condition is only meaningful for the LTTng tracepoint, logging +statement, and Linux system call instrumentation point types: it's +always satisfied for the other types. + +In all cases, 'NAME' and 'XNAME' are globbing patterns: the `*` +character means ``match anything''. To match a literal `*` character, +use :escwc:. To match a literal `,` character, use +:esccomma:. + +IMPORTANT: Make sure to **single-quote** 'NAME' and 'XNAME' when they +contain the `*` character and when you run the `enable-event` command +from a shell. + +With the LTTng tracepoint, logging statement, and Linux system call +instrumentation point types, the `enable-event` command creates or +enables one independent recording event rule per 'NAME' argument +(non-option, comma-separated). With the option:--all option, the +`enable-event` command creates or enables a single recording event rule. + + +[[inst-point-log-level-cond]] +Instrumentation point log level condition +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +An event{nbsp}__E__ satisfies the instrumentation point log level +condition of a recording event rule if either: + +* The option:--loglevel and option:--loglevel-only options are + missing. + +* The log level of the LTTng user space tracepoint or logging statement + which creates{nbsp}__E__ is: + With the option:--loglevel='LOGLEVEL' option:: + At least as severe as 'LOGLEVEL'. + + With the option:--loglevel-only='LOGLEVEL' option:: + Exactly 'LOGLEVEL'. + +This condition is only meaningful for the LTTng user space tracepoint +and logging statement instrumentation point types: it's always satisfied +for other types. + +The available values of 'LOGLEVEL' are, depending on the tracing domain, +from the most to the least severe: + +User space (option:--userspace option):: + Shortcuts such as `system` are allowed. + -An enumeration field's value is an integer. +* `TRACE_EMERG` (0) +* `TRACE_ALERT` (1) +* `TRACE_CRIT` (2) +* `TRACE_ERR` (3) +* `TRACE_WARNING` (4) +* `TRACE_NOTICE` (5) +* `TRACE_INFO` (6) +* `TRACE_DEBUG_SYSTEM` (7) +* `TRACE_DEBUG_PROGRAM` (8) +* `TRACE_DEBUG_PROCESS` (9) +* `TRACE_DEBUG_MODULE` (10) +* `TRACE_DEBUG_UNIT` (11) +* `TRACE_DEBUG_FUNCTION` (12) +* `TRACE_DEBUG_LINE` (13) +* `TRACE_DEBUG` (14) + +`java.util.logging` (option:--jul option):: + Shortcuts such as `severe` are allowed. + -When the expression's field does not exist, the whole filter expression -evaluates to false. +* `JUL_OFF` (`INT32_MAX`) +* `JUL_SEVERE` (1000) +* `JUL_WARNING` (900) +* `JUL_INFO` (800) +* `JUL_CONFIG` (700) +* `JUL_FINE` (500) +* `JUL_FINER` (400) +* `JUL_FINEST` (300) +* `JUL_ALL` (`INT32_MIN`) + +Apache log4j (option:--log4j option):: + Shortcuts such as `severe` are allowed. ++ +* `LOG4J_OFF` (`INT32_MAX`) +* `LOG4J_FATAL` (50000) +* `LOG4J_ERROR` (40000) +* `LOG4J_WARN` (30000) +* `LOG4J_INFO` (20000) +* `LOG4J_DEBUG` (10000) +* `LOG4J_TRACE` (5000) +* `LOG4J_ALL` (`INT32_MIN`) + +Python (option:--python option):: + Shortcuts such as `critical` are allowed. ++ +* `PYTHON_CRITICAL` (50) +* `PYTHON_ERROR` (40) +* `PYTHON_WARNING` (30) +* `PYTHON_INFO` (20) +* `PYTHON_DEBUG` (10) +* `PYTHON_NOTSET` (0) + + +[[filter-cond]] +Event payload and context filter condition +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +An event{nbsp}__E__ satisfies the event payload and context filter +condition of a recording event rule if the option:--filter='EXPR' +option is missing or if 'EXPR' is _true_. + +'EXPR' can contain references to the payload fields of{nbsp}__E__ and +to the current context fields. + +IMPORTANT: Make sure to **single-quote** 'EXPR' when you run the +`enable-event` command from a shell, as filter expressions typically +include characters having a special meaning for most shells. + +The expected syntax of 'EXPR' is similar to the syntax of a +C{nbsp}language conditional expression (an expression which an `if` +statement can evaluate), but there are a few differences: + +* A _NAME_ expression identifies an event payload field named + _NAME_ (a C{nbsp}identifier). ++ +Use the C{nbsp}language dot and square bracket notations to access +nested structure and array/sequence fields. You can only use a constant, +positive integer number within square brackets. If the index is out of +bounds, 'EXPR' is _false_. ++ +The value of an enumeration field is an integer. ++ +When a field expression doesn't exist, 'EXPR' is _false_. + Examples: `my_field`, `target_cpu`, `seq[7]`, `msg.user[1].data[2][17]`. -* The dynamic value of a statically-known context field is read by - prefixing its name with `$ctx.`. Statically-known context fields are - context fields added to channels without the `$app.` prefix using the - man:lttng-add-context(1) command. +* A ++$ctx.++__TYPE__ expression identifies the statically-known context + field having the type _TYPE_ (a C{nbsp}identifier). ++ +List the available statically-known context field names with the +man:lttng-add-context(1) command. + -When the expression's statically-known context field does not exist, -the whole filter expression evaluates to false. +When a field expression doesn't exist, 'EXPR' is _false_. + Examples: `$ctx.prio`, `$ctx.preemptible`, `$ctx.perf:cpu:stalled-cycles-frontend`. -* The dynamic value of an application-specific context field is read by - prefixing its name with `$app.` (follows the format used to add such a - context field with the man:lttng-add-context(1) command). +* A ++$app.++__PROVIDER__++:++__TYPE__ expression identifies the + application-specific context field having the type _TYPE_ (a + C{nbsp}identifier) from the provider _PROVIDER_ (a C{nbsp}identifier). + -When the expression's application-specific context field does not exist, -the whole filter expression evaluates to false. +When a field expression doesn't exist, 'EXPR' is _false_. + Example: `$app.server:cur_user`. -The following precedence table shows the operators which are supported -in a filter expression. In this table, the highest precedence is 1. -Parentheses are supported to bypass the default order. - -IMPORTANT: Unlike the C language, the `lttng enable-event` filter -expression syntax's bitwise AND and OR operators (`&` and `|`) take -precedence over relational operators (`<`, `<=`, `>`, `>=`, `==`, and -`!=`). This means the filter expression `2 & 2 == 2` is true while the -equivalent C expression is false. +* Compare strings, either string fields or string literals + (double-quoted), with the `==` and `!=` operators. ++ +When comparing to a string literal, the `*` character means ``match +anything''. To match a literal `*` character, use :escwc:. ++ +Examples: `my_field == "user34"`, `my_field == my_other_field`, +`my_field == "192.168.*"`. +* The precedence table of the operators which are supported in 'EXPR' + is as follows. In this table, the highest precedence is{nbsp}1: ++ [options="header"] |=== |Precedence |Operator |Description |Associativity @@ -276,27 +530,34 @@ equivalent C expression is false. |8 |`&&` |Logical AND |Left-to-right |9 |`\|\|` |Logical OR |Left-to-right |=== - ++ +Parentheses are supported to bypass the default order. ++ +IMPORTANT: Unlike the C{nbsp}language, the bitwise AND and OR operators +(`&` and `|`) in 'EXPR' take precedence over relational operators (`<`, +`<=`, `>`, `>=`, `==`, and `!=`). This means the expression `2 & 2 == 2` +is _true_ while the equivalent C{nbsp}expression is _false_. ++ The arithmetic operators are :not: supported. - -All integer constants and fields are first casted to signed 64-bit ++ +LTTng first casts all integer constants and fields to signed 64-bit integers. The representation of negative integers is two's complement. This means that, for example, the signed 8-bit integer field 0xff (-1) becomes 0xffffffffffffffff (still -1) once casted. - -Before a bitwise operator is applied, all its operands are casted to -unsigned 64-bit integers, and the result is casted back to a signed -64-bit integer. For the bitwise NOT operator, it is the equivalent of -this C expression: - ++ +Before a bitwise operator is applied, LTTng casts all its operands to +unsigned 64-bit integers, and then casts the result back to a signed +64-bit integer. For the bitwise NOT operator, it's the equivalent of +this C{nbsp}expression: ++ [source,c] ---- (int64_t) ~((uint64_t) val) ---- - -For the binary bitwise operators, it is the equivalent of those C -expressions: - ++ +For the binary bitwise operators, it's the equivalent of those +C{nbsp}expressions: ++ [source,c] ---- (int64_t) ((uint64_t) lhs >> (uint64_t) rhs) @@ -305,17 +566,21 @@ expressions: (int64_t) ((uint64_t) lhs ^ (uint64_t) rhs) (int64_t) ((uint64_t) lhs | (uint64_t) rhs) ---- - ++ If the right-hand side of a bitwise shift operator (`<<` and `>>`) is -not in the [0,{nbsp}63] range, the whole filter expression evaluates to -false. +not in the [0,{nbsp}63] range, then 'EXPR' is _false_. -NOTE: Although it is possible to filter the process ID of an event when -the `pid` context has been added to its channel using, for example, -`$ctx.pid == 2832`, it is recommended to use the PID tracker instead, -which is much more efficient (see man:lttng-track(1)). +[NOTE] +==== +Use the man:lttng-track(1) and man:lttng-untrack(1) commands to allow or +disallow processes to record LTTng events based on their attributes +instead of using equivalent statically-known context fields in 'EXPR' +like `$ctx.pid`. -Filter expression examples: +The former method is much more efficient. +==== + +'EXPR' examples: ---------------------------- msg_id == 23 && size >= 2048 @@ -338,190 +603,200 @@ eax_reg & 0xff7 == 0x240 && x[4] >> 12 <= 0x1234 ------------------------------------------------ -[[log-levels]] -Log levels -~~~~~~~~~~ -Tracepoints and log statements in applications have an attached log -level. Application event rules can contain a _log level_ condition. - -With the option:--loglevel option, the event source's log level must -be at least as severe as the option's argument. With the -option:--loglevel-only option, the event source's log level must match -the option's argument. - -The available log levels are: +[[er-name]] +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__: -User space domain (option:--userspace option):: - Shortcuts such as `system` are allowed. +LTTng tracepoint (option:--kernel/option:--userspace and option:--tracepoint options):: + Full name of the tracepoint from which LTTng creates{nbsp}__E__. + -* `TRACE_EMERG` (0) -* `TRACE_ALERT` (1) -* `TRACE_CRIT` (2) -* `TRACE_ERR` (3) -* `TRACE_WARNING` (4) -* `TRACE_NOTICE` (5) -* `TRACE_INFO` (6) -* `TRACE_DEBUG_SYSTEM` (7) -* `TRACE_DEBUG_PROGRAM` (8) -* `TRACE_DEBUG_PROCESS` (9) -* `TRACE_DEBUG_MODULE` (10) -* `TRACE_DEBUG_UNIT` (11) -* `TRACE_DEBUG_FUNCTION` (12) -* `TRACE_DEBUG_LINE` (13) -* `TRACE_DEBUG` (14) +Note that the full name of a user space tracepoint is +__PROVIDER__++:++__NAME__, where __PROVIDER__ is the tracepoint provider +name and __NAME__ is the tracepoint name. -`java.util.logging` domain (option:--jul option):: - Shortcuts such as `severe` are allowed. +`java.util.logging` logging statement (option:--jul and option:--tracepoint options):: + `lttng_jul:event` + -* `JUL_OFF` (`INT32_MAX`) -* `JUL_SEVERE` (1000) -* `JUL_WARNING` (900) -* `JUL_INFO` (800) -* `JUL_CONFIG` (700) -* `JUL_FINE` (500) -* `JUL_FINER` (400) -* `JUL_FINEST` (300) -* `JUL_ALL` (`INT32_MIN`) +Such an event record has a string field `logger_name` which contains the +name of the `java.util.logging` logger from which LTTng +creates{nbsp}__E__. -Apache log4j domain (option:--log4j option):: - Shortcuts such as `severe` are allowed. +Apache log4j logging statement (option:--log4j and option:--tracepoint options):: + `lttng_log4j:event` + -* `LOG4J_OFF` (`INT32_MAX`) -* `LOG4J_FATAL` (50000) -* `LOG4J_ERROR` (40000) -* `LOG4J_WARN` (30000) -* `LOG4J_INFO` (20000) -* `LOG4J_DEBUG` (10000) -* `LOG4J_TRACE` (5000) -* `LOG4J_ALL` (`INT32_MIN`) +Such an event record has a string field `logger_name` which contains the +name of the Apache log4j logger from which LTTng creates{nbsp}__E__. -Python domain (option:--python option):: - Shortcuts such as `critical` are allowed. +Python logging statement (option:--python and option:--tracepoint options):: + `lttng_python:event` + -* `PYTHON_CRITICAL` (50) -* `PYTHON_ERROR` (40) -* `PYTHON_WARNING` (30) -* `PYTHON_INFO` (20) -* `PYTHON_DEBUG` (10) -* `PYTHON_NOTSET` (0) +Such an event record has a string field `logger_name` which contains the +name of the Python logger from which LTTng creates{nbsp}__E__. + +Linux system call (option:--kernel and option:--syscall options):: + Entry::: + ++syscall_entry_++__NAME__, where _NAME_ is the name of the + system call from which LTTng creates{nbsp}__E__, without any + `sys_` prefix. + + Exit::: + ++syscall_exit_++__NAME__, where _NAME_ is the name of the + system call from which LTTng creates{nbsp}__E__, without any + `sys_` prefix. + +Linux kprobe (option:--kernel and option:--probe options):: +Linux user space probe (option:--kernel and option:--userspace-probe options):: + 'RECORDNAME' (first non-option argument). +Linux kretprobe (option:--kernel and option:--function options):: + Entry::: + __RECORDNAME__++_entry++ -[[userspace-probe]] -Dynamic user space probes -~~~~~~~~~~~~~~~~~~~~~~~~~ -With the option:--userspace-probe option, you can instrument function -entries of any user space binary (application or library) using either -an available symbol name or a SystemTap User-level Statically Defined -Tracing (USDT, a DTrace-style marker) probe's provider and probe names. -As of this version, only USDT probes that are :not: surrounded by a -reference counter (semaphore) are supported. + Exit::: + __RECORDNAME__++_exit++ -The option:--userspace-probe option must be specified with the -option:--kernel option because it uses Linux's uprobe feature to -dynamically instrument a user space application or library. -As of this version, dynamic probe events do not record any payload -field. +[[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. + +You may enable a disabled recording event rule regardless of the +activity (started or stopped) of its tracing session (see +man:lttng-start(1) and man:lttng-stop(1)). + +To enable a disabled recording event rule, run the `enable-event` +command with the exact same options and arguments that you used to +create it. In particular, with the option:--filter='EXPR' option, 'EXPR' +must be the exact same string as the one you used on creation. include::common-cmd-options-head.txt[] -Domain -~~~~~~ +Tracing domain +~~~~~~~~~~~~~~ One of: option:-j, option:--jul:: - Create or enable event rules in the `java.util.logging` - (JUL) domain. + Create or enable recording event rules in the `java.util.logging` + (JUL) tracing domain. option:-k, option:--kernel:: - Create or enable event rules in the Linux kernel domain. + Create or enable recording event rules in the Linux kernel tracing + domain. option:-l, option:--log4j:: - Create or enable event rules in the Apache log4j domain. + Create or enable recording event rules in the Apache log4j tracing + domain. option:-p, option:--python:: - Create or enable event rules in the Python domain. + Create or enable recording event rules in the Python tracing domain. option:-u, option:--userspace:: - Create or enable event rules in the user space domain. + Create or enable recording event rules in the user space tracing + domain. -Target -~~~~~~ +Recording target +~~~~~~~~~~~~~~~~ option:-c 'CHANNEL', option:--channel='CHANNEL':: - Create or enable event rules in the channel named 'CHANNEL' instead - of the default channel name `channel0`. + Create or enable recording event rules attached to the channel named + 'CHANNEL' instead of `channel0`. option:-s 'SESSION', option:--session='SESSION':: - Create or enable event rules in the tracing session named 'SESSION' - instead of the current tracing session. + Create or enable recording event rules in the tracing session named + 'SESSION' instead of the current tracing session. -Event source type -~~~~~~~~~~~~~~~~~ -One of: +Instrumentation point type condition +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +See the <> +section above. -option:--function='SOURCE':: - Dynamic kernel return probe (kretprobe). Only available with the - option:--kernel domain option. 'SOURCE' is one of: +At most one of: + +option:--function='LOC':: + Only match Linux kretprobe events. ++ +Only available with the option:--kernel option. ++ +'LOC' is one of: + -* Function address (`0x` prefix supported) -* Function symbol name -* Function symbol name and offset (__SYMBOL__++pass:[+]++__OFFSET__ format) +-- +* A function address (`0x` hexadecimal prefix supported). +* A function symbol name. +* A function symbol name and an offset + (__SYMBOL__++pass:[+]++__OFFSET__ format). +-- ++ +You must specify the event record name with 'RECORDNAME'. See the +<> section above to learn more. -option:--probe='SOURCE':: - Dynamic kernel probe (kprobe). Only available with the - option:--kernel domain option. 'SOURCE' is one of: +option:--probe='LOC':: + Only match Linux kprobe events. ++ +Only available with the option:--kernel option. ++ +'LOC' is one of: ++ +-- +* An address (`0x` hexadecimal prefix supported). +* A symbol name. +* A symbol name and an offset (__SYMBOL__++pass:[+]++__OFFSET__ format). +-- + -* Address (`0x` prefix supported) -* Symbol name -* Symbol name and offset (__SYMBOL__++pass:[+]++__OFFSET__ format) +You must specify the event record name with 'RECORDNAME'. See the +<> section above to learn more. -option:--userspace-probe='SOURCE':: - Dynamic user space probe (uprobe). Only available with the - option:--kernel domain option. See the - <> section. +option:--userspace-probe='LOC':: + Only match Linux user space probe events. + -'SOURCE' is one of: +Only available with the option:--kernel option. ++ +'LOC' is one of: + -- \[++elf:++]__PATH__++:++__SYMBOL__:: - Dynamically instrument an available symbol within a user space - application or library. + Probe an available symbol within a user space application or + library. + -- 'PATH':: Application or library path. + -This can be: +One of: + * An absolute path. * A relative path. -* An application's name as found in the directories listed in the +* The name of an application as found in the directories listed in the `PATH` environment variable. 'SYMBOL':: Symbol name of the function of which to instrument the entry. + -This can be any defined code symbol listed by the man:nm(1) command -(including with its nloption:--dynamic option which lists dynamic -symbols). +'SYMBOL' can be any defined code symbol in the output of the man:nm(1) +command, including with its nloption:--dynamic option, which lists +dynamic symbols. -- + -As of this version, not specifying `elf:` is equivalent to specifying -it. +As of LTTng{nbsp}{lttng_version}, not specifying `elf:` is equivalent to +specifying it, but this default may change in the future. + Examples: + * `--userspace-probe=/usr/lib/libc.so.6:malloc` * `--userspace-probe=./myapp:createUser` -* `--userspace-probe=httpd:ap_run_open_htaccess` +* `--userspace-probe=elf:httpd:ap_run_open_htaccess` ++sdt:++__PATH__++:++__PROVIDER__++:++__NAME__:: - Dynamically instrument a USDT probe within a user space application - or library. + Use a SystemTap User-level Statically Defined Tracing (USDT) probe + within a user space application or library. + -- 'PATH':: @@ -531,10 +806,11 @@ This can be: + * An absolute path. * A relative path. -* An application's name as found in the directories listed in the +* The name of an application as found in the directories listed in the `PATH` environment variable. -__PROVIDER__++:++__NAME__:: +'PROVIDER':: +'NAME':: USDT provider and probe names. + For example, with the following USDT probe: @@ -548,58 +824,83 @@ DTRACE_PROBE2("server", "accept_request", The provider/probe name pair is `server:accept_request`. -- + -Example: -+ -* `--userspace-probe=sdt:./build/server:server:accept_request` +Example: `--userspace-probe=sdt:./build/server:server:accept_request` -- ++ +You must specify the event record name with 'RECORDNAME'. See the +<> section above to learn more. option:--syscall:: - Linux kernel system call. Only available with the option:--kernel - domain option. + Only match Linux system call events. ++ +Only available with the option:--kernel option. option:--tracepoint:: - Linux kernel or application tracepoint (default). + Only match: ++ +With the option:--kernel or option:--userspace option::: + LTTng tracepoint events. +With the option:--jul, option:--log4j, or option:--python option::: + Logging events. +With the option:--kernel, not specifying any of the instrumentation +point type options is equivalent to specifying the option:--tracepoint +option, but this default may change in the future. -Log level -~~~~~~~~~ -One of: +With the option:--userspace, option:--jul, option:--log4j, and +option:--python options, not specifying the option:--tracepoint option +is equivalent to specifying it, but this default may change in the +future. + + +Event name condition +~~~~~~~~~~~~~~~~~~~~ +See the <> section above. + +option:-a, option:--all:: + Equivalent to a single 'NAME' argument (LTTng tracepoint or logger + name) set to `*` (match anything). ++ +You may :not: use this option with a 'NAME' argument. + +option:-x 'XNAME'[,'XNAME']..., option:--exclude='XNAME'[,'XNAME']...:: + Only match events of which none of the 'XNAME' arguments + matches the full name of the LTTng user space tracepoint. ++ +Only available with the option:--userspace option. ++ +'XNAME' is a globbing pattern: the `*` character means ``match +anything''. To match a literal `*` character, use :escwc:. To match +a literal `,` character, use :esccomma:. + + +Instrumentation point log level condition +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +See the <> section above. + +At most one of: option:--loglevel='LOGLEVEL':: - Add log level condition to the event rule: the event source's - defined log level must be at least as severe as 'LOGLEVEL'. - See the <> section above for the available - log levels. Only available with application domains. + Only match events of which the log level of the LTTng tracepoint or + logging statement is at least as severe as 'LOGLEVEL'. option:--loglevel-only='LOGLEVEL':: - Add log level condition to the event rule: the event source's - defined log level must match 'LOGLEVEL'. See the - <> section above for the available log - levels. Only available with application domains. - - -Filtering and exclusion -~~~~~~~~~~~~~~~~~~~~~~~ -option:-x 'EVENT'[,'EVENT']..., option:--exclude='EVENT'[,'EVENT']...:: - Exclude events named 'EVENT' from the event rule. This option - can be used when the command's 'EVENT' argument contains at least - one wildcard star (`*`) to exclude specific names. 'EVENT' can also - contain wildcard stars. To use a - literal `,` character, use :esccomma:. - Only available with the option:--userspace domain. + Only match events of which the log level of the LTTng tracepoint or + logging statement is exactly 'LOGLEVEL'. -option:-f 'EXPR', option:--filter='EXPR':: - Add filter expression condition to the event rule. Expression 'EXPR' - must evaluate to true when executed against the dynamic values of - event fields. See the <> - section above for more information. +The instrumentation point log level options above are :not: available +with the option:--kernel option. -Shortcuts -~~~~~~~~~ -option:-a, option:--all:: - Equivalent to an 'EVENT' argument named `*` (wildcard) when also - using the option:--tracepoint (default) or option:--syscall option. +Event payload and context filter condition +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +See the <> +section above. + +option:-f 'EXPR', option:--filter='EXPR':: + Only match events of which 'EXPR', which can contain references to + event payload and current context fields, is _true_. include::common-cmd-help-options.txt[] @@ -610,5 +911,9 @@ include::common-cmd-footer.txt[] SEE ALSO -------- +man:lttng(1), man:lttng-disable-event(1), -man:lttng(1) +man:lttng-enable-channel(1), +man:lttng-list(1), +man:lttng-start(1), +man:lttng-track(1) diff --git a/doc/man/lttng-enable-rotation.1.txt b/doc/man/lttng-enable-rotation.1.txt index a002085aa..cd8de7309 100644 --- a/doc/man/lttng-enable-rotation.1.txt +++ b/doc/man/lttng-enable-rotation.1.txt @@ -1,62 +1,84 @@ lttng-enable-rotation(1) ======================== -:revdate: 13 November 2018 +:revdate: 21 April 2021 NAME ---- -lttng-enable-rotation - Set a tracing session's rotation schedule +lttng-enable-rotation - Set a tracing session rotation schedule SYNOPSIS -------- [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-rotation* [option:--session='SESSION'] - (option:--timer='PERIOD' | option:--size='SIZE' | option:--timer='PERIOD' option:--size='SIZE') + (option:--timer='PERIODUS' | option:--size='SIZE' | option:--timer='PERIODUS' option:--size='SIZE') DESCRIPTION ----------- -The `lttng enable-rotation` command sets a rotation schedule for the -current tracing session, or for the tracing session named 'SESSION' if -provided. See man:lttng-rotate(1) for more information about the -concepts of a tracing session _rotation_ and a _trace chunk_. +The `lttng enable-rotation` command sets a tracing session rotation +schedule for: -With the option:--timer option, the rotation schedule is set so that an -automatic rotation occurs at least every 'PERIOD' (microseconds without -a unit suffix). +With the option:--session='SESSION' option:: + The tracing session named 'SESSION'. -With the option:--size option, the rotation schedule is set -so that an automatic rotation occurs every time the total size of the -flushed part of the current trace chunk is at least 'SIZE' (bytes -without a unit suffix). +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). -For both option:--timer and option:--size options, LTTng checks the -schedule condition periodically using the monitor timers of the tracing -session's channels (see the nloption:--monitor-timer option of the -man:lttng-enable-channel(1) command). This means that: +See man:lttng-rotate(1) for more information about the concepts of a +tracing session _rotation_ and a _trace chunk_. -* With the option:--timer option, the automatic rotation can occur when - the elapsed time since the last automatic rotation is slightly greater - than 'PERIOD'. The exact precision is governed by the monitor timer's - precision, which relies on the precision of the platform's - implementation of POSIX timers. +With the option:--timer='PERIODUS' option, the `enable-rotation` command +sets a rotation schedule so that LTTng performs an automatic rotation at +least every 'PERIODUS'. -* With the option:--size option, the automatic rotation can occur when - the size of the flushed part of the current trace chunk is greater - than 'SIZE'. +With the option:--size='SIZE' option, the `enable-rotation` command sets +a rotation schedule so that LTTng performs an automatic rotation every +time the total size of the flushed part of the current trace chunk is at +least 'SIZE'. -You can combine the option:--timer and option:--size options. +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: + +* With the option:--timer='PERIODUS' option, LTTng can perform an + automatic rotation when the elapsed time since the last automatic + rotation is slightly greater than 'PERIODUS'. ++ +The exact precision depends on the precision of the monitor timer, which +relies on the precision of the platform implementation of POSIX timers. + +* With the option:--size='SIZE' option, LTTng can perform an automatic + rotation when the size of the flushed part of the current trace chunk + is greater than 'SIZE'. + +You may combine the option:--timer and option:--size options. The naming convention of a trace chunk archive which an automatic -rotation creates is the same as with the immediate rotation command, -man:lttng-rotate(1). +rotation operation creates is the same as with the immediate rotation +command, man:lttng-rotate(1). + +Unset a tracing session rotation schedule with the +man:lttng-disable-rotation(1) command. + +[IMPORTANT] +==== +The `enable-rotation` command only works when: + +* The selected tracing session was created in normal mode or in network + streaming mode (see man:lttng-create(1)). -You can unset a rotation schedule with the man:lttng-disable-rotation(1) -command. +* 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)). -See <> for important limitations regarding -this command. +For a given tracing session, LTTng only performs an automatic rotation +when no other rotation is currently happening. +==== include::common-cmd-options-head.txt[] @@ -65,19 +87,23 @@ include::common-cmd-options-head.txt[] Rotation schedule condition ~~~~~~~~~~~~~~~~~~~~~~~~~~~ option:--size='SIZE':: - Set a rotation schedule so that an automatic rotation occurs every - time the total size of the flushed part of the current trace chunk - is at least 'SIZE' bytes. The `k` (kiB), `M` (MiB), and `G` (GiB) - suffixes are supported. - -option:--timer='PERIOD':: - Set a rotation schedule so that an automatic rotation occurs at - least every 'PERIOD' microseconds. The `ms` (milliseconds), `s` - (seconds), `m` (minutes), and `h` (hours) suffixes are supported. - - -Target -~~~~~~ + Set a rotation schedule so that LTTng performs an automatic rotation + every time the total size of the flushed part of the current trace + chunk is at least 'SIZE' bytes. ++ +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. ++ +The `ms`{nbsp}(milliseconds), `s`{nbsp}(seconds), `m`{nbsp}(minutes), +and `h`{nbsp}(hours) suffixes are supported. + + +Recording target +~~~~~~~~~~~~~~~~ option:-s 'SESSION', option:--session='SESSION':: Set a rotation schedule for the tracing session named 'SESSION' instead of the current tracing session. @@ -86,27 +112,12 @@ option:-s 'SESSION', option:--session='SESSION':: include::common-cmd-help-options.txt[] -[[limitations]] -LIMITATIONS ------------ -The `lttng enable-rotation` command only works when: - -* The tracing session is 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 in man:lttng-enable-channel(1)). - -For a given tracing session, LTTng only performs an automatic rotation -when no other rotation is currently happening. - - include::common-cmd-footer.txt[] SEE ALSO -------- -man:lttng-rotate(1), +man:lttng(1), +man:lttng-create(1), man:lttng-disable-rotation(1), -man:lttng(1) +man:lttng-rotate(1) diff --git a/doc/man/lttng-event-rule.7.txt b/doc/man/lttng-event-rule.7.txt new file mode 100644 index 000000000..b28d23aae --- /dev/null +++ b/doc/man/lttng-event-rule.7.txt @@ -0,0 +1,808 @@ +lttng-event-rule(7) +=================== +:revdate: 19 April 2021 + + +NAME +---- +lttng-event-rule - Common LTTng event rule specification + + +SYNOPSIS +-------- +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])] +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' +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']... +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'] +pass:[[]option:--log-level=('LOGLEVEL' | 'LOGLEVEL'.. | ..)] [option:--filter='EXPR'] + + +DESCRIPTION +----------- +This manual page shows how to specify an LTTng event rule on the command +line. + +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)). + +[NOTE] +==== +This manual page only describes the common event rule options. The +man:lttng(1) commands which require an event rule specification may +accept or require other options and arguments, depending on the context. + +For example, the man:lttng-add-trigger(1) command also accepts +nloption:--capture options with the `event-rule-matches` trigger +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 +~~~~~~~~~~~~~~~~~~~ +For LTTng to emit an event{nbsp}__E__,{nbsp}__E__ must satisfy *all* the +conditions of an event rule, 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. ++ +See the <> section below. + +* 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. ++ +See the <> section below. + +* The fields of the payload of{nbsp}__E__ and the current context fields + satisfy a filter expression. ++ +See the <> +section below. + +The dedicated command-line options of most conditions are optional: if +you don't specify the option, the associated condition is always +satisfied. + + +[[inst-point-type-cond]] +Instrumentation point type condition +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +An event{nbsp}__E__ satisfies the instrumentation point type condition +of an event rule if the instrumentation point from which LTTng +creates{nbsp}__E__ is: + +For the Linux kernel tracing domain (option:--domain=++kernel++ option):: + With the option:--type=++tracepoint++ option or without any option:--type option::: + An LTTng kernel tracepoint, that is, a statically defined point + in the source code of the kernel image or of a kernel module + with LTTng kernel tracer macros. ++ +As of LTTng{nbsp}{lttng_version}, this is the default instrumentation +point type of the Linux kernel tracing domain, but this may change in +the future. ++ +List the available Linux kernel tracepoints with `lttng list --kernel`. +See man:lttng-list(1) to learn more. + + With the option:--type=++syscall++, option:--type=++syscall:entry++, option:--type=++syscall:exit++, or option:--type=++syscall:entry+exit++ option::: + The entry, exit, or entry and exit 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. + + With the option:--type=++kprobe++ option::: + A Linux kprobe, that is, a single probe dynamically placed in + the compiled kernel code. ++ +You must specify the kprobe location with the option:--location option. ++ +The payload of a Linux kprobe event is empty. + + With the option:--type=++uprobe++ option::: + A Linux user space probe, that is, a single probe dynamically + placed at the entry of a compiled user space application/library + function through the kernel. ++ +LTTng{nbsp}{lttng_version} supports the ELF and SystemTap User-level +Statically Defined Tracing (USDT; a DTrace-style marker) probing +methods. LTTng only supports USDT probes which are :not: +reference-counted. ++ +You must specify the user space probe location with the +option:--location option. ++ +The payload of a Linux user space probe event is empty. + +For the user space tracing domain (option:--domain=++user++ option):: + With or without the option:--type=++tracepoint++ option::: + An LTTng user space tracepoint, that is, a statically defined point + in the source code of a C/$$C++$$ application/library + with LTTng user space tracer macros. ++ +As of LTTng{nbsp}{lttng_version}, this is the default and sole +instrumentation point type of the user space tracing domain, but this +may change in the future. ++ +List the available user space tracepoints with `lttng list --userspace`. +See man:lttng-list(1) to learn more. + +For the `java.util.logging` (option:--domain=++jul++ option), Apache log4j (option:--domain=++log4j++ option), and Python (option:--domain=++python++ option) tracing domains:: + With or without the option:--type=++logging++ option::: + A logging statement. ++ +As of LTTng{nbsp}{lttng_version}, this is the default and sole +instrumentation point type of the `java.util.logging`, Apache log4j, and +Python tracing domains, but this may change in the future. ++ +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. + + +[[event-name-cond]] +Event name condition +~~~~~~~~~~~~~~~~~~~~ +An event{nbsp}__E__ satisfies the event name condition of an event +rule{nbsp}__ER__ if the two following statements are true: + +* You don't specify the option:--name='NAME' option or, depending on the + instrumentation type condition (see the + <> section + above) of{nbsp}__ER__, 'NAME' matches: ++ +-- +LTTng tracepoint:: + The full name of the tracepoint from which LTTng creates{nbsp}__E__. ++ +Note that the full name of a user space tracepoint is +__PROVIDER__++:++__NAME__, where __PROVIDER__ is the tracepoint provider +name and __NAME__ is the tracepoint name. + +Logging statement:: + The name of the Java or Python logger from which LTTng + creates{nbsp}__E__. + +Linux system call:: + The name of the system call, without any `sys_` prefix, from which + LTTng creates{nbsp}__E__. +-- + +* You don't specify any option:--exclude-name='XNAME' option or + none of the 'XNAME' arguments matches the full name of the user space + tracepoint from which LTTng creates{nbsp}__E__. ++ +The option:--exclude-name option is only available with the +option:--domain=++user++ option. + +This condition is only meaningful for the LTTng tracepoint, logging +statement, and Linux system call instrumentation point types: it's +always satisfied for the other types. + +In all cases, 'NAME' and 'XNAME' are globbing patterns: the `*` +character means ``match anything''. To match a literal `*` character, +use :escwc:. + +IMPORTANT: Make sure to **single-quote** 'NAME' and 'XNAME' when they +contain the `*` character and when you run an man:lttng(1) command from +a shell. + +As of LTTng{nbsp}{lttng_version}, not specifying the option:--name +option is equivalent to specifying option:--name=++\'*\'++, but this +default may change in the future. + + +[[inst-point-log-level-cond]] +Instrumentation point log level condition +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +An event{nbsp}__E__ satisfies the instrumentation point log level +condition of an event rule if either: + +* You specify the option:--log-level=++..++ option or you don't specify + the option:--log-level option. ++ +Defaulting to option:--log-level=++..++ when you don't specify the +option:--log-level option is specific to LTTng{nbsp}{lttng_version} and +may change in the future. + +* The log level of the LTTng user space tracepoint or logging statement + from which LTTng creates{nbsp}__E__ is: + With the option:--log-level=__LOGLEVEL__++..++ option:: + At least as severe as 'LOGLEVEL'. + + With the option:--log-level=__LOGLEVEL__ option:: + Exactly 'LOGLEVEL'. + +As of LTTng{nbsp}{lttng_version}, the ++..++__LOGLEVEL__ and +__LOGLEVEL__++..++__LOGLEVEL__ formats are :not: supported. + +This condition is only meaningful for the LTTng user space tracepoint +and logging statement instrumentation point types: it's always satisfied +for other types. + +The available values of 'LOGLEVEL' are, depending on the tracing domain, +from the most to the least severe: + +User space (option:--domain=++user++ option):: + Shortcuts such as `system` are allowed. ++ +* `TRACE_EMERG` (0) +* `TRACE_ALERT` (1) +* `TRACE_CRIT` (2) +* `TRACE_ERR` (3) +* `TRACE_WARNING` (4) +* `TRACE_NOTICE` (5) +* `TRACE_INFO` (6) +* `TRACE_DEBUG_SYSTEM` (7) +* `TRACE_DEBUG_PROGRAM` (8) +* `TRACE_DEBUG_PROCESS` (9) +* `TRACE_DEBUG_MODULE` (10) +* `TRACE_DEBUG_UNIT` (11) +* `TRACE_DEBUG_FUNCTION` (12) +* `TRACE_DEBUG_LINE` (13) +* `TRACE_DEBUG` (14) + +`java.util.logging` (option:--domain=++jul++ option):: + Shortcuts such as `severe` are allowed. ++ +* `JUL_OFF` (`INT32_MAX`) +* `JUL_SEVERE` (1000) +* `JUL_WARNING` (900) +* `JUL_INFO` (800) +* `JUL_CONFIG` (700) +* `JUL_FINE` (500) +* `JUL_FINER` (400) +* `JUL_FINEST` (300) +* `JUL_ALL` (`INT32_MIN`) + +Apache log4j (option:--domain=++log4j++ option):: + Shortcuts such as `severe` are allowed. ++ +* `LOG4J_OFF` (`INT32_MAX`) +* `LOG4J_FATAL` (50000) +* `LOG4J_ERROR` (40000) +* `LOG4J_WARN` (30000) +* `LOG4J_INFO` (20000) +* `LOG4J_DEBUG` (10000) +* `LOG4J_TRACE` (5000) +* `LOG4J_ALL` (`INT32_MIN`) + +Python (option:--domain=++python++ option):: + Shortcuts such as `critical` are allowed. ++ +* `PYTHON_CRITICAL` (50) +* `PYTHON_ERROR` (40) +* `PYTHON_WARNING` (30) +* `PYTHON_INFO` (20) +* `PYTHON_DEBUG` (10) +* `PYTHON_NOTSET` (0) + + +[[filter-cond]] +Event payload and context filter condition +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +An event{nbsp}__E__ satisfies the event payload and context filter +condition of an event rule if the option:--filter='EXPR' option is +missing or if 'EXPR' is _true_. + +'EXPR' can contain references to the payload fields of{nbsp}__E__ and +to the current context fields. + +IMPORTANT: Make sure to **single-quote** 'EXPR' when you run an +man:lttng(1) command from a shell, as filter expressions typically +include characters having a special meaning for most shells. + +The expected syntax of 'EXPR' is similar to the syntax of a +C{nbsp}language conditional expression (an expression which an `if` +statement can evaluate), but there are a few differences: + +* A _NAME_ expression identifies an event payload field named + _NAME_ (a C{nbsp}identifier). ++ +Use the C{nbsp}language dot and square bracket notations to access +nested structure and array/sequence fields. You can only use a constant, +positive integer number within square brackets. If the index is out of +bounds, 'EXPR' is _false_. ++ +The value of an enumeration field is an integer. ++ +When a field expression doesn't exist, 'EXPR' is _false_. ++ +Examples: `my_field`, `target_cpu`, `seq[7]`, `msg.user[1].data[2][17]`. + +* A ++$ctx.++__TYPE__ expression identifies the statically-known context + field having the type _TYPE_ (a C{nbsp}identifier). ++ +List the available statically-known context field names with the +man:lttng-add-context(1) command. ++ +When a field expression doesn't exist, 'EXPR' is _false_. ++ +Examples: `$ctx.prio`, `$ctx.preemptible`, +`$ctx.perf:cpu:stalled-cycles-frontend`. + +* A ++$app.++__PROVIDER__++:++__TYPE__ expression identifies the + application-specific context field having the type _TYPE_ (a + C{nbsp}identifier) from the provider _PROVIDER_ (a C{nbsp}identifier). ++ +When a field expression doesn't exist, 'EXPR' is _false_. ++ +Example: `$app.server:cur_user`. + +* Compare strings, either string fields or string literals + (double-quoted), with the `==` and `!=` operators. ++ +When comparing to a string literal, the `*` character means ``match +anything''. To match a literal `*` character, use :escwc:. ++ +Examples: `my_field == "user34"`, `my_field == my_other_field`, +`my_field == "192.168.*"`. + +* The precedence table of the operators which are supported in 'EXPR' + is as follows. In this table, the highest precedence is{nbsp}1: ++ +[options="header"] +|=== +|Precedence |Operator |Description |Associativity +|1 |`-` |Unary minus |Right-to-left +|1 |`+` |Unary plus |Right-to-left +|1 |`!` |Logical NOT |Right-to-left +|1 |`~` |Bitwise NOT |Right-to-left +|2 |`<<` |Bitwise left shift |Left-to-right +|2 |`>>` |Bitwise right shift |Left-to-right +|3 |`&` |Bitwise AND |Left-to-right +|4 |`^` |Bitwise XOR |Left-to-right +|5 |`\|` |Bitwise OR |Left-to-right +|6 |`<` |Less than |Left-to-right +|6 |`<=` |Less than or equal to |Left-to-right +|6 |`>` |Greater than |Left-to-right +|6 |`>=` |Greater than or equal to |Left-to-right +|7 |`==` |Equal to |Left-to-right +|7 |`!=` |Not equal to |Left-to-right +|8 |`&&` |Logical AND |Left-to-right +|9 |`\|\|` |Logical OR |Left-to-right +|=== ++ +Parentheses are supported to bypass the default order. ++ +IMPORTANT: Unlike the C{nbsp}language, the bitwise AND and OR operators +(`&` and `|`) in 'EXPR' take precedence over relational operators (`<`, +`<=`, `>`, `>=`, `==`, and `!=`). This means the expression `2 & 2 == 2` +is _true_ while the equivalent C{nbsp}expression is _false_. ++ +The arithmetic operators are :not: supported. ++ +LTTng first casts all integer constants and fields to signed 64-bit +integers. The representation of negative integers is two's complement. +This means that, for example, the signed 8-bit integer field 0xff (-1) +becomes 0xffffffffffffffff (still -1) once casted. ++ +Before a bitwise operator is applied, LTTng casts all its operands to +unsigned 64-bit integers, and then casts the result back to a signed +64-bit integer. For the bitwise NOT operator, it's the equivalent of +this C{nbsp}expression: ++ +[source,c] +---- +(int64_t) ~((uint64_t) val) +---- ++ +For the binary bitwise operators, it's the equivalent of those +C{nbsp}expressions: ++ +[source,c] +---- +(int64_t) ((uint64_t) lhs >> (uint64_t) rhs) +(int64_t) ((uint64_t) lhs << (uint64_t) rhs) +(int64_t) ((uint64_t) lhs & (uint64_t) rhs) +(int64_t) ((uint64_t) lhs ^ (uint64_t) rhs) +(int64_t) ((uint64_t) lhs | (uint64_t) rhs) +---- ++ +If the right-hand side of a bitwise shift operator (`<<` and `>>`) is +not in the [0,{nbsp}63] range, then 'EXPR' is _false_. + +'EXPR' examples: + +---------------------------- +msg_id == 23 && size >= 2048 +---------------------------- + +------------------------------------------------- +$ctx.procname == "lttng*" && (!flag || poel < 34) +------------------------------------------------- + +--------------------------------------------------------- +$app.my_provider:my_context == 17.34e9 || some_enum >= 14 +--------------------------------------------------------- + +--------------------------------------- +$ctx.cpu_id == 2 && filename != "*.log" +--------------------------------------- + +------------------------------------------------ +eax_reg & 0xff7 == 0x240 && x[4] >> 12 <= 0x1234 +------------------------------------------------ + + +Migration from a recording event rule specification +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Since LTTng{nbsp}2.13, what this manual page documents is the standard, +common way to specify an LTTng event rule. + +With the man:lttng-enable-event(1) command, you also specify an event +rule, but with deprecated options and arguments. + +The following table shows how to translate from the +man:lttng-enable-event(1) options and arguments to the common event +rule specification options: + +[options="header"] +|=== +|Recording event rule option(s)/argument(s) |Common event rule option(s) + +|nloption:--kernel |option:--domain=++kernel++ +|nloption:--userspace |option:--domain=++user++ +|nloption:--jul |option:--domain=++jul++ +|nloption:--log4j |option:--domain=++log4j++ +|nloption:--python |option:--domain=++python++ +|nloption:--tracepoint (with nloption:--kernel/nloption:--userspace) |option:--type=++tracepoint++ or no option:--type option +|nloption:--tracepoint (with nloption:--jul/nloption:--log4j/nloption:--python) |option:--type=++logging++ or no option:--type option +|nloption:--syscall |option:--type=++syscall++ or option:--type=++syscall:entry+exit++ +|nloption:--probe='LOC' and 'RECORDNAME' (non-option) |option:--type=++kprobe++, option:--location='LOC', and option:--event-name='RECORDNAME' +|nloption:--userspace-probe='LOC' and 'RECORDNAME' (non-option) |option:--type=++uprobe++, option:--location='LOC', and option:--event-name='RECORDNAME' +|nloption:--function='LOC' and 'RECORDNAME' (non-option) |Not available as of LTTng{nbsp}{lttng_version} +|'NAME' (non-option) |option:--name='NAME' +|nloption:--all |option:--name=++\'*\'++ or no option:--name option +|nloption:--exclude=__XNAME__[++,++__XNAME__]... |option:--exclude-name='XNAME' for each 'XNAME' +|nloption:--loglevel='LOGLEVEL' |option:--log-level=__LOGLEVEL__++..++ +|nloption:--loglevel-only='LOGLEVEL' |option:--log-level=__LOGLEVEL__ +|nloption:--filter='EXPR' |option:--filter='EXPR' +|=== + + +OPTIONS +------- +Tracing domain +~~~~~~~~~~~~~~ +option:-d 'DOMAIN', option:--domain='DOMAIN':: + Only match events which LTTng creates in the tracing domain + 'DOMAIN'. ++ +'DOMAIN' is one of: ++ +-- +`kernel`::: + Linux kernel +`user`::: +`userspace`::: + User space tracing +`jul`::: + `java.util.logging` +`log4j`::: + Apache log4j +`python`::: + Python +-- ++ +This option is mandatory. + + +Instrumentation point type condition +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +See the <> +section above. + +option:-E 'NAME', option:--event-name='NAME':: + With the option:--type=++kprobe++ or option:--type=++uprobe++ + option, set the name of the emitted events to 'NAME' instead of the + 'LOC' argument of the option:--location='LOC' option. ++ +Defaulting to 'LOC' is specific to LTTng{nbsp}{lttng_version} and may +change in the future. + +option:-L 'LOC', option:--location='LOC':: + With the option:--type=++kprobe++ option::: + Set the location of the Linux kprobe to insert to 'LOC'. ++ +'LOC' is one of: ++ +* An address (`0x` hexadecimal prefix supported). +* A symbol name. +* A symbol name and an offset (__SYMBOL__++pass:[+]++__OFFSET__ format). + + With the option:--type=++uprobe++ option::: + Set the location of the user space probe to insert to 'LOC'. ++ +'LOC' is one of: ++ +\[++elf:++]__PATH__++:++__SYMBOL__:::: + An available symbol within a user space application or library. ++ +-- +'PATH':: + Application or library path. ++ +One of: ++ +* An absolute path. +* A relative path. +* The name of an application as found in the directories listed in the + `PATH` environment variable. + +'SYMBOL':: + Symbol name of the function of which to instrument the entry. ++ +'SYMBOL' can be any defined code symbol in the output of the man:nm(1) +command, including with its nloption:--dynamic option, which lists +dynamic symbols. +-- ++ +As of LTTng{nbsp}{lttng_version}, not specifying `elf:` is equivalent to +specifying it, but this default may change in the future. ++ +Examples: ++ +* `/usr/lib/libc.so.6:malloc` +* `./myapp:createUser` +* `elf:httpd:ap_run_open_htaccess` + +++sdt:++__PATH__++:++__PROVIDER__++:++__NAME__:::: + A SystemTap User-level Statically Defined Tracing (USDT) probe + within a user space application or library. ++ +-- +'PATH':: + Application or library path. ++ +This can be: ++ +* An absolute path. +* A relative path. +* The name of an application as found in the directories listed in the + `PATH` environment variable. + +'PROVIDER':: +'NAME':: + USDT provider and probe names. ++ +For example, with the following USDT probe: ++ +[source,c] +---- +DTRACE_PROBE2("server", "accept_request", + request_id, ip_addr); +---- ++ +The provider/probe name pair is `server:accept_request`. +-- ++ +Example: `sdt:./build/server:server:accept_request` + +option:-t 'TYPE', option:--type='TYPE':: + Only match events which LTTng creates from an instrumentation point + having the type 'TYPE'. ++ +'TYPE' is one of: ++ +-- +`tracepoint`:: + LTTng tracepoint. ++ +Only available with the option:--domain=++kernel++ and +option:--domain=++user++ options. ++ +As of LTTng{nbsp}{lttng_version}, this is the default instrumentation +point type of the Linux kernel and user space tracing domains, but this +may change in the future. + +`logging`:: + Logging statement. ++ +Only available with the option:--domain=++jul++, +option:--domain=++log4j++, and option:--domain=++python++ options. ++ +As of LTTng{nbsp}{lttng_version}, this is the default instrumentation +point type of the `java.util.logging`, Apache log4j, and Python tracing +domains, but this may change in the future. + +`syscall`:: + As of LTTng{nbsp}{lttng_version}, equivalent to + `syscall:entry+exit`, but this default may change in the future. ++ +Only available with the option:--domain=++kernel++ option. + +`syscall:entry`:: + Linux system call entry. ++ +Only available with the option:--domain=++kernel++ option. + +`syscall:exit`:: + Linux system call exit. ++ +Only available with the option:--domain=++kernel++ option. + +`syscall:entry+exit`:: + Linux system call entry and exit (two distinct instrumentation + points). ++ +Only available with the option:--domain=++kernel++ option. + +`kprobe`:: + Linux kprobe. ++ +Only available with the option:--domain=++kernel++ option. ++ +You must specify the location of the kprobe to insert with the +option:--location option. ++ +You may specify the name of the emitted events with the +option:--event-name option. + +`uprobe` or `userspace-probe`:: + Linux user space probe. ++ +Only available with the option:--domain=++kernel++ option. ++ +You must specify the location of the user space probe to insert with the +option:--location option. ++ +You may specify the name of the emitted events with the +option:--event-name option. +-- + + +Event name condition +~~~~~~~~~~~~~~~~~~~~ +See the <> section above. + +option:-n 'NAME', option:--name='NAME':: + Only match events of which 'NAME' matches: ++ +-- +With the option:--domain=++kernel++ or option:--domain=++user++ option, with the option:--type=++tracepoint++ option or without the option:--type option::: + The full name of the LTTng tracepoint. + +With the option:--domain=++jul++, option:--domain=++log4j++, or option:--domain=++python++ option::: + The Java or Python logger name. + +With the option:--domain=++kernel++ option and one of the option:--type=++syscall++, option:--type=++syscall:entry++, option:--type=++syscall:exit++, and option:--type=++syscall:entry+exit++ options::: + The name of the system call, without any `sys_` prefix. +-- ++ +This option is :not: available with the option:--type=++kprobe++ and +option:--type=++uprobe++ options. ++ +As of LTTng{nbsp}{lttng_version}, not specifying this option is +equivalent to specifying option:--name=++\'*\'++ (when it applies), but +this default may change in the future. + +option:-x 'XNAME', option:--exclude='XNAME':: + Only match events of which 'XNAME' does :not: match the full name of + the LTTng user space tracepoint. ++ +Only available with the option:--domain=++user++ option. + +'NAME' and 'XNAME' are globbing patterns: the `*` character means +``match anything''. To match a literal `*` character, use :escwc:. + + +Instrumentation point log level condition +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +See the <> section above. + +option:-l 'LOGLEVELSPEC', option:--log-level='LOGLEVELSPEC':: + Only match events of which the log level of the LTTng tracepoint or + logging statement is, depending on the format of 'LOGLEVELSPEC': ++ +-- +__LOGLEVEL__++..++:: + At least as severe as 'LOGLEVEL'. + +'LOGLEVEL':: + Exactly 'LOGLEVEL'. + +++..++:: + Anything. +-- ++ +This option is :not: available with the option:--domain=++kernel++ +option. ++ +As of LTTng{nbsp}{lttng_version}, not specifying this option is +equivalent to specifying option:--log-level=++..++ (when it applies), +but this default may change in the future. + + +Event payload and context filter condition +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +See the <> +section above. + +option:-f 'EXPR', option:--filter='EXPR':: + Only match events of which 'EXPR', which can contain references to + event payload and current context fields, is _true_. + + +SEE ALSO +-------- +man:lttng(1), +man:lttng-add-trigger(1) diff --git a/doc/man/lttng-help.1.txt b/doc/man/lttng-help.1.txt index 65b909dd9..1de72c55b 100644 --- a/doc/man/lttng-help.1.txt +++ b/doc/man/lttng-help.1.txt @@ -1,11 +1,11 @@ lttng-help(1) ============= -:revdate: 14 March 2017 +:revdate: 21 April 2021 NAME ---- -lttng-help - Display help information about an LTTng command +lttng-help - Show the help of an LTTng command SYNOPSIS @@ -16,23 +16,22 @@ SYNOPSIS DESCRIPTION ----------- -The `lttng help` command displays help information about an LTTng -command. +The `lttng help` command shows the help of: -This command is the equivalent of: +With the 'COMMAND' argument:: + The ++lttng{nbsp}++__COMMAND__ command. -[role="term"] ----- -$ lttng COMMAND --help ----- +Without the 'COMMAND' argument:: + The man:lttng(1) command itself. -where `COMMAND` is the name of the command about which to get help. If -'COMMAND' is omitted, `lttng help` shows general help about the -man:lttng(1) command. +The `help` command is equivalent to: + +[verse] +*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] ['COMMAND'] --help -The `lttng help` command attempts to launch `/usr/bin/man` to view -the command's man page. The path to the man pager can be overridden -by the `LTTNG_MAN_BIN_PATH` environment variable. +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 +`LTTNG_MAN_BIN_PATH` environment variable. include::common-cmd-options-head.txt[] diff --git a/doc/man/lttng-list-triggers.1.txt b/doc/man/lttng-list-triggers.1.txt index 2ab3085cd..f6308141d 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: 20 January 2020 +:revdate: 3 March 2021 NAME @@ -10,23 +10,22 @@ lttng-list-triggers - List LTTng triggers SYNOPSIS -------- - [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *list-triggers* DESCRIPTION ----------- +The `lttng list-triggers` command lists the available LTTng triggers +of your Unix user and their properties. -The `lttng list-triggers` command list the existing triggers. +See man:lttng-add-trigger(1) to learn more about triggers. OPTIONS ------- - include::common-cmd-help-options.txt[] - include::common-cmd-footer.txt[] diff --git a/doc/man/lttng-list.1.txt b/doc/man/lttng-list.1.txt index 0cb19fe48..af3b13f71 100644 --- a/doc/man/lttng-list.1.txt +++ b/doc/man/lttng-list.1.txt @@ -26,7 +26,7 @@ List tracing session's domains: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *list* option:--domain 'SESSION' -List tracing session's channels and event rules: +List tracing session's channels and recording event rules: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *list* [option:--channel='CHANNEL'] 'SESSION' @@ -52,10 +52,10 @@ 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 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. +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. include::common-cmd-options-head.txt[] diff --git a/doc/man/lttng-load.1.txt b/doc/man/lttng-load.1.txt index 691437dd7..253b86d3c 100644 --- a/doc/man/lttng-load.1.txt +++ b/doc/man/lttng-load.1.txt @@ -23,8 +23,8 @@ 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 event rules, the context added to channels, the tracing activity, -and more. +and recording event rules, the context added to channels, the tracing +activity, and more. Once one or more tracing session configurations are loaded, they appear exactly as they were saved from the user's point of view. diff --git a/doc/man/lttng-relayd.8.txt b/doc/man/lttng-relayd.8.txt index 4f911eb49..5171b93d9 100644 --- a/doc/man/lttng-relayd.8.txt +++ b/doc/man/lttng-relayd.8.txt @@ -64,7 +64,7 @@ Consider the following variables: Base output directory: `$LTTNG_HOME/lttng-traces` or the argument of the option:--output option. + -NOTE: `$LTTNG_HOME` defaults to `$HOME` when not explicitly set. +NOTE: `$LTTNG_HOME` defaults to `$HOME`. 'HOSTNAME':: Peer's hostname. @@ -331,7 +331,7 @@ FILES Default base output directory of LTTng traces. This can be overridden with the option:--output option. -NOTE: `$LTTNG_HOME` defaults to `$HOME` when not explicitly set. +NOTE: `$LTTNG_HOME` defaults to `$HOME`. EXIT STATUS diff --git a/doc/man/lttng-remove-trigger.1.txt b/doc/man/lttng-remove-trigger.1.txt index 645ef152f..a0dfb5709 100644 --- a/doc/man/lttng-remove-trigger.1.txt +++ b/doc/man/lttng-remove-trigger.1.txt @@ -1,29 +1,43 @@ lttng-remove-trigger(1) -======================== -:revdate: 20 January 2020 +======================= +:revdate: 5 March 2021 NAME ---- -lttng-remove-trigger - Remove LTTng triggers +lttng-remove-trigger - Remove an LTTng trigger SYNOPSIS -------- - [verse] -*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *remove-trigger* 'ID' +*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *remove-trigger* [option:--owner-id='UID'] 'NAME' DESCRIPTION ----------- +The `lttng remove-trigger` command removes the trigger named 'NAME'. + +See man:lttng-add-trigger(1) to learn more about LTTng triggers. -The `lttng remove-trigger` command removes the trigger with the given -'ID'. +List the available triggers and their name 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 +user with the option:--owner-id option. OPTIONS ------- +Identification +~~~~~~~~~~~~~~ +option:--owner-id='UID':: + Remove the trigger named 'NAME' of the Unix user having the user ID + 'UID'. ++ +You may only use this option if your Unix user is `root`. + include::common-cmd-help-options.txt[] @@ -34,5 +48,5 @@ include::common-cmd-footer.txt[] SEE ALSO -------- man:lttng-add-trigger(1), -man:lttng-list-trigger(1), +man:lttng-list-triggers(1), man:lttng(1) diff --git a/doc/man/lttng-save.1.txt b/doc/man/lttng-save.1.txt index 6bb607f4f..1f526ef66 100644 --- a/doc/man/lttng-save.1.txt +++ b/doc/man/lttng-save.1.txt @@ -22,9 +22,9 @@ tracing sessions to files. 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 event rules, the context added to channels, the tracing activity, -and more. `lttng save` does not save tracing data, only the tracing -session parameters. +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. If 'SESSION' is omitted, all the existing tracing session configurations are saved (equivalent to using the option:--all option). Otherwise, diff --git a/doc/man/lttng-sessiond.8.txt b/doc/man/lttng-sessiond.8.txt index c35ccdccf..8edb004b7 100644 --- a/doc/man/lttng-sessiond.8.txt +++ b/doc/man/lttng-sessiond.8.txt @@ -1,11 +1,11 @@ lttng-sessiond(8) ================= -:revdate: 17 September 2018 +:revdate: 21 April 2021 NAME ---- -lttng-sessiond - LTTng 2 tracing session daemon +lttng-sessiond - LTTng session daemon SYNOPSIS @@ -25,134 +25,197 @@ SYNOPSIS [option:--ustconsumerd64-cmd-sock='PATH'] [option:--consumerd32-path='PATH'] [option:--consumerd32-libdir='PATH'] [option:--consumerd64-path='PATH'] [option:--consumerd64-libdir='PATH'] - [option:--event-notifier-error-buffer-size-kernel='SIZE'] - [option:--event-notifier-error-buffer-size-userspace='SIZE'] - [option:--quiet | [option:-v | option:-vv | option:-vvv] [option:--verbose-consumer]] + [option:--event-notifier-error-buffer-size-kernel='SLOTS'] + [option:--event-notifier-error-buffer-size-userspace='SLOTS'] + [option:--quiet | [option:--verbose]... [option:--verbose-consumer]] 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 session daemon, `lttng-sessiond`, is a program which: -The _LTTng session daemon_ is a tracing registry which allows the user -to interact with multiple tracers (kernel and user space) within the -same container, a _tracing session_. Traces can be gathered from the -Linux kernel and/or from instrumented applications (see -man:lttng-ust(3)). You can aggregate and read the events of LTTng -traces using man:babeltrace2(1). +* Manages tracing sessions (see man:lttng-create(1) to learn more about + tracing sessions). -To trace the Linux kernel, the session daemon needs to be running as -`root`. LTTng uses a _tracing group_ to allow specific users to interact -with the root session daemon. The default tracing group name is -`tracing`. You can use the option:--group option to set the tracing -group name to use. +* Controls the various components (like tracers and consumer daemons) of + LTTng. -Session daemons can coexist. You can have a session daemon running as -user Alice that can be used to trace her applications alongside a root -session daemon or a session daemon running as user Bob. +* Sends asynchronous notifications to user applications. -The LTTng session daemon manages trace data consumer daemons by spawning -them when necessary. You do not need to manage the consumer daemons -manually. +A session daemon receives commands from the man:lttng(1) command-line +tool, as well as from any user application linked with the LTTng control +library (`liblttng-ctl`). -NOTE: It is highly recommended to start the session daemon at boot time -for stable and long-term tracing. +Each Unix user may have its own independent running session daemon. +However, the man:lttng(1) tool must connect to the session daemon of the +`root` user (the root session daemon) to control Linux kernel tracing. +When you start `lttng-sessiond` as the `root` Unix user, a non-root Unix +user can connect to it if it's part of the Unix tracing group. By +default, the name of the tracing group is `tracing`. Override the +tracing group name with the option:--group option. -Automatic loading of tracing session configurations -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -When the session daemon starts, it automatically loads session -configuration files. +See the ``Session daemon connection'' section of man:lttng(1) to learn +how a user application connects to a session daemon. -The following directories are searched, non-recursively, in this order -for configuration files to load on launch: +A session daemon manages trace data consumer daemons, spawning them when +necessary. You do :not: need to manage the consumer daemons yourself. -. `$LTTNG_HOME/.lttng/sessions/auto` (`$LTTNG_HOME` defaults to `$HOME`) -. +{system_sessions_auto_dir}+ +By default, `lttng-sessiond` doesn't start as a daemon. Make it a daemon +with the option:--daemonize or option:--background option. With those +options, `lttng-sessiond` ensures the daemon is ready to receive client +commands before it exits. -Note that both the directory containing the tracing session -configurations _and_ the session daemon binary _must_ share the same UID -for the configurations to be automatically loaded. +NOTE: The LTTng project recommends that you start the session daemon at +boot time for stable and long-term tracing. -The option:--load option overrides the default directories _and_ the UID -check. The session daemon simply checks if the path is accessible and -tries to load every tracing session configuration in it. When this -option is specified, the default directories are :not: searched for -configuration files. When the option is not specified, _both_ default -directories are searched for configuration files. -If the option:--load option's argument is a directory, then all the -tracing session configurations found in all the files in this directory -are loaded. If the argument is a file, then all the tracing session -configurations found in this file are loaded. +[[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). + + The selected command-line option is a switch::: + `true`:::: + `yes`:::: + `on`:::: + Enable the option. + + `false`:::: + `no`:::: + `off`:::: + Disable the option. + +INI configuration file example: + +[source,ini] +---- +[sessiond] +daemonize=yes +extra-kmod-probes=my-driver,other-module +---- + + +[[load]] +Tracing session configuration loading +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +When the session daemon starts, it loads tracing session configurations +from: +Without the option:--load option:: + In this order: ++ +-- +. All the files in `$LTTNG_HOME/.lttng/sessions/auto`. ++ +`$LTTNG_HOME` defaults to `$HOME`. + +. All the files in +{system_sessions_auto_dir}+. +-- ++ +`lttng-sessiond` only loads tracing configuration files from the +directories above if its UID and their UID are the same. +With the option:--load='PATH' option:: + 'PATH' is a directory::: + All the files in 'PATH'. + + 'PATH' is a file::: + The file 'PATH'. + + +[[options]] OPTIONS ------- 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-sessiond` ensures the daemon is ready to +receive client commands before it exits. ++ +Use the option:--daemonize option instead to close the file descriptors. option:-f 'PATH', option:--config='PATH':: - Load session 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-sessiond` ensures the daemon is ready to +receive client commands before it exits. ++ +Use the option:--background option instead to keep the file descriptors +open. 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-sessiond`. ++ +Members of the Unix tracing group may connect to the root session daemon +and, therefore, control LTTng kernel tracing. option:-l 'PATH', option:--load='PATH':: - Automatically load tracing session configurations from 'PATH', - either a directory or a file, instead of loading them from the - default search directories. + Load tracing session configurations from 'PATH', either a directory + or a file, instead of loading them from the default search + directories. ++ +See the <> section above. option:-S, option:--sig-parent:: - Send `SIGUSR1` to parent process to notify readiness. + Send the `USR1` signal to the parent process to notify readiness. + -NOTE: This is used by man:lttng(1) to get notified when the -session daemon is ready to accept commands. When building a third party -tool on liblttng-ctl, this option can be very handy to synchronize the -control tool and the session daemon. - -option:--event-notifier-error-buffer-size-kernel='SIZE':: - Set the size of the kernel event notifier error counter buffers to 'SIZE. - -option:--event-notifier-error-buffer-size-userspace='SIZE':: - Set the size of the userspace event notifier error counter buffers to - 'SIZE. +You can also use the option:--daemonize or option:--background option, +in which case `lttng-sessiond` ensures the daemon is ready to receive +client commands before it exits. Linux kernel tracing ~~~~~~~~~~~~~~~~~~~~ +At most one of: + option:--extra-kmod-probes='PROBE'[,'PROBE']...:: - Load specific LTTng Linux kernel modules when kernel tracing - is enabled (option:--no-kernel option is :not: specified), in - addition to loading the default list of LTTng kernel modules. -+ -Only the name of the probe needs to be specified, without the -`lttng-probe-` prefix and without the kernel module extension suffix. -For example, specify `sched` to load the `lttng-probe-sched.ko` kernel -module. + 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. option:--kmod-probes='PROBE'[,'PROBE']...:: - Only load specific LTTng Linux kernel modules when kernel tracing - is enabled (option:--no-kernel option is :not: specified). -+ -Only the name of the probe needs to be specified, without the -`lttng-probe-` prefix and without the kernel module extension suffix. -For example, specify `sched` to load the `lttng-probe-sched.ko` kernel -module. + 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. option:--no-kernel:: Disable Linux kernel tracing. @@ -161,88 +224,112 @@ option:--no-kernel:: Paths and ports ~~~~~~~~~~~~~~~ option:--agent-tcp-port='PORT':: - Listen on TCP port 'PORT' for agent application registrations - (default: a port within the range + Listen on TCP port 'PORT' for agent application registration + instead of a port within the range [{default_agent_tcp_port_range_begin},{nbsp}{default_agent_tcp_port_range_end}]). option:-a 'PATH', option:--apps-sock='PATH':: - Set application Unix socket path to 'PATH'. + Set the application Unix socket path to 'PATH'. option:-c 'PATH', option:--client-sock='PATH':: - Set client Unix socket path to 'PATH'. + Set the client Unix socket path to 'PATH'. option:--consumerd32-libdir='PATH':: - Set 32-bit consumer daemon library directory to 'PATH'. + Set the 32-bit consumer daemon library directory to 'PATH'. option:--consumerd32-path='PATH':: - Set 32-bit consumer daemon binary path to 'PATH'. + Set the 32-bit consumer daemon binary path to 'PATH'. option:--consumerd64-libdir='PATH':: - Set 64-bit consumer daemon library directory to 'PATH'. + Set the 64-bit consumer daemon library directory to 'PATH'. option:--consumerd64-path='PATH':: - Set 64-bit consumer daemon binary path to 'PATH'. + Set the 64-bit consumer daemon binary path to 'PATH'. option:--kconsumerd-cmd-sock='PATH':: - Set Linux kernel consumer daemon's command Unix socket path + Set the command Unix socket path of the Linux kernel consumer daemon to 'PATH'. option:--kconsumerd-err-sock='PATH':: - Set Linux kernel consumer daemon's error Unix socket path + Set the error Unix socket path of the Linux kernel consumer daemon to 'PATH'. option:--ustconsumerd32-cmd-sock='PATH':: - Set 32-bit consumer daemon's command Unix socket path to 'PATH'. + Set the Unix socket path of the 32-bit consumer daemon command to + 'PATH'. option:--ustconsumerd64-cmd-sock='PATH':: - Set 64-bit consumer daemon's command Unix socket path to 'PATH'. + Set the Unix socket path of the 64-bit consumer daemon command to + 'PATH'. option:--ustconsumerd32-err-sock='PATH':: - Set 32-bit consumer daemon's error Unix socket path to 'PATH'. + Set the Unix socket path of the 32-bit consumer daemon error to + 'PATH'. option:--ustconsumerd64-err-sock='PATH':: - Set 64-bit consumer daemon's error Unix socket path to 'PATH'. + Set the Unix socket path of the 64-bit consumer daemon error to + 'PATH'. + + +Buffer size of event notifier error counters +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +option:--event-notifier-error-buffer-size-kernel='SLOTS':: + Set the size of the kernel event notifier error counter buffers to + 'SLOTS'{nbsp}slots. + +option:--event-notifier-error-buffer-size-userspace='SLOTS':: + Set the size of the user space event notifier error counter buffers + to 'SLOTS'{nbsp}slots. + +As of LTTng{nbsp}{lttng_version}, a _slot_ is a 32-bit counter, but this +may change in the future. Verbosity ~~~~~~~~~ option:-q, option:--quiet:: Suppress all messages, including warnings and errors. ++ +You may :not: use this option with the option:--verbose and +option:--verbose-consumer options. 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. ++ +You may :not: use this option with the option:--quiet option. option:--verbose-consumer:: - Increase verbosity of consumer daemons spawned by this session - daemon. + Increase the verbosity of the consumer daemons which this session + daemon spawns. ++ +You may :not: use this option with the option:--quiet option. 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 --------------------- -Note that command-line options override their equivalent environment -variable. - `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_APP_SOCKET_TIMEOUT`:: - Application socket's timeout (seconds) when sending/receiving - commands. After this period of time, the application is unregistered - by the session daemon. A value of 0 or -1 means an infinite timeout. - Default value: {default_app_socket_rw_timeout}. + Timeout (in seconds) of the application socket when + sending/receiving commands. ++ +After this period of time, `lttng-sessiond` unregisters the application. ++ +Set to `0` or `-1` to set an infinite timeout. ++ +Default: +{default_app_socket_rw_timeout}+. `LTTNG_CONSUMERD32_BIN`:: 32-bit consumer daemon binary path. @@ -250,7 +337,7 @@ variable. The option:--consumerd32-path option overrides this variable. `LTTNG_CONSUMERD32_LIBDIR`:: - 32-bit consumer daemon library path. + 32-bit consumer daemon library directory path. + The option:--consumerd32-libdir option overrides this variable. @@ -260,31 +347,32 @@ The option:--consumerd32-libdir option overrides this variable. The option:--consumerd64-path option overrides this variable. `LTTNG_CONSUMERD64_LIBDIR`:: - 64-bit consumer daemon library path. + 64-bit consumer daemon library directory path. + The option:--consumerd64-libdir option overrides this variable. `LTTNG_DEBUG_NOCLONE`:: - Set to 1 to disable the use of `clone()`/`fork()`. Setting this - variable is considered insecure, but it is required to allow - debuggers to work with the session daemon on some operating systems. + 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. `LTTNG_EXTRA_KMOD_PROBES`:: - Load specific LTTng Linux kernel modules when kernel tracing - is enabled (option:--no-kernel option is :not: specified), in - addition to loading the default list of LTTng kernel modules. + Extra LTTng kernel probe modules to load. + -The option:--extra-kmod-probes option overrides this variable. +See the option:--extra-kmod-probes option which overrides this +environment variable. `LTTNG_KMOD_PROBES`:: - Only load specific LTTng Linux kernel modules when kernel tracing - is enabled (option:--no-kernel option is :not: specified). + Exclusive LTTng kernel probe modules to load. + -The option:--kmod-probes option overrides this variable. +See the option:--kmod-probes option which overrides this environment +variable. `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 use the timeout of the operating system (default). `LTTNG_SESSION_CONFIG_XSD_PATH`:: Tracing session configuration XML schema definition (XSD) path. @@ -293,34 +381,40 @@ The option:--kmod-probes option overrides this variable. FILES ----- `$LTTNG_HOME/.lttng`:: - User LTTng runtime and configuration directory. + Unix user's LTTng runtime and configuration directory. `$LTTNG_HOME/lttng-traces`:: - Default output directory of LTTng traces. This can be overridden - with the nloption:--output option of the man:lttng-create(1) - command. + Default output directory of LTTng traces in local and snapshot + modes. ++ +Override this path with the nloption:--output option of the +man:lttng-create(1) command. `$LTTNG_HOME/.lttng/sessions/auto`:: - Directory from which user tracing configuration files are - automatically loaded when the session daemon starts (see - man:lttng-save(1) and man:lttng-load(1) for saving - and loading tracing sessions). + Directory from which `lttng-sessiond` loads Unix user tracing + session configurations when starting. ++ +See the <> section above to +learn more. +{system_sessions_auto_dir}+:: - Directory from which system-wide tracing configuration files are - automatically loaded when the session daemon starts (see - man:lttng-save(1) and man:lttng-load(1) for saving - and loading tracing sessions). + Directory from which `lttng-sessiond` loads system-wide tracing + session configurations when starting. ++ +See the <> section above to +learn more. `$LTTNG_HOME/.lttng/lttng.conf`:: - Default location of the session daemon configuration file (see the - option:--config option). + Unix user's LTTng daemon INI configuration file. ++ +See the <> section above to learn more. +{system_lttng_conf}+:: - System-wide location of the session daemon configuration file (see - the option:--config option). + System-wide LTTng daemon INI configuration file. ++ +See the <> section above to learn more. -NOTE: `$LTTNG_HOME` defaults to `$HOME` when not explicitly set. +NOTE: `$LTTNG_HOME` defaults to `$HOME`. EXIT STATUS @@ -337,14 +431,13 @@ EXIT STATUS LIMITATIONS ----------- -For an unprivileged 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 -is two file descriptors per CPU and one more socket for bidirectional -communication. +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 bumped to 65535. A future version will -deal with this limitation. +For the `root` user, the limit is usually 65,535. include::common-footer.txt[] @@ -352,8 +445,4 @@ include::common-footer.txt[] SEE ALSO -------- -man:lttng(1), -man:lttng-relayd(8), -man:lttng-crash(1), -man:lttng-ust(3), -man:babeltrace2(1) +man:lttng(1) diff --git a/doc/man/lttng-set-session.1.txt b/doc/man/lttng-set-session.1.txt index 068a66f33..2e97c055b 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: 7 April 2016 +:revdate: 21 April 2021 NAME @@ -16,14 +16,39 @@ SYNOPSIS DESCRIPTION ----------- -The `lttng set-session` command sets the current tracing session. - -'SESSION' is the name of an existing tracing session. `lttng list` -outputs all the existing tracing sessions (see man:lttng-list(1)). - -The current tracing session is used by default when a session can be -specified in other commands. See man:lttng-create(1) for more -information about the current tracing session. +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) + +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. include::common-cmd-options-head.txt[] diff --git a/doc/man/lttng-start.1.txt b/doc/man/lttng-start.1.txt index a6868f160..a5f8c2f50 100644 --- a/doc/man/lttng-start.1.txt +++ b/doc/man/lttng-start.1.txt @@ -1,11 +1,11 @@ lttng-start(1) ============== -:revdate: 7 April 2016 +:revdate: 21 April 2021 NAME ---- -lttng-start - Start LTTng tracers +lttng-start - Start an LTTng tracing session SYNOPSIS @@ -16,25 +16,28 @@ SYNOPSIS DESCRIPTION ----------- -The `lttng start` command starts the various LTTng tracers for a -given inactive tracing session. +The `lttng start` command starts a tracing session, that is, it +activates the LTTng tracers for: -Starting the LTTng tracers has the effect that all enabled event rules -within enabled channels can make their target event sources _emit_ trace -events. Whether they are recorded to the local file system, sent over -the network, or not recorded at all depends on the specific -configuration of the tracing session in which tracing is started. See -man:lttng-create(1) for different session modes. +With the 'SESSION' argument:: + The tracing session named 'SESSION'. -A tracing session with running tracers is said to be _active_. Active -tracing sessions can return to the inactive state using the -man:lttng-stop(1) command. +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). -If 'SESSION' is omitted, the LTTng tracers are started for the current -tracing session (see man:lttng-create(1) for more information -about the current tracing session). Otherwise, they are started for the -existing tracing session named 'SESSION'. `lttng list` -outputs all the existing tracing sessions (see man:lttng-list(1)). +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)). + +Stop an active tracing session with the man:lttng-stop(1) command. include::common-cmd-options-head.txt[] @@ -48,5 +51,8 @@ include::common-cmd-footer.txt[] SEE ALSO -------- -man:lttng-stop(1), -man:lttng(1) +man:lttng(1), +man:lttng-add-trigger(1), +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 05e5bc550..caeac9703 100644 --- a/doc/man/lttng-status.1.txt +++ b/doc/man/lttng-status.1.txt @@ -1,11 +1,11 @@ lttng-status(1) =============== -:revdate: 14 March 2017 +:revdate: 21 April 2021 NAME ---- -lttng-status - Get the current LTTng tracing session's status +lttng-status - Show the status of the current LTTng tracing session SYNOPSIS @@ -16,18 +16,16 @@ SYNOPSIS DESCRIPTION ----------- -The `lttng status` command shows the status of the current -tracing session. +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). -This command is the exact equivalent of: +This command is equivalent to: -[role="term"] ----- -$ lttng list CURSESSION ----- +[verse] +*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *list* 'CURSESSION' where `CURSESSION` is the name of the current tracing session. -Use man:lttng-set-session(1) to set the current tracing session. include::common-cmd-options-head.txt[] @@ -41,5 +39,7 @@ include::common-cmd-footer.txt[] SEE ALSO -------- -man:lttng-set-session(1), -man:lttng(1) +man:lttng(1), +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 55afcd348..5c21c6ce4 100644 --- a/doc/man/lttng-stop.1.txt +++ b/doc/man/lttng-stop.1.txt @@ -1,11 +1,11 @@ lttng-stop(1) ============= -:revdate: 18 January 2018 +:revdate: 21 April 2021 NAME ---- -lttng-stop - Stop LTTng tracers +lttng-stop - Stop an LTTng tracing session SYNOPSIS @@ -16,45 +16,52 @@ SYNOPSIS DESCRIPTION ----------- -The `lttng stop` command stops the various LTTng tracers for a given -active tracing session. - -Stopping the LTTng tracers has the effect that all enabled event rules -within enabled channels cannot make event sources _emit_ trace events -anymore. - -A tracing session with no running tracers is said to be _inactive_. -Inactive tracing sessions can be set active using the -man:lttng-start(1) command. - -If 'SESSION' is omitted, the LTTng tracers are stopped for the current -tracing session (see man:lttng-create(1) for more information -about the current tracing session). Otherwise, they are stopped for the -existing tracing session named 'SESSION'. `lttng list` -outputs all the existing tracing sessions (see man:lttng-list(1)). - -By default, the `lttng stop` command ensures that the tracing session's -trace data is valid before returning to the prompt. With the -option:--no-wait option, the command finishes immediately, hence a local -trace might not be valid when the command is done. In this case, there -is no way to know when the trace becomes valid. - -If at least one rotation occurred during the chosen tracing session's -lifetime (see man:lttng-rotate(1) and man:lttng-enable-rotation(1)), the -`lttng stop` command renames the current trace chunk subdirectory and -prints the renamed path. Although it is safe to read the content of this -renamed subdirectory while the tracing session remains inactive (until -the next man:lttng-start(1)), it is :not: a trace chunk archive: you -need to destroy the tracing session with man:lttng-destroy(1) or make -a rotation with man:lttng-rotate(1) to archive it. +The `lttng stop` command stops a tracing session, that is, it +deactivates the LTTng tracers for: + +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 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)). + +Start an inactive tracing session with the man:lttng-start(1) command. + +By default, the `stop` command ensures that the trace data of the +selected tracing session is valid before it exits. Make the command exit +immediately with the option:--no-wait option. In this case, however, the +traces(s) might not be valid when the command exits, and there's no way +to know when it/they becomes valid. + +If LTTng archived the current trace chunk (see man:lttng-rotate(1) and +man:lttng-enable-rotation(1)) of the selected tracing session at least +once during its lifetime, the `stop` command renames the current trace +chunk subdirectory and prints the renamed path. Although it's safe to +read the content of this renamed subdirectory while the tracing session +remains inactive, it's :not: a trace chunk archive: you need to destroy +the tracing session with man:lttng-destroy(1) or perform a rotation with +man:lttng-rotate(1) to archive it. include::common-cmd-options-head.txt[] option:-n, option:--no-wait:: - Do not ensure that the chosen tracing session's trace data is valid - before returning to the prompt. + Do :not: ensure that the trace data of the selected tracing session + is valid before exiting. include::common-cmd-help-options.txt[] @@ -65,5 +72,9 @@ include::common-cmd-footer.txt[] SEE ALSO -------- -man:lttng-start(1), -man:lttng(1) +man:lttng(1), +man:lttng-add-trigger(1), +man:lttng-create(1), +man:lttng-enable-event(1), +man:lttng-rotate(1), +man:lttng-start(1) diff --git a/doc/man/lttng-track.1.txt b/doc/man/lttng-track.1.txt index 79b294f74..6157bcd43 100644 --- a/doc/man/lttng-track.1.txt +++ b/doc/man/lttng-track.1.txt @@ -43,9 +43,9 @@ DESCRIPTION The `lttng track` commands adds one or more values to a process attribute tracker. -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 event rules (see +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)). Tracker values can be removed from an inclusion set with diff --git a/doc/man/lttng-version.1.txt b/doc/man/lttng-version.1.txt index dce553c8b..5cc7b3c54 100644 --- a/doc/man/lttng-version.1.txt +++ b/doc/man/lttng-version.1.txt @@ -1,6 +1,6 @@ lttng-version(1) ================ -:revdate: 1 May 2018 +:revdate: 21 April 2021 NAME @@ -16,15 +16,17 @@ SYNOPSIS DESCRIPTION ----------- -The `lttng version` command outputs the version of LTTng-tools. +The `lttng version` command shows the version of LTTng-tools, the LTTng +project which provides the man:lttng(1) command and other tracing +control programs and libraries. -The output of `lttng version` is broken down into the following parts: +The output of the `version` command shows: -* Major, minor, and patch numbers -* Git commit information, if available -* Release name with its description -* LTTng project's website URL -* License information +* The major, minor, and patch version numbers. +* The Git commit information, if available. +* The release name and its description. +* The URL of the LTTng project website. +* The license information. include::common-cmd-options-head.txt[] diff --git a/doc/man/lttng-view.1.txt b/doc/man/lttng-view.1.txt index e358c5b63..6874aad3c 100644 --- a/doc/man/lttng-view.1.txt +++ b/doc/man/lttng-view.1.txt @@ -1,50 +1,61 @@ lttng-view(1) ============= -:revdate: 28 November 2016 +:revdate: 21 April 2021 NAME ---- -lttng-view - View the traces of an LTTng tracing session +lttng-view - Launch an LTTng trace reader SYNOPSIS -------- [verse] -*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *view* [option:--viewer='CMD'] [option:--trace-path='PATH' | 'SESSION'] +*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *view* [option:--viewer='READER'] + ['SESSION' | option:--trace-path='DIR'] DESCRIPTION ----------- -The `lttng view` command launches an external trace viewer to view the -current trace of a tracing session. +The `lttng view` command launches an external trace reader to read the +current traces of: -If 'SESSION' is omitted, the viewer is launched for the current tracing -session (see man:lttng-create(1) for more information -about the current tracing session). Otherwise, it is launched for the -existing tracing session named 'SESSION'. `lttng list` -outputs all the existing tracing sessions (see man:lttng-list(1)). +With the option:--session='SESSION' option:: + The tracing session named 'SESSION'. -By default, the man:babeltrace2(1) trace viewer is launched. If it is -not found on the system, the man:babeltrace(1) trace viewer is -used. -Another trace viewer command can be specified using the -option:--viewer option. +With the option:--trace-path='DIR' option:: + The local file system directory 'DIR'. -By default, the trace path of the chosen tracing session is given -as the first positional argument to the trace viewer. This path can -be overridden using the option:--trace-path option. +Otherwise:: + 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 option or without the option:--trace-path +option, the mode of the selected tracing session may :not: be network +streaming or live. + +By default, the `view` command attempts to launch man:babeltrace2(1) or, +if it's not available, man:babeltrace(1). Override which trace reader to +launch with the option:--viewer option. include::common-cmd-options-head.txt[] -option:-t 'PATH', option:--trace-path='PATH':: - View trace at path 'PATH' instead of using the chosen tracing - session's trace path. +option:-t 'DIR', option:--trace-path='DIR':: + Pass 'DIR' as the last argument of the trace reader command instead + of the output directory of the selected tracing session. -option:-e 'CMD', option:--viewer='CMD':: - Use 'CMD' as the trace viewer. +option:-e 'READER', option:--viewer='READER':: + Use the trace reader 'READER' to read the traces. ++ +'READER' is the absolute path to the reader command to use, and it can +contain command arguments as well. The `view` command passes the trace +directory path to read to the 'READER' command as its last argument. ++ +Without this option, the `view` command uses man:babeltrace2(1) if it's +available. Otherwise, it tries to use man:babeltrace(1). include::common-cmd-help-options.txt[] @@ -55,4 +66,5 @@ include::common-cmd-footer.txt[] SEE ALSO -------- +man:babeltrace2(1), man:lttng(1) diff --git a/doc/man/lttng.1.txt b/doc/man/lttng.1.txt index 8465ceeb4..06f3a362a 100644 --- a/doc/man/lttng.1.txt +++ b/doc/man/lttng.1.txt @@ -11,133 +11,140 @@ lttng - LTTng 2 tracer control command-line tool SYNOPSIS -------- [verse] -*lttng* [option:--group='GROUP'] [option:--mi='TYPE'] [option:--no-sessiond | option:--sessiond-path='PATH'] - [option:--quiet | option:-v | option:-vv | option:-vvv] '<>' ['COMMAND OPTIONS'] +*lttng* [option:--group='GROUP'] [option:--mi=xml] [option:--no-sessiond | option:--sessiond-path='PATH'] + [option:--quiet | option:-verbose...] '<>' ['COMMAND OPTIONS'] 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). +The `lttng` command-line tool, as well as any user application linked +with the LTTng control library (`liblttng-ctl`), sends commands to a +listening LTTng session daemon (man:lttng-sessiond(8)). A session +daemon: -An LTTng _session daemon_, man:lttng-sessiond(8), receives -commands from the command-line interface `lttng` to control the LTTng -tracers. All interactions with the LTTng tracers happen through the -`lttng` tool or through the liblttng-ctl library shipped with the -LTTng-tools package. +* Manages tracing sessions (see man:lttng-create(1) to learn more + about tracing sessions). -A _tracing domain_ is a tracer category. There are five available -domains. For some commands, the domain needs to be specified with a -command-line option. The domain options are: +* Controls the various components (like tracers and consumer daemons) of + LTTng. -nloption:-j, nloption:--jul:: - Apply command to the `java.util.logging` (JUL) domain. +* Sends asynchronous notifications to user applications. -nloption:-k, nloption:--kernel:: - Apply command to the Linux kernel domain. +By default, the man:lttng-create(1) command automatically spawns a +session daemon for your Unix user if none is currently running. Override +the path of the session daemon binary to spawn with the +option:--sessiond-path option. Avoid automatically spawning a session +daemon with the option:--no-sessiond option. -nloption:-l, nloption:--log4j:: - Apply command to the https://logging.apache.org/log4j/1.2/[Apache log4j 1.2] - (Java) domain. +NOTE: The LTTng project recommends that you start the session daemon at +boot time for stable and long-term tracing. -nloption:-p, nloption:--python:: - Apply command to the https://www.python.org/[Python] domain. -nloption:-u, nloption:--userspace:: - Apply command to the user space domain (application using - liblttng-ust directly; see man:lttng-ust(3)). +Session daemon connection +~~~~~~~~~~~~~~~~~~~~~~~~~ +For most of its commands, the `lttng` tool needs to connect to a +listening LTTng session daemon (man:lttng-sessiond(8)) to control LTTng +tracing. -The LTTng session daemon is a tracing registry which allows the user to -interact with multiple tracers (kernel and user space) within the same -container, a _tracing session_. Traces can be gathered from the Linux -kernel and/or from instrumented applications (see -man:lttng-ust(3)). You can aggregate and read the events of LTTng -traces using man:babeltrace2(1). +Each Unix user may have its own independent running session daemon. +However, the `lttng` tool must connect to the session daemon of the +`root` user (the root session daemon) to control Linux kernel tracing. -To trace the Linux kernel, the session daemon needs to be running as -`root`. LTTng uses a _tracing group_ to allow specific users to interact -with the root session daemon. The default tracing group name is -`tracing`. You can use the option:--group option to set the tracing -group name to use. +How the `lttng` tool chooses which session daemon to connect to +is as follows: -Session daemons can coexist. You can have a session daemon running as -user Alice that can be used to trace her applications alongside a root -session daemon or a session daemon running as user Bob. +If your Unix user is `root`:: + Connect to the root session daemon. -NOTE: It is highly recommended to start the session daemon at boot time -for stable and long-term tracing. +If your Unix user is not `root`:: + If your Unix user is part of the Unix tracing group::: + Try to connect to the root session daemon. ++ +If the root session daemon isn't running, connect to the session daemon +of your Unix user. -User applications instrumented with LTTng automatically register to the -root session daemon and to user session daemons. This allows any session -daemon to list the available traceable applications and event sources -(see man:lttng-list(1)). + If your Unix user is not part of the tracing group::: + Connect to the session daemon of your Unix user. -By default, the man:lttng-create(1) command automatically spawns a -user session daemon if none is currently running. The -option:--no-sessiond general option can be set to avoid this. +The name of the Unix tracing group is one of: + +With the nloption:--group='GROUP' option of the root session daemon (man:lttng-sessiond(8)):: + 'GROUP' ++ +In that case, you must use the option:--group='GROUP' option, with +the same 'GROUP' argument, of the `lttng` tool. + +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)). OPTIONS ------- option:-g 'GROUP', option:--group='GROUP':: - Use 'GROUP' as Unix tracing group (default: `tracing`). - -option:-m 'TYPE', option:--mi='TYPE':: - Print the command's result using the machine interface type 'TYPE' - instead of a human-readable output. + Set the name of the Unix tracing group to 'GROUP' instead of + `tracing`. + -Supported types: `xml`. -+ -The machine interface (MI) mode converts the traditional pretty-printing -to a machine output syntax. The MI mode provides a change-resistant way -to access information generated by the `lttng` command-line program. +You must use this option to be able to connect to a root session daemon +(man:lttng-sessiond(8)) which was started with its own +nloption:--group='GROUP' option. + +option:-m `xml`, option:--mi=++xml++:: + Print the command's result using a stable XML machine interface (MI) + output instead of the default, unstable human-readable output. + -When using the MI mode, the data is printed to the standard output. -Errors and warnings are printed on the standard error with the -pretty-print default format. +With this mode, `lttng` prints the resulting XML document to the +standard output, while it prints any error/warning to the standard error +with an unstable, human-readable format. + -If any error occurs during the execution of a command, the return value -of the command will be different than 0. In this case, `lttng` does -:not: guarantee the syntax and data validity of the generated MI output. +If any error occurs during the execution of `lttng`, the command +exits with a status different than{nbsp}0, and `lttng` does +:not: guarantee the syntax and data validity of its MI output. + -For the `xml` MI type, an XML schema definition (XSD) file used for -validation is available: see the `src/common/mi_lttng.xsd` file in -the LTTng-tools source tree. +An XML schema definition (XSD) file used for validation of the MI output +is available: see the `src/common/mi_lttng.xsd` file in the LTTng-tools +source tree. option:-n, option:--no-sessiond:: - Do not automatically spawn a session daemon. + Do not automatically spawn a session daemon for your Unix user when + running the man:lttng-create(1) command. ++ +You may :not: use this option with the option:--sessiond-path option. option:-q, option:--quiet:: Suppress all messages, including warnings and errors. ++ +You may :not: use this option with the option:--verbose option. option:--sessiond-path='PATH':: - Set the session daemon binary's absolute path to 'PATH'. + Set the absolute path of the session daemon binary to spawn from the + man:lttng-create(1) command to 'PATH'. ++ +You may :not: use this option with the option:--no-sessiond option. 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. ++ +You may :not: use this option with the option:--quiet option. Program information ~~~~~~~~~~~~~~~~~~~ -option:-h, option:--help:: - Show help. +include::common-help-option.txt[] option:--list-commands:: - List available commands. - -option:--list-options:: - List available general options. + List available commands and quit. option:-V, option:--version:: - Show version. + Show version and quit. [[commands]] @@ -146,101 +153,90 @@ COMMANDS The following commands also have their own nloption:--help option. -Tracing sessions -~~~~~~~~~~~~~~~~ -man:lttng-create(1):: - {cmd_descr_create}. - -man:lttng-destroy(1):: - {cmd_descr_destroy}. - -man:lttng-load(1):: - {cmd_descr_load}. - -man:lttng-regenerate(1):: - {cmd_descr_regenerate}. - -man:lttng-save(1):: - {cmd_descr_save}. - -man:lttng-set-session(1):: - {cmd_descr_set_session}. - - -Channels -~~~~~~~~ -man:lttng-add-context(1):: - {cmd_descr_add_context}. - -man:lttng-disable-channel(1):: - {cmd_descr_disable_channel}. - -man:lttng-enable-channel(1):: - {cmd_descr_enable_channel}. - - -Event rules -~~~~~~~~~~~ -man:lttng-disable-event(1):: - {cmd_descr_disable_event}. - -man:lttng-enable-event(1):: - {cmd_descr_enable_event}. - - -Status -~~~~~~ -man:lttng-list(1):: - {cmd_descr_list}. - -man:lttng-status(1):: - {cmd_descr_status}. - - -Control +Tracing session +~~~~~~~~~~~~~~~ +[options="header"] +|=== +|Command |Description + +|man:lttng-create(1) |{cmd_descr_create}. +|man:lttng-destroy(1) |{cmd_descr_destroy}. +|man:lttng-disable-rotation(1) |{cmd_descr_disable_rotation}. +|man:lttng-enable-rotation(1) |{cmd_descr_enable_rotation}. +|man:lttng-load(1) |{cmd_descr_load}. +|man:lttng-regenerate(1) |{cmd_descr_regenerate}. +|man:lttng-rotate(1) |{cmd_descr_rotate}. +|man:lttng-save(1) |{cmd_descr_save}. +|man:lttng-set-session(1) |{cmd_descr_set_session}. +|man:lttng-snapshot(1) |{cmd_descr_snapshot}. +|man:lttng-start(1) |{cmd_descr_start}. +|man:lttng-status(1) |{cmd_descr_status}. +|man:lttng-stop(1) |{cmd_descr_stop}. +|=== + + +Channel ~~~~~~~ -man:lttng-snapshot(1):: - {cmd_descr_snapshot}. - -man:lttng-start(1):: - {cmd_descr_start}. - -man:lttng-stop(1):: - {cmd_descr_stop}. +[options="header"] +|=== +|Command |Description +|man:lttng-add-context(1) |{cmd_descr_add_context}. +|man:lttng-disable-channel(1) |{cmd_descr_disable_channel}. +|man:lttng-enable-channel(1) |{cmd_descr_enable_channel}. +|=== -Tracing session rotation -~~~~~~~~~~~~~~~~~~~~~~~~ -man:lttng-disable-rotation(1):: - {cmd_descr_disable_rotation}. -man:lttng-enable-rotation(1):: - {cmd_descr_enable_rotation}. +Recording event rule +~~~~~~~~~~~~~~~~~~~~ +[options="header"] +|=== +|Command |Description -man:lttng-rotate(1):: - {cmd_descr_rotate}. +|man:lttng-disable-event(1) |{cmd_descr_disable_event}. +|man:lttng-enable-event(1) |{cmd_descr_enable_event}. +|=== +Information +~~~~~~~~~~~ +[options="header"] +|=== +|Command |Description +|man:lttng-list(1) |{cmd_descr_list}. +|=== Resource tracking ~~~~~~~~~~~~~~~~~ -man:lttng-track(1):: - {cmd_descr_track}. +[options="header"] +|=== +|Command |Description + +|man:lttng-track(1) |{cmd_descr_track}. +|man:lttng-untrack(1) |{cmd_descr_untrack}. +|=== -man:lttng-untrack(1):: - {cmd_descr_untrack}. +Trigger +~~~~~~~ +[options="header"] +|=== +|Command |Description +|man:lttng-add-trigger(1) |{cmd_descr_add_trigger}. +|man:lttng-list-triggers(1) |{cmd_descr_list_triggers}. +|man:lttng-remove-trigger(1) |{cmd_descr_remove_trigger}. +|=== Miscellaneous ~~~~~~~~~~~~~ -man:lttng-help(1):: - {cmd_descr_help}. - -man:lttng-version(1):: - {cmd_descr_version}. +[options="header"] +|=== +|Command |Description -man:lttng-view(1):: - {cmd_descr_view}. +|man:lttng-help(1) |{cmd_descr_help}. +|man:lttng-version(1) |{cmd_descr_version}. +|man:lttng-view(1) |{cmd_descr_view}. +|=== include::common-cmd-footer.txt[] @@ -248,8 +244,6 @@ include::common-cmd-footer.txt[] SEE ALSO -------- -man:lttng-sessiond(8), +man:babeltrace2(1), man:lttng-relayd(8), -man:lttng-crash(1), -man:lttng-ust(3), -man:babeltrace2(1) +man:lttng-sessiond(8) diff --git a/src/bin/lttng/commands/list.c b/src/bin/lttng/commands/list.c index 815188608..a2db7e6b1 100644 --- a/src/bin/lttng/commands/list.c +++ b/src/bin/lttng/commands/list.c @@ -1244,7 +1244,7 @@ static int list_events(const char *channel_name) } } else { /* Pretty print */ - MSG("\n%sEvent rules:", indent4); + MSG("\n%sRecording event rules:", indent4); if (count == 0) { MSG("%sNone\n", indent6); goto end; diff --git a/src/bin/lttng/lttng.c b/src/bin/lttng/lttng.c index 437a9cc4c..1c7d79954 100644 --- a/src/bin/lttng/lttng.c +++ b/src/bin/lttng/lttng.c @@ -286,7 +286,7 @@ static void show_basic_help(void) puts(" disable-channel " CONFIG_CMD_DESCR_DISABLE_CHANNEL); puts(" enable-channel " CONFIG_CMD_DESCR_ENABLE_CHANNEL); puts(""); - puts("Event rules:"); + puts("Recording event rules:"); puts(" disable-event " CONFIG_CMD_DESCR_DISABLE_EVENT); puts(" enable-event " CONFIG_CMD_DESCR_ENABLE_EVENT); puts(""); @@ -308,6 +308,11 @@ static void show_basic_help(void) puts(" track " CONFIG_CMD_DESCR_TRACK); puts(" untrack " CONFIG_CMD_DESCR_UNTRACK); puts(""); + puts("Triggers:"); + puts(" add-trigger " CONFIG_CMD_DESCR_ADD_TRIGGER); + puts(" remove-trigger " CONFIG_CMD_DESCR_REMOVE_TRIGGER); + puts(" list-triggers " CONFIG_CMD_DESCR_LIST_TRIGGERS); + puts(""); puts("Miscellaneous:"); puts(" help " CONFIG_CMD_DESCR_HELP); puts(" version " CONFIG_CMD_DESCR_VERSION); -- 2.34.1