lttng-add-context - Add context fields to be recorded by LTTng

       This program is part of the LTTng-tools project.

       LTTng-tools is distributed under the GNU General Public License version 2
       <http://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html>. See the LICENSE
       <https://github.com/lttng/lttng-tools/blob/master/LICENSE> file for details.

       The lttngadd-context command can:

       Without the --list option
           Add one or more context fields to be recorded by LTTng to the event records of:

           With the --session=SESSION option
               The recording session named SESSION.

           Without the --session option
               The current recording session (see lttng-concepts(7) to learn more about the current recording
               session).

           With the --channel=CHANNEL
               The channel named CHANNEL.

           Without the --channel option
               All the channels of the selected recording session.

       With the --list option
           List the available context field types.

       See lttng-concepts(7) to learn more about recording sessions and channels.

       Repeat the --type=TYPE option to add more than one context field to be recorded. TYPE is one of:

       •   A statically-known, or built-in context field named.

       •   A perf counter name:

           Per-CPU
               Prefix: perf:cpu:

               Only available with the --kernel option.

           Per-thread
               Prefix: perf:thread:

               Only available with the --userspace, --jul, or --log4j option.

           Add Performance Monitoring Unit (PMU) counter context fields by raw ID with the perf:cpu:raw:rN:NAME
           (--kernel option) or perf:thread:raw:rN:NAME (--userspace, --jul, or --log4j option) types, with:

           N
               A hexadecimal event descriptor which follows the 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 part are processor-specific.

           NAME
               Custom name to identify the counter.

       •   An LTTng application-specific context field name:

               $app.PROVIDER:TYPE
           + PROVIDER:: Provider name.

           TYPE
               Context type name.

           Only available with the --jul and --log4j options.

       Important

           Make sure to single-quoteTYPE when you run the add-context command from a shell, as $ is a special
           character for variable substitution in most shells.

       Note

           As of LTTng 2.13.14, you may NOT add context fields to be recorded to the event records of a given
           channel once its recording session has been started (see lttng-start(1)) at least once.

       See the “EXAMPLES” section below for usage examples.

LTTNG_ABORT_ON_ERROR
           Set to 1 to abort the process after the first error is encountered.

       LTTNG_HOME
           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 manual pager to use to read the LTTng command-line help (with lttng-help(1) or
           with the --help option) instead of /usr/bin/man.

       LTTNG_SESSION_CONFIG_XSD_PATH
           Path to the directory containing the session.xsd recording session configuration XML schema.

       LTTNG_SESSIOND_PATH
           Absolute path to the LTTng session daemon binary (see lttng-sessiond(8)) to spawn from the lttng-create(1) command.

           The --sessiond-path general option overrides this environment variable.

Example1.Listtheavailablecontextfieldtypes.

           See the --list option.

               $ lttng add-context --list

       Example2.Addasinglestatically-knowncontextfieldtoberecordedtoalltheLinuxkernelchannelsofthecurrentrecordingsession.

               $ lttng add-context --kernel --type=pid

       Example3.Addthreestatically-knowncontextfieldstoberecordedtoaspecificuserspacechannelofaspecificrecordingsession.

           See the --session and --channel options.

               $ lttng add-context --userspace --session=my-session \
                                   --channel=my-channel \
                                   --type=vpid --type=procname --type=ip

       Example4.AddaperfcountercontextfieldtoberecordedtoaspecificLinuxkernelchannelofthecurrentrecordingsession.

           See the --channel option.

               $ lttng add-context --kernel --channel=my-channel \
                                   --type=perf:cpu:cache-misses

       Example5.AddanLTTngapplication-specificcontextfieldtoberecordedtoalltheJULchannelsofthecurrentrecordingsession.

               $ lttng add-context --jul --type='$app.my_server:user_cnt'

0
           Success

       1
           Command error

       2
           Undefined command

       3
           Fatal error

       4
           Command warning (something went wrong during the command)

$LTTNG_HOME/.lttngrc
           Unix user’s LTTng runtime configuration.

           This is where LTTng stores the name of the Unix user’s current recording session between executions
           of lttng(1).  lttng-create(1) and lttng-set-session(1) set the current recording session.

       $LTTNG_HOME/lttng-traces
           Default output directory of LTTng traces in local and snapshot modes.

           Override this path with the --output option of the lttng-create(1) command.

       $LTTNG_HOME/.lttng
           Unix user’s LTTng runtime and configuration directory.

       $LTTNG_HOME/.lttng/sessions
           Default directory containing the Unix user’s saved recording session configurations (see lttng-save(1) and lttng-load(1)).

       /etc/lttng/sessions
           Directory containing the system-wide saved recording session configurations (see lttng-save(1) and
           lttng-load(1)).

       Note$LTTNG_HOME defaults to the value of the HOME environment variable.

       lttng-add-context - Add context fields to be recorded by LTTng

       See lttng(1) for GENERALOPTIONS.

   Tracingdomain
       One of:

       -j, --jul
           Add context fields to be recorded to the event records of one or more channels of the
           java.util.logging (JUL) tracing domain.

       -k, --kernel
           Add context fields to be recorded to the event records of one or more channels of the Linux kernel
           tracing domain.

       -l, --log4j
           Add context fields to be recorded to the event records of one or more channels of the Apache log4j
           tracing domain.

       -u, --userspace
           Add context fields to be recorded to the event records of one or more channels of the user space
           tracing domain.

   Recordingtarget-cCHANNEL, --channel=CHANNEL
           Add context fields to be recorded to the event records of a channel named CHANNEL instead of all the
           channels of the selected recording session.

       -sSESSION, --session=SESSION
           Add context fields to be recorded to the event records of one or more channels of the recording
           session named SESSION instead of the current recording session.

   Contextfieldtype--list
           List the available context field types.

           You may NOT use this option with the --channel, --session, or --type options.

       -tTYPE, --type=TYPE
           Add a context field having the type TYPE to be recorded.

           Repeat this option to add more than one context field.

   Programinformation-h, --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.

       --list-options
           List available command options and quit.

       •   LTTng project website <https://lttng.org>

       •   LTTng documentation <https://lttng.org/docs>

       •   LTTng bug tracker <https://bugs.lttng.org>

       •   Git repositories <https://git.lttng.org>

       •   GitHub organization <https://github.com/lttng>

       •   Continuous integration <https://ci.lttng.org/>

       •   Mailing list <https://lists.lttng.org/> for support and development: lttng-dev@lists.lttng.org

       •   IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net

lttng(1), lttng-enable-channel(1), lttng-concepts(7)

LTTng 2.13.14                                     14 June 2021                              LTTNG-ADD-CONTEXT(1)

       Add context fields to be recorded to the event records of one or more channels:

       lttng [GENERALOPTIONS] add-context
             (--kernel | --userspace | --jul | --log4j)
             [--session=SESSION] [--channel=CHANNEL]
             --type=TYPE [--type=TYPE]...

       List the available context field types:

       lttng [GENERALOPTIONS] add-context--list

       Special thanks to Michel Dagenais and the DORSAL laboratory <http://www.dorsal.polymtl.ca/> at École
       Polytechnique de Montréal for the LTTng journey.

       Also thanks to the Ericsson teams working on tracing which helped us greatly with detailed bug reports
       and unusual test cases.