Commit | Line | Data |
---|---|---|
2e4886b8 PP |
1 | lttng-add-context(1) |
2 | ==================== | |
ed0a071d | 3 | :revdate: 6 May 2021 |
2e4886b8 PP |
4 | |
5 | ||
6 | NAME | |
7 | ---- | |
484b2a0c | 8 | lttng-add-context - Add context fields to be recorded by LTTng |
2e4886b8 PP |
9 | |
10 | ||
11 | SYNOPSIS | |
12 | -------- | |
26f0c779 PP |
13 | Add context fields to be recorded to the event records of one or more |
14 | channels: | |
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 | 22 | List the available context field types: |
2e4886b8 PP |
23 | |
24 | [verse] | |
d1cff337 | 25 | *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *add-context* option:--list |
2e4886b8 PP |
26 | |
27 | ||
28 | DESCRIPTION | |
29 | ----------- | |
26f0c779 | 30 | The `lttng add-context` command can: |
484b2a0c | 31 | |
26f0c779 PP |
32 | Without 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 | + |
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). | |
484b2a0c | 42 | |
f14111c9 PP |
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 | ||
26f0c779 PP |
49 | With the option:--list option:: |
50 | List the available context field types. | |
484b2a0c | 51 | |
26f0c779 PP |
52 | See man:lttng-concepts(7) to learn more about tracing sessions and |
53 | channels. | |
484b2a0c | 54 | |
26f0c779 PP |
55 | Repeat the option:--type='TYPE' option to add more than one context |
56 | field to be recorded. 'TYPE' is one of: | |
484b2a0c | 57 | |
26f0c779 | 58 | * A statically-known, or built-in context field named. |
484b2a0c | 59 | |
26f0c779 PP |
60 | * A perf counter name: |
61 | + | |
62 | -- | |
484b2a0c | 63 | Per-CPU:: |
26f0c779 | 64 | Prefix: `perf:cpu:` |
484b2a0c | 65 | + |
26f0c779 | 66 | Only available with the option:--kernel option. |
484b2a0c PP |
67 | |
68 | Per-thread:: | |
26f0c779 | 69 | Prefix: `perf:thread:` |
484b2a0c | 70 | + |
26f0c779 PP |
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 | -- | |
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 | 86 | The 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 | + | |
105 | Only available with the option:--jul and option:--log4j options. | |
2e4886b8 | 106 | |
26f0c779 PP |
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. | |
484b2a0c | 110 | |
26f0c779 PP |
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. | |
2e4886b8 | 114 | |
ed0a071d PP |
115 | See the <<examples,EXAMPLES>> section below for usage examples. |
116 | ||
2e4886b8 | 117 | |
f5511eea | 118 | include::common-lttng-cmd-options-head.txt[] |
2e4886b8 PP |
119 | |
120 | ||
484b2a0c PP |
121 | Tracing domain |
122 | ~~~~~~~~~~~~~~ | |
2e4886b8 PP |
123 | One of: |
124 | ||
125 | option:-j, option:--jul:: | |
484b2a0c PP |
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. | |
2e4886b8 PP |
128 | |
129 | option:-k, option:--kernel:: | |
484b2a0c PP |
130 | Add context fields to be recorded to the event records of one or |
131 | more channels of the Linux kernel tracing domain. | |
2e4886b8 PP |
132 | |
133 | option:-l, option:--log4j:: | |
484b2a0c PP |
134 | Add context fields to be recorded to the event records of one or |
135 | more channels of the Apache log4j tracing domain. | |
2e4886b8 PP |
136 | |
137 | option:-u, option:--userspace:: | |
484b2a0c PP |
138 | Add context fields to be recorded to the event records of one or |
139 | more channels of the user space tracing domain. | |
2e4886b8 PP |
140 | |
141 | ||
484b2a0c PP |
142 | Recording target |
143 | ~~~~~~~~~~~~~~~~ | |
59b19c3c | 144 | option:-c 'CHANNEL', option:--channel='CHANNEL':: |
484b2a0c PP |
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. | |
2e4886b8 | 148 | |
59b19c3c | 149 | option:-s 'SESSION', option:--session='SESSION':: |
484b2a0c PP |
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. | |
2e4886b8 PP |
153 | |
154 | ||
484b2a0c PP |
155 | Context field type |
156 | ~~~~~~~~~~~~~~~~~~ | |
2e4886b8 | 157 | option:--list:: |
484b2a0c PP |
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. | |
2e4886b8 | 162 | |
59b19c3c | 163 | option:-t 'TYPE', option:--type='TYPE':: |
484b2a0c PP |
164 | Add a context field having the type 'TYPE' to be recorded. |
165 | + | |
166 | Repeat this option to add more than one context field. | |
2e4886b8 PP |
167 | |
168 | ||
f5511eea | 169 | include::common-lttng-cmd-help-options.txt[] |
2e4886b8 PP |
170 | |
171 | ||
f5511eea PP |
172 | include::common-lttng-cmd-after-options.txt[] |
173 | ||
174 | ||
ed0a071d PP |
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 | ==== | |
dca99295 PP |
198 | See the option:--session and option:--channel options. |
199 | ||
ed0a071d PP |
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 | ==== | |
dca99295 PP |
210 | See the option:--channel option. |
211 | ||
ed0a071d PP |
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 | ||
f5511eea | 228 | include::common-footer.txt[] |
2e4886b8 PP |
229 | |
230 | ||
231 | SEE ALSO | |
232 | -------- | |
484b2a0c | 233 | man:lttng(1), |
af1c4164 PP |
234 | man:lttng-enable-channel(1), |
235 | man:lttng-concepts(7) |