lttng-add-context(1)

1LTTNG-ADD-CONTEXT(1)             LTTng Manual             LTTNG-ADD-CONTEXT(1)
2
3
4

NAME

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

SYNOPSIS

9       Add context fields to be recorded to the event records of one or more
10       channels:
11
12       lttng [GENERAL OPTIONS] add-context
13             (--kernel | --userspace | --jul | --log4j)
14             [--session=SESSION] [--channel=CHANNEL]
15             --type=TYPE [--type=TYPE]...
16
17       List the available context field types:
18
19       lttng [GENERAL OPTIONS] add-context --list
20

DESCRIPTION

22       The lttng add-context command can:
23
24       Without the --list option
25           Add one or more context fields to be recorded by LTTng to the event
26           records of:
27
28           With the --session=SESSION option
29               The recording session named SESSION.
30
31           Without the --session option
32               The current recording session (see lttng-concepts(7) to learn
33               more about the current recording session).
34
35           With the --channel=CHANNEL
36               The channel named CHANNEL.
37
38           Without the --channel option
39               All the channels of the selected recording session.
40
41       With the --list option
42           List the available context field types.
43
44       See lttng-concepts(7) to learn more about recording sessions and
45       channels.
46
47       Repeat the --type=TYPE option to add more than one context field to be
48       recorded. TYPE is one of:
49
50       •   A statically-known, or built-in context field named.
51
52       •   A perf counter name:
53
54           Per-CPU
55               Prefix: perf:cpu:
56
57               Only available with the --kernel option.
58
59           Per-thread
60               Prefix: perf:thread:
61
62               Only available with the --userspace, --jul, or --log4j option.
63
64           Add Performance Monitoring Unit (PMU) counter context fields by raw
65           ID with the perf:cpu:raw:rN:NAME (--kernel option) or
66           perf:thread:raw:rN:NAME (--userspace, --jul, or --log4j option)
67           types, with:
68
69           N
70               A hexadecimal event descriptor which follows the perf-record(1)
71               format: a concatenation of the event number and umask value
72               which the manufacturer of the processor provides.
73
74               The possible values for this part are processor-specific.
75
76           NAME
77               Custom name to identify the counter.
78
79       •   An LTTng application-specific context field name:
80
81               $app.PROVIDER:TYPE
82           + PROVIDER:: Provider name.
83
84           TYPE
85               Context type name.
86
87           Only available with the --jul and --log4j options.
88
89       Important
90           Make sure to single-quote TYPE when you run the add-context command
91           from a shell, as $ is a special character for variable substitution
92           in most shells.
93
94       Note
95           As of LTTng 2.13.4, you may NOT add context fields to be recorded
96           to the event records of a given channel once its recording session
97           has been started (see lttng-start(1)) at least once.
98
99       See the “EXAMPLES” section below for usage examples.
100

OPTIONS

102       See lttng(1) for GENERAL OPTIONS.
103
104   Tracing domain
105       One of:
106
107       -j, --jul
108           Add context fields to be recorded to the event records of one or
109           more channels of the java.util.logging (JUL) tracing domain.
110
111       -k, --kernel
112           Add context fields to be recorded to the event records of one or
113           more channels of the Linux kernel tracing domain.
114
115       -l, --log4j
116           Add context fields to be recorded to the event records of one or
117           more channels of the Apache log4j tracing domain.
118
119       -u, --userspace
120           Add context fields to be recorded to the event records of one or
121           more channels of the user space tracing domain.
122
123   Recording target
124       -c CHANNEL, --channel=CHANNEL
125           Add context fields to be recorded to the event records of a channel
126           named CHANNEL instead of all the channels of the selected recording
127           session.
128
129       -s SESSION, --session=SESSION
130           Add context fields to be recorded to the event records of one or
131           more channels of the recording session named SESSION instead of the
132           current recording session.
133
134   Context field type
135       --list
136           List the available context field types.
137
138           You may NOT use this option with the --channel, --session, or
139           --type options.
140
141       -t TYPE, --type=TYPE
142           Add a context field having the type TYPE to be recorded.
143
144           Repeat this option to add more than one context field.
145
146   Program information
147       -h, --help
148           Show help.
149
150           This option attempts to launch /usr/bin/man to view this manual
151           page. Override the manual pager path with the LTTNG_MAN_BIN_PATH
152           environment variable.
153
154       --list-options
155           List available command options and quit.
156

EXIT STATUS

158       0
159           Success
160
161       1
162           Command error
163
164       2
165           Undefined command
166
167       3
168           Fatal error
169
170       4
171           Command warning (something went wrong during the command)
172

ENVIRONMENT

174       LTTNG_ABORT_ON_ERROR
175           Set to 1 to abort the process after the first error is encountered.
176
177       LTTNG_HOME
178           Path to the LTTng home directory.
179
180           Defaults to $HOME.
181
182           Useful when the Unix user running the commands has a non-writable
183           home directory.
184
185       LTTNG_MAN_BIN_PATH
186           Absolute path to the manual pager to use to read the LTTng
187           command-line help (with lttng-help(1) or with the --help option)
188           instead of /usr/bin/man.
189
190       LTTNG_SESSION_CONFIG_XSD_PATH
191           Path to the directory containing the session.xsd recording session
192           configuration XML schema.
193
194       LTTNG_SESSIOND_PATH
195           Absolute path to the LTTng session daemon binary (see lttng-
196           sessiond(8)) to spawn from the lttng-create(1) command.
197
198           The --sessiond-path general option overrides this environment
199           variable.
200

FILES

202       $LTTNG_HOME/.lttngrc
203           Unix user’s LTTng runtime configuration.
204
205           This is where LTTng stores the name of the Unix user’s current
206           recording session between executions of lttng(1).  lttng-create(1)
207           and lttng-set-session(1) set the current recording session.
208
209       $LTTNG_HOME/lttng-traces
210           Default output directory of LTTng traces in local and snapshot
211           modes.
212
213           Override this path with the --output option of the lttng-create(1)
214           command.
215
216       $LTTNG_HOME/.lttng
217           Unix user’s LTTng runtime and configuration directory.
218
219       $LTTNG_HOME/.lttng/sessions
220           Default directory containing the Unix user’s saved recording
221           session configurations (see lttng-save(1) and lttng-load(1)).
222
223       /usr/local/etc/lttng/sessions
224           Directory containing the system-wide saved recording session
225           configurations (see lttng-save(1) and lttng-load(1)).
226
227       Note
228           $LTTNG_HOME defaults to the value of the HOME environment variable.
229

EXAMPLES

231       Example 1. List the available context field types.
232
233           See the --list option.
234
235               $ lttng add-context --list
236
237       Example 2. Add a single statically-known context field to be recorded
238       to all the Linux kernel channels of the current recording session.
239
240               $ lttng add-context --kernel --type=pid
241
242       Example 3. Add three statically-known context fields to be recorded to
243       a specific user space channel of a specific recording session.
244
245           See the --session and --channel options.
246
247               $ lttng add-context --userspace --session=my-session \
248                                   --channel=my-channel \
249                                   --type=vpid --type=procname --type=ip
250
251       Example 4. Add a perf counter context field to be recorded to a
252       specific Linux kernel channel of the current recording session.
253
254           See the --channel option.
255
256               $ lttng add-context --kernel --channel=my-channel \
257                                   --type=perf:cpu:cache-misses
258
259       Example 5. Add an LTTng application-specific context field to be
260       recorded to all the JUL channels of the current recording session.
261
262               $ lttng add-context --jul --type='$app.my_server:user_cnt'
263

RESOURCES

265       •   LTTng project website <https://lttng.org>
266
267       •   LTTng documentation <https://lttng.org/docs>
268
269       •   LTTng bug tracker <https://bugs.lttng.org>
270
271       •   Git repositories <https://git.lttng.org>
272
273       •   GitHub organization <https://github.com/lttng>
274
275       •   Continuous integration <https://ci.lttng.org/>
276
277       •   Mailing list <https://lists.lttng.org/> for support and
278           development: lttng-dev@lists.lttng.org
279
280       •   IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
281

COPYRIGHT

283       This program is part of the LTTng-tools project.
284
285       LTTng-tools is distributed under the GNU General Public License
286       version 2 <http://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html>.
287       See the LICENSE <https://github.com/lttng/lttng-
288       tools/blob/master/LICENSE> file for details.
289

THANKS

291       Special thanks to Michel Dagenais and the DORSAL laboratory
292       <http://www.dorsal.polymtl.ca/> at École Polytechnique de Montréal for
293       the LTTng journey.
294
295       Also thanks to the Ericsson teams working on tracing which helped us
296       greatly with detailed bug reports and unusual test cases.
297