lttng-add-context(1) ==================== :revdate: 14 June 2021 NAME ---- lttng-add-context - Add context fields to be recorded by LTTng SYNOPSIS -------- Add context fields to be recorded to the event records of one or more channels: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *add-context* (option:--kernel | option:--userspace | option:--jul | option:--log4j) [option:--session='SESSION'] [option:--channel='CHANNEL'] option:--type='TYPE' [option:--type='TYPE']... List the available context field types: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *add-context* option:--list DESCRIPTION ----------- The `lttng add-context` command can: Without the option:--list option:: Add one or more context fields to be recorded by LTTng to the event records of: + With the option:--session='SESSION' option::: The recording session named 'SESSION'. Without the option:--session option::: The current recording session (see man:lttng-concepts(7) to learn more about the current recording session). With the option:--channel='CHANNEL'::: The channel named 'CHANNEL'. Without the option:--channel option::: *All* the channels of the selected recording session. With the option:--list option:: List the available context field types. See man:lttng-concepts(7) to learn more about recording sessions and channels. Repeat the option:--type='TYPE' option to add more than one context field to be recorded. 'TYPE' is one of: * A statically-known, or built-in context field name. * A perf counter name: + -- Per-CPU:: Prefix: `perf:cpu:` + Only available with the option:--kernel option. Per-thread:: Prefix: `perf:thread:` + Only available with the option:--userspace, option:--jul, or option:--log4j option. -- + Add Performance Monitoring Unit (PMU) counter context fields by raw ID with the ++perf:cpu:raw:r++__N__++:++__NAME__ (option:--kernel option) or ++perf:thread:raw:r++__N__++:++__NAME__ (option:--userspace, option:--jul, or option:--log4j option) types, with: + -- 'N':: A hexadecimal event descriptor which follows the man:perf-record(1) format: a concatenation of the event number and umask value which the manufacturer of the processor provides. + The possible values for this part are processor-specific. 'NAME':: Custom name to identify the counter. -- * An LTTng application-specific context field name: + -- [verse] $app.'PROVIDER':__TYPE__ + 'PROVIDER':: Provider name. 'TYPE':: Context type name. -- + Only available with the option:--jul and option:--log4j options. IMPORTANT: Make sure to **single-quote** 'TYPE' when you run the `add-context` command from a shell, as `$` is a special character for variable substitution in most shells. NOTE: As of LTTng{nbsp}{lttng_version}, you may :not: add context fields to be recorded to the event records of a given channel once its recording session has been started (see man:lttng-start(1)) at least once. See the ``<>'' section below for usage examples. include::common-lttng-cmd-options-head.txt[] Tracing domain ~~~~~~~~~~~~~~ One of: option:-j, option:--jul:: 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 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 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 fields to be recorded to the event records of one or more channels of the user space tracing domain. Recording target ~~~~~~~~~~~~~~~~ option:-c 'CHANNEL', option:--channel='CHANNEL':: Add context fields to be recorded to the event records of a channel named 'CHANNEL' instead of all the channels of the selected recording session. option:-s 'SESSION', option:--session='SESSION':: Add context fields to be recorded to the event records of one or more channels of the recording session named 'SESSION' instead of the current recording session. Context field type ~~~~~~~~~~~~~~~~~~ option:--list:: 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 a context field having the type 'TYPE' to be recorded. + Repeat this option to add more than one context field. include::common-lttng-cmd-help-options.txt[] include::common-lttng-cmd-after-options.txt[] [[examples]] EXAMPLES -------- .List the available context field types. ==== See the option:--list option. [role="term"] ---- $ lttng add-context --list ---- ==== .Add a single statically-known context field to be recorded to all the Linux kernel channels of the current recording session. ==== [role="term"] ---- $ lttng add-context --kernel --type=pid ---- ==== .Add three statically-known context fields to be recorded to a specific user space channel of a specific recording session. ==== See the option:--session and option:--channel options. [role="term"] ---- $ lttng add-context --userspace --session=my-session \ --channel=my-channel \ --type=vpid --type=procname --type=ip ---- ==== .Add a perf counter context field to be recorded to a specific Linux kernel channel of the current recording session. ==== See the option:--channel option. [role="term"] ---- $ lttng add-context --kernel --channel=my-channel \ --type=perf:cpu:cache-misses ---- ==== .Add an LTTng application-specific context field to be recorded to all the JUL channels of the current recording session. ==== [role="term"] ---- $ lttng add-context --jul --type='$app.my_server:user_cnt' ---- ==== include::common-footer.txt[] SEE ALSO -------- man:lttng(1), man:lttng-enable-channel(1), man:lttng-concepts(7)