38b77617ee52d568893072e2418a3ee02c25944f
[lttng-tools.git] / doc / man / lttng-add-context.1.txt
1 lttng-add-context(1)
2 ====================
3 :revdate: 6 May 2021
4
5
6 NAME
7 ----
8 lttng-add-context - Add context fields to be recorded by LTTng
9
10
11 SYNOPSIS
12 --------
13 Add context fields to be recorded to the event records of one or more
14 channels:
15
16 [verse]
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']...
21
22 List the available context field types:
23
24 [verse]
25 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *add-context* option:--list
26
27
28 DESCRIPTION
29 -----------
30 The `lttng add-context` command can:
31
32 Without the option:--list option::
33 Add one or more context fields to be recorded by LTTng to the event
34 records of:
35 +
36 With the option:--session='SESSION' option:::
37 The tracing session named 'SESSION'.
38
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).
42
43 With the option:--channel='CHANNEL':::
44 The channel named 'CHANNEL'.
45
46 Without the option:--channel option:::
47 *All* the channels of the selected tracing session.
48
49 With the option:--list option::
50 List the available context field types.
51
52 See man:lttng-concepts(7) to learn more about tracing sessions and
53 channels.
54
55 Repeat the option:--type='TYPE' option to add more than one context
56 field to be recorded. 'TYPE' is one of:
57
58 * A statically-known, or built-in context field named.
59
60 * A perf counter name:
61 +
62 --
63 Per-CPU::
64 Prefix: `perf:cpu:`
65 +
66 Only available with the option:--kernel option.
67
68 Per-thread::
69 Prefix: `perf:thread:`
70 +
71 Only available with the option:--userspace, option:--jul, or
72 option:--log4j option.
73 --
74 +
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:
79 +
80 --
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 +
86 The possible values for this part are processor-specific.
87
88 'NAME'::
89 Custom name to identify the counter.
90 --
91
92 * An LTTng application-specific context field name:
93 +
94 --
95 [verse]
96 $app.'PROVIDER':__TYPE__
97 +
98 'PROVIDER'::
99 Provider name.
100
101 'TYPE'::
102 Context type name.
103 --
104 +
105 Only available with the option:--jul and option:--log4j options.
106
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.
110
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.
114
115 See the ``<<examples,EXAMPLES>>'' section below for usage examples.
116
117
118 include::common-lttng-cmd-options-head.txt[]
119
120
121 Tracing domain
122 ~~~~~~~~~~~~~~
123 One of:
124
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.
128
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.
132
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.
136
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.
140
141
142 Recording target
143 ~~~~~~~~~~~~~~~~
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
147 tracing session.
148
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.
153
154
155 Context field type
156 ~~~~~~~~~~~~~~~~~~
157 option:--list::
158 List the available context field types.
159 +
160 You may :not: use this option with the option:--channel,
161 option:--session, or option:--type options.
162
163 option:-t 'TYPE', option:--type='TYPE'::
164 Add a context field having the type 'TYPE' to be recorded.
165 +
166 Repeat this option to add more than one context field.
167
168
169 include::common-lttng-cmd-help-options.txt[]
170
171
172 include::common-lttng-cmd-after-options.txt[]
173
174
175 [[examples]]
176 EXAMPLES
177 --------
178 .List the available context field types.
179 ====
180 See the option:--list option.
181
182 [role="term"]
183 ----
184 $ lttng add-context --list
185 ----
186 ====
187
188 .Add a single statically-known context field to be recorded to all the Linux kernel channels of the current tracing session.
189 ====
190 [role="term"]
191 ----
192 $ lttng add-context --kernel --type=pid
193 ----
194 ====
195
196 .Add three statically-known context fields to be recorded to a specific user space channel of a specific tracing session.
197 ====
198 See the option:--session and option:--channel options.
199
200 [role="term"]
201 ----
202 $ lttng add-context --userspace --session=my-session \
203 --channel=my-channel \
204 --type=vpid --type=procname --type=ip
205 ----
206 ====
207
208 .Add a perf counter context field to be recorded to a specific Linux kernel channel of the current tracing session.
209 ====
210 See the option:--channel option.
211
212 [role="term"]
213 ----
214 $ lttng add-context --kernel --channel=my-channel \
215 --type=perf:cpu:cache-misses
216 ----
217 ====
218
219 .Add an LTTng application-specific context field to be recorded to all the JUL channels of the current tracing session.
220 ====
221 [role="term"]
222 ----
223 $ lttng add-context --jul --type='$app.my_server:user_cnt'
224 ----
225 ====
226
227
228 include::common-footer.txt[]
229
230
231 SEE ALSO
232 --------
233 man:lttng(1),
234 man:lttng-enable-channel(1),
235 man:lttng-concepts(7)
This page took 0.035657 seconds and 5 git commands to generate.