scope-exit: Clarify scope_exit noexcept requirement
[lttng-tools.git] / doc / man / lttng-add-context.1.txt
CommitLineData
2e4886b8
PP
1lttng-add-context(1)
2====================
e9711845 3:revdate: 14 June 2021
2e4886b8
PP
4
5
6NAME
7----
484b2a0c 8lttng-add-context - Add context fields to be recorded by LTTng
2e4886b8
PP
9
10
11SYNOPSIS
12--------
26f0c779
PP
13Add context fields to be recorded to the event records of one or more
14channels:
2e4886b8
PP
15
16[verse]
ce19b9ed 17*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *add-context*
2e4886b8
PP
18 (option:--kernel | option:--userspace | option:--jul | option:--log4j)
19 [option:--session='SESSION'] [option:--channel='CHANNEL']
20 option:--type='TYPE' [option:--type='TYPE']...
21
484b2a0c 22List the available context field types:
2e4886b8
PP
23
24[verse]
d1cff337 25*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *add-context* option:--list
2e4886b8
PP
26
27
28DESCRIPTION
29-----------
26f0c779 30The `lttng add-context` command can:
484b2a0c 31
26f0c779
PP
32Without the option:--list option::
33 Add one or more context fields to be recorded by LTTng to the event
f14111c9 34 records of:
26f0c779
PP
35+
36With the option:--session='SESSION' option:::
e9711845 37 The recording session named 'SESSION'.
26f0c779
PP
38
39Without the option:--session option:::
e9711845
PP
40 The current recording session (see man:lttng-concepts(7) to learn
41 more about the current recording session).
484b2a0c 42
f14111c9
PP
43With the option:--channel='CHANNEL':::
44 The channel named 'CHANNEL'.
45
46Without the option:--channel option:::
e9711845 47 *All* the channels of the selected recording session.
f14111c9 48
26f0c779
PP
49With the option:--list option::
50 List the available context field types.
484b2a0c 51
e9711845 52See man:lttng-concepts(7) to learn more about recording sessions and
26f0c779 53channels.
484b2a0c 54
26f0c779
PP
55Repeat the option:--type='TYPE' option to add more than one context
56field to be recorded. 'TYPE' is one of:
484b2a0c 57
d1e97bd6 58* A statically-known, or built-in context field name.
484b2a0c 59
26f0c779
PP
60* A perf counter name:
61+
62--
484b2a0c 63Per-CPU::
26f0c779 64 Prefix: `perf:cpu:`
484b2a0c 65+
26f0c779 66Only available with the option:--kernel option.
484b2a0c
PP
67
68Per-thread::
26f0c779 69 Prefix: `perf:thread:`
484b2a0c 70+
26f0c779
PP
71Only available with the option:--userspace, option:--jul, or
72option:--log4j option.
73--
74+
75Add Performance Monitoring Unit (PMU) counter context fields by raw ID
76with the ++perf:cpu:raw:r++__N__++:++__NAME__ (option:--kernel option)
77or ++perf:thread:raw:r++__N__++:++__NAME__ (option:--userspace,
78option:--jul, or option:--log4j option) types, with:
79+
80--
484b2a0c
PP
81'N'::
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.
85+
26f0c779 86The possible values for this part are processor-specific.
484b2a0c
PP
87
88'NAME'::
26f0c779
PP
89 Custom name to identify the counter.
90--
2e4886b8 91
26f0c779
PP
92* An LTTng application-specific context field name:
93+
ed0a071d 94--
2e4886b8
PP
95[verse]
96$app.'PROVIDER':__TYPE__
26f0c779 97+
2e4886b8
PP
98'PROVIDER'::
99 Provider name.
100
101'TYPE'::
102 Context type name.
ed0a071d
PP
103--
104+
105Only available with the option:--jul and option:--log4j options.
2e4886b8 106
26f0c779
PP
107IMPORTANT: Make sure to **single-quote** 'TYPE' when you run the
108`add-context` command from a shell, as `$` is a special character for
109variable substitution in most shells.
484b2a0c 110
26f0c779 111NOTE: As of LTTng{nbsp}{lttng_version}, you may :not: add context fields
e9711845
PP
112to be recorded to the event records of a given channel once its
113recording session has been started (see man:lttng-start(1)) at least
114once.
2e4886b8 115
da39b67c 116See the ``<<examples,EXAMPLES>>'' section below for usage examples.
ed0a071d 117
2e4886b8 118
f5511eea 119include::common-lttng-cmd-options-head.txt[]
2e4886b8
PP
120
121
484b2a0c
PP
122Tracing domain
123~~~~~~~~~~~~~~
2e4886b8
PP
124One of:
125
126option:-j, option:--jul::
484b2a0c
PP
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.
2e4886b8
PP
129
130option:-k, option:--kernel::
484b2a0c
PP
131 Add context fields to be recorded to the event records of one or
132 more channels of the Linux kernel tracing domain.
2e4886b8
PP
133
134option:-l, option:--log4j::
484b2a0c
PP
135 Add context fields to be recorded to the event records of one or
136 more channels of the Apache log4j tracing domain.
2e4886b8
PP
137
138option:-u, option:--userspace::
484b2a0c
PP
139 Add context fields to be recorded to the event records of one or
140 more channels of the user space tracing domain.
2e4886b8
PP
141
142
484b2a0c
PP
143Recording target
144~~~~~~~~~~~~~~~~
59b19c3c 145option:-c 'CHANNEL', option:--channel='CHANNEL'::
484b2a0c
PP
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
e9711845 148 recording session.
2e4886b8 149
59b19c3c 150option:-s 'SESSION', option:--session='SESSION'::
484b2a0c 151 Add context fields to be recorded to the event records of one or
e9711845
PP
152 more channels of the recording session named 'SESSION' instead of
153 the current recording session.
2e4886b8
PP
154
155
484b2a0c
PP
156Context field type
157~~~~~~~~~~~~~~~~~~
2e4886b8 158option:--list::
484b2a0c
PP
159 List the available context field types.
160+
161You may :not: use this option with the option:--channel,
162option:--session, or option:--type options.
2e4886b8 163
59b19c3c 164option:-t 'TYPE', option:--type='TYPE'::
484b2a0c
PP
165 Add a context field having the type 'TYPE' to be recorded.
166+
167Repeat this option to add more than one context field.
2e4886b8
PP
168
169
f5511eea 170include::common-lttng-cmd-help-options.txt[]
2e4886b8
PP
171
172
f5511eea
PP
173include::common-lttng-cmd-after-options.txt[]
174
175
ed0a071d
PP
176[[examples]]
177EXAMPLES
178--------
179.List the available context field types.
180====
181See the option:--list option.
182
183[role="term"]
184----
185$ lttng add-context --list
186----
187====
188
e9711845 189.Add a single statically-known context field to be recorded to all the Linux kernel channels of the current recording session.
ed0a071d
PP
190====
191[role="term"]
192----
193$ lttng add-context --kernel --type=pid
194----
195====
196
e9711845 197.Add three statically-known context fields to be recorded to a specific user space channel of a specific recording session.
ed0a071d 198====
dca99295
PP
199See the option:--session and option:--channel options.
200
ed0a071d
PP
201[role="term"]
202----
203$ lttng add-context --userspace --session=my-session \
204 --channel=my-channel \
205 --type=vpid --type=procname --type=ip
206----
207====
208
e9711845 209.Add a perf counter context field to be recorded to a specific Linux kernel channel of the current recording session.
ed0a071d 210====
dca99295
PP
211See the option:--channel option.
212
ed0a071d
PP
213[role="term"]
214----
215$ lttng add-context --kernel --channel=my-channel \
216 --type=perf:cpu:cache-misses
217----
218====
219
e9711845 220.Add an LTTng application-specific context field to be recorded to all the JUL channels of the current recording session.
ed0a071d
PP
221====
222[role="term"]
223----
224$ lttng add-context --jul --type='$app.my_server:user_cnt'
225----
226====
227
228
f5511eea 229include::common-footer.txt[]
2e4886b8
PP
230
231
232SEE ALSO
233--------
484b2a0c 234man:lttng(1),
af1c4164
PP
235man:lttng-enable-channel(1),
236man:lttng-concepts(7)
This page took 0.057747 seconds and 5 git commands to generate.