Commit | Line | Data |
---|---|---|
2e4886b8 PP |
1 | lttng-add-context(1) |
2 | ==================== | |
26f0c779 | 3 | :revdate: 3 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 | + | |
2e4886b8 PP |
94 | [verse] |
95 | $app.'PROVIDER':__TYPE__ | |
26f0c779 | 96 | + |
2e4886b8 PP |
97 | 'PROVIDER':: |
98 | Provider name. | |
99 | ||
100 | 'TYPE':: | |
101 | Context type name. | |
102 | ||
26f0c779 PP |
103 | IMPORTANT: Make sure to **single-quote** 'TYPE' when you run the |
104 | `add-context` command from a shell, as `$` is a special character for | |
105 | variable substitution in most shells. | |
484b2a0c | 106 | |
26f0c779 PP |
107 | NOTE: As of LTTng{nbsp}{lttng_version}, you may :not: add context fields |
108 | to be recorded to the event records of a given channel once its tracing | |
109 | session has been started (see man:lttng-start(1)) at least once. | |
2e4886b8 PP |
110 | |
111 | ||
f5511eea | 112 | include::common-lttng-cmd-options-head.txt[] |
2e4886b8 PP |
113 | |
114 | ||
484b2a0c PP |
115 | Tracing domain |
116 | ~~~~~~~~~~~~~~ | |
2e4886b8 PP |
117 | One of: |
118 | ||
119 | option:-j, option:--jul:: | |
484b2a0c PP |
120 | Add context fields to be recorded to the event records of one or |
121 | more channels of the `java.util.logging` (JUL) tracing domain. | |
2e4886b8 PP |
122 | |
123 | option:-k, option:--kernel:: | |
484b2a0c PP |
124 | Add context fields to be recorded to the event records of one or |
125 | more channels of the Linux kernel tracing domain. | |
2e4886b8 PP |
126 | |
127 | option:-l, option:--log4j:: | |
484b2a0c PP |
128 | Add context fields to be recorded to the event records of one or |
129 | more channels of the Apache log4j tracing domain. | |
2e4886b8 PP |
130 | |
131 | option:-u, option:--userspace:: | |
484b2a0c PP |
132 | Add context fields to be recorded to the event records of one or |
133 | more channels of the user space tracing domain. | |
2e4886b8 PP |
134 | |
135 | ||
484b2a0c PP |
136 | Recording target |
137 | ~~~~~~~~~~~~~~~~ | |
59b19c3c | 138 | option:-c 'CHANNEL', option:--channel='CHANNEL':: |
484b2a0c PP |
139 | Add context fields to be recorded to the event records of a channel |
140 | named 'CHANNEL' instead of all the channels of the selected | |
141 | tracing session. | |
2e4886b8 | 142 | |
59b19c3c | 143 | option:-s 'SESSION', option:--session='SESSION':: |
484b2a0c PP |
144 | Add context fields to be recorded to the event records of one or |
145 | more channels of the tracing session named 'SESSION' instead of the | |
146 | current tracing session. | |
2e4886b8 PP |
147 | |
148 | ||
484b2a0c PP |
149 | Context field type |
150 | ~~~~~~~~~~~~~~~~~~ | |
2e4886b8 | 151 | option:--list:: |
484b2a0c PP |
152 | List the available context field types. |
153 | + | |
154 | You may :not: use this option with the option:--channel, | |
155 | option:--session, or option:--type options. | |
2e4886b8 | 156 | |
59b19c3c | 157 | option:-t 'TYPE', option:--type='TYPE':: |
484b2a0c PP |
158 | Add a context field having the type 'TYPE' to be recorded. |
159 | + | |
160 | Repeat this option to add more than one context field. | |
2e4886b8 PP |
161 | |
162 | ||
f5511eea | 163 | include::common-lttng-cmd-help-options.txt[] |
2e4886b8 PP |
164 | |
165 | ||
f5511eea PP |
166 | include::common-lttng-cmd-after-options.txt[] |
167 | ||
168 | ||
169 | include::common-footer.txt[] | |
2e4886b8 PP |
170 | |
171 | ||
172 | SEE ALSO | |
173 | -------- | |
484b2a0c | 174 | man:lttng(1), |
af1c4164 PP |
175 | man:lttng-enable-channel(1), |
176 | man:lttng-concepts(7) |