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 an LTTng channel
7

SYNOPSIS

9       Add context fields to a channel:
10
11       lttng [GENERAL OPTIONS] add-context
12             (--kernel | --userspace | --jul | --log4j)
13             [--session=SESSION] [--channel=CHANNEL]
14             --type=TYPE [--type=TYPE]...
15
16       List the available context fields:
17
18       lttng [GENERAL OPTIONS] add-context --list
19

DESCRIPTION

21       The lttng add-context command adds one or more context fields to a
22       channel.
23
24       Channels are created with the lttng-enable-channel(1) command.
25
26       When context fields are added to a channel, all the events emitted
27       within this channel contain the dynamic values of those context fields.
28
29       If the --session option is omitted, the current tracing session is
30       used. If the --channel option is omitted, the context fields are added
31       to all the selected tracing session’s channels.
32
33       Many context fields can be added to a channel at once by repeating the
34       --type option.
35
36       perf counters are available as per-CPU (perf:cpu: prefix) as well as
37       per-thread (perf:thread: prefix) counters. Currently, per-CPU counters
38       can only be used in the Linux kernel tracing domain, while per-thread
39       counters can only be used in the user space tracing domain.
40
41       It is also possible to enable PMU counters by raw ID using the
42       perf:cpu:raw:rN:NAME (Linux kernel tracing domain) or
43       perf:thread:raw:rN:NAME (user space tracing domain), with:
44
45       N
46           A hexadecimal event descriptor which is the same format as used by
47           perf-record(1): a concatenation of the event number and umask value
48           provided by the processor’s manufacturer. The possible values for
49           this field are processor-specific.
50
51       NAME
52           Custom name to easily recognize the counter.
53
54       Application-specific context fields can be added to a channel using the
55       following syntax:
56
57           $app.PROVIDER:TYPE
58
59       with:
60
61       PROVIDER
62           Provider name.
63
64       TYPE
65           Context type name.
66
67           Note
68           Make sure to single-quote the type when running the command from a
69           shell, as $ is a special character for variable substitution in
70           most shells.
71
72       Use the --list option without other arguments to list the available
73       context field names.
74
75       See the LIMITATIONS section below for a list of limitations to
76       consider.
77

OPTIONS

79       General options are described in lttng(1).
80
81   Domain
82       One of:
83
84       -j, --jul
85           Add context to channel in the java.util.logging (JUL) domain.
86
87       -k, --kernel
88           Add context to channel in the Linux kernel domain.
89
90       -l, --log4j
91           Add context to channel in the Apache log4j domain.
92
93       -u, --userspace
94           Add context to channel in the user space domain.
95
96   Target
97       -c CHANNEL, --channel=CHANNEL
98           Add context fields to a channel named CHANNEL instead of adding
99           them to all the channels.
100
101       -s SESSION, --session=SESSION
102           Add context fields to a channel in the tracing session named
103           SESSION instead of the current tracing session.
104
105   Context
106       --list
107           List the available context fields. Use this option alone.
108
109       -t TYPE, --type=TYPE
110           Add context field named TYPE. This option can be repeated as many
111           times as needed on the command-line.
112
113   Program information
114       -h, --help
115           Show command help.
116
117           This option, like lttng-help(1), attempts to launch /usr/bin/man to
118           view the command’s man page. The path to the man pager can be
119           overridden by the LTTNG_MAN_BIN_PATH environment variable.
120
121       --list-options
122           List available command options.
123

LIMITATIONS

125       As of this version of LTTng, it is not possible to add context fields
126       to a channel once its tracing session has been started (see lttng-
127       start(1)) at least once.
128

ENVIRONMENT VARIABLES

130       LTTNG_ABORT_ON_ERROR
131           Set to 1 to abort the process after the first error is encountered.
132
133       LTTNG_HOME
134           Overrides the $HOME environment variable. Useful when the user
135           running the commands has a non-writable home directory.
136
137       LTTNG_MAN_BIN_PATH
138           Absolute path to the man pager to use for viewing help information
139           about LTTng commands (using lttng-help(1) or lttng COMMAND --help).
140
141       LTTNG_SESSION_CONFIG_XSD_PATH
142           Path in which the session.xsd session configuration XML schema may
143           be found.
144
145       LTTNG_SESSIOND_PATH
146           Full session daemon binary path.
147
148           The --sessiond-path option has precedence over this environment
149           variable.
150
151       Note that the lttng-create(1) command can spawn an LTTng session daemon
152       automatically if none is running. See lttng-sessiond(8) for the
153       environment variables influencing the execution of the session daemon.
154

FILES

156       $LTTNG_HOME/.lttngrc
157           User LTTng runtime configuration.
158
159           This is where the per-user current tracing session is stored
160           between executions of lttng(1). The current tracing session can be
161           set with lttng-set-session(1). See lttng-create(1) for more
162           information about tracing sessions.
163
164       $LTTNG_HOME/lttng-traces
165           Default output directory of LTTng traces. This can be overridden
166           with the --output option of the lttng-create(1) command.
167
168       $LTTNG_HOME/.lttng
169           User LTTng runtime and configuration directory.
170
171       $LTTNG_HOME/.lttng/sessions
172           Default location of saved user tracing sessions (see lttng-save(1)
173           and lttng-load(1)).
174
175       /usr/local/etc/lttng/sessions
176           System-wide location of saved tracing sessions (see lttng-save(1)
177           and lttng-load(1)).
178
179           Note
180           $LTTNG_HOME defaults to $HOME when not explicitly set.
181

EXIT STATUS

183       0
184           Success
185
186       1
187           Command error
188
189       2
190           Undefined command
191
192       3
193           Fatal error
194
195       4
196           Command warning (something went wrong during the command)
197

BUGS

199       If you encounter any issue or usability problem, please report it on
200       the LTTng bug tracker <https://bugs.lttng.org/projects/lttng-tools>.
201

RESOURCES

203       •   LTTng project website <https://lttng.org>
204
205       •   LTTng documentation <https://lttng.org/docs>
206
207       •   Git repositories <http://git.lttng.org>
208
209       •   GitHub organization <http://github.com/lttng>
210
211       •   Continuous integration <http://ci.lttng.org/>
212
213       •   Mailing list <http://lists.lttng.org> for support and development:
214           lttng-dev@lists.lttng.org
215
216       •   IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
217

COPYRIGHTS

219       This program is part of the LTTng-tools project.
220
221       LTTng-tools is distributed under the GNU General Public License version
222       2 <http://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html>. See the
223       LICENSE <https://github.com/lttng/lttng-tools/blob/master/LICENSE> file
224       for details.
225

THANKS

227       Special thanks to Michel Dagenais and the DORSAL laboratory
228       <http://www.dorsal.polymtl.ca/> at École Polytechnique de Montréal for
229       the LTTng journey.
230
231       Also thanks to the Ericsson teams working on tracing which helped us
232       greatly with detailed bug reports and unusual test cases.
233