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 tracing session named 'SESSION'.
39 Without the option:--session option:::
40 The current tracing session (see man:lttng-concepts(7) to learn more
41 about the current tracing 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 tracing session.
49 With the option:--list option::
50 List the available context field types.
52 See man:lttng-concepts(7) to learn more about tracing 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 named.
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 tracing
113 session has been started (see man:lttng-start(1)) at least once.
115 See the ``<<examples,EXAMPLES>>'' section below for usage examples.
118 include::common-lttng-cmd-options-head.txt[]
125 option:-j, option:--jul::
126 Add context fields to be recorded to the event records of one or
127 more channels of the `java.util.logging` (JUL) tracing domain.
129 option:-k, option:--kernel::
130 Add context fields to be recorded to the event records of one or
131 more channels of the Linux kernel tracing domain.
133 option:-l, option:--log4j::
134 Add context fields to be recorded to the event records of one or
135 more channels of the Apache log4j tracing domain.
137 option:-u, option:--userspace::
138 Add context fields to be recorded to the event records of one or
139 more channels of the user space tracing domain.
144 option:-c 'CHANNEL', option:--channel='CHANNEL'::
145 Add context fields to be recorded to the event records of a channel
146 named 'CHANNEL' instead of all the channels of the selected
149 option:-s 'SESSION', option:--session='SESSION'::
150 Add context fields to be recorded to the event records of one or
151 more channels of the tracing session named 'SESSION' instead of the
152 current tracing session.
158 List the available context field types.
160 You may :not: use this option with the option:--channel,
161 option:--session, or option:--type options.
163 option:-t 'TYPE', option:--type='TYPE'::
164 Add a context field having the type 'TYPE' to be recorded.
166 Repeat this option to add more than one context field.
169 include::common-lttng-cmd-help-options.txt[]
172 include::common-lttng-cmd-after-options.txt[]
178 .List the available context field types.
180 See the option:--list option.
184 $ lttng add-context --list
188 .Add a single statically-known context field to be recorded to all the Linux kernel channels of the current tracing session.
192 $ lttng add-context --kernel --type=pid
196 .Add three statically-known context fields to be recorded to a specific user space channel of a specific tracing session.
198 See the option:--session and option:--channel options.
202 $ lttng add-context --userspace --session=my-session \
203 --channel=my-channel \
204 --type=vpid --type=procname --type=ip
208 .Add a perf counter context field to be recorded to a specific Linux kernel channel of the current tracing session.
210 See the option:--channel option.
214 $ lttng add-context --kernel --channel=my-channel \
215 --type=perf:cpu:cache-misses
219 .Add an LTTng application-specific context field to be recorded to all the JUL channels of the current tracing session.
223 $ lttng add-context --jul --type='$app.my_server:user_cnt'
228 include::common-footer.txt[]
234 man:lttng-enable-channel(1),
235 man:lttng-concepts(7)