8 lttng-add-context - Add context fields to be recorded by LTTng
13 Add context fields to be recorded to the event records of one or more
17 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *add-context*
18 (option:--kernel | option:--userspace | option:--jul | option:--log4j)
19 [option:--session='SESSION'] [option:--channel='CHANNEL']
20 option:--type='TYPE' [option:--type='TYPE']...
22 List the available context field types:
25 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *add-context* option:--list
30 The `lttng add-context` command can:
32 Without the option:--list option::
33 Add one or more context fields to be recorded by LTTng to the event
36 With the option:--session='SESSION' option:::
37 The recording session named 'SESSION'.
39 Without the option:--session option:::
40 The current recording session (see man:lttng-concepts(7) to learn
41 more about the current recording session).
43 With the option:--channel='CHANNEL':::
44 The channel named 'CHANNEL'.
46 Without the option:--channel option:::
47 *All* the channels of the selected recording session.
49 With the option:--list option::
50 List the available context field types.
52 See man:lttng-concepts(7) to learn more about recording sessions and
55 Repeat the option:--type='TYPE' option to add more than one context
56 field to be recorded. 'TYPE' is one of:
58 * A statically-known, or built-in context field name.
60 * A perf counter name:
66 Only available with the option:--kernel option.
69 Prefix: `perf:thread:`
71 Only available with the option:--userspace, option:--jul, or
72 option:--log4j option.
75 Add Performance Monitoring Unit (PMU) counter context fields by raw ID
76 with the ++perf:cpu:raw:r++__N__++:++__NAME__ (option:--kernel option)
77 or ++perf:thread:raw:r++__N__++:++__NAME__ (option:--userspace,
78 option:--jul, or option:--log4j option) types, with:
82 A hexadecimal event descriptor which follows the man:perf-record(1)
83 format: a concatenation of the event number and umask value which
84 the manufacturer of the processor provides.
86 The possible values for this part are processor-specific.
89 Custom name to identify the counter.
92 * An LTTng application-specific context field name:
96 $app.'PROVIDER':__TYPE__
105 Only available with the option:--jul and option:--log4j options.
107 IMPORTANT: Make sure to **single-quote** 'TYPE' when you run the
108 `add-context` command from a shell, as `$` is a special character for
109 variable substitution in most shells.
111 NOTE: As of LTTng{nbsp}{lttng_version}, you may :not: add context fields
112 to be recorded to the event records of a given channel once its
113 recording session has been started (see man:lttng-start(1)) at least
116 See the ``<<examples,EXAMPLES>>'' section below for usage examples.
119 include::common-lttng-cmd-options-head.txt[]
126 option:-j, option:--jul::
127 Add context fields to be recorded to the event records of one or
128 more channels of the `java.util.logging` (JUL) tracing domain.
130 option:-k, option:--kernel::
131 Add context fields to be recorded to the event records of one or
132 more channels of the Linux kernel tracing domain.
134 option:-l, option:--log4j::
135 Add context fields to be recorded to the event records of one or
136 more channels of the Apache log4j tracing domain.
138 option:-u, option:--userspace::
139 Add context fields to be recorded to the event records of one or
140 more channels of the user space tracing domain.
145 option:-c 'CHANNEL', option:--channel='CHANNEL'::
146 Add context fields to be recorded to the event records of a channel
147 named 'CHANNEL' instead of all the channels of the selected
150 option:-s 'SESSION', option:--session='SESSION'::
151 Add context fields to be recorded to the event records of one or
152 more channels of the recording session named 'SESSION' instead of
153 the current recording session.
159 List the available context field types.
161 You may :not: use this option with the option:--channel,
162 option:--session, or option:--type options.
164 option:-t 'TYPE', option:--type='TYPE'::
165 Add a context field having the type 'TYPE' to be recorded.
167 Repeat this option to add more than one context field.
170 include::common-lttng-cmd-help-options.txt[]
173 include::common-lttng-cmd-after-options.txt[]
179 .List the available context field types.
181 See the option:--list option.
185 $ lttng add-context --list
189 .Add a single statically-known context field to be recorded to all the Linux kernel channels of the current recording session.
193 $ lttng add-context --kernel --type=pid
197 .Add three statically-known context fields to be recorded to a specific user space channel of a specific recording session.
199 See the option:--session and option:--channel options.
203 $ lttng add-context --userspace --session=my-session \
204 --channel=my-channel \
205 --type=vpid --type=procname --type=ip
209 .Add a perf counter context field to be recorded to a specific Linux kernel channel of the current recording session.
211 See the option:--channel option.
215 $ lttng add-context --kernel --channel=my-channel \
216 --type=perf:cpu:cache-misses
220 .Add an LTTng application-specific context field to be recorded to all the JUL channels of the current recording session.
224 $ lttng add-context --jul --type='$app.my_server:user_cnt'
229 include::common-footer.txt[]
235 man:lttng-enable-channel(1),
236 man:lttng-concepts(7)