Commit | Line | Data |
---|---|---|
2e4886b8 PP |
1 | lttng-add-context(1) |
2 | ==================== | |
188419c4 | 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 | -------- | |
188419c4 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 | ----------- | |
188419c4 | 30 | The `lttng add-context` command can: |
484b2a0c | 31 | |
188419c4 PP |
32 | Without the option:--list option:: |
33 | Add one or more context fields to be recorded by LTTng to the event | |
34 | records of a given channel, or of all the channels 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). | |
484b2a0c | 42 | |
188419c4 PP |
43 | With the option:--list option:: |
44 | List the available context field types. | |
484b2a0c | 45 | |
188419c4 PP |
46 | See man:lttng-concepts(7) to learn more about tracing sessions and |
47 | channels. | |
484b2a0c PP |
48 | |
49 | Without the option:--channel option, LTTng adds context fields to be | |
50 | recorded to the event records of *all* the channels of the selected | |
51 | tracing session. | |
52 | ||
188419c4 PP |
53 | Repeat the option:--type='TYPE' option to add more than one context |
54 | field to be recorded. 'TYPE' is one of: | |
484b2a0c | 55 | |
188419c4 | 56 | * A statically-known, or built-in context field named. |
484b2a0c | 57 | |
188419c4 PP |
58 | * A perf counter name: |
59 | + | |
60 | -- | |
484b2a0c | 61 | Per-CPU:: |
188419c4 | 62 | Prefix: `perf:cpu:` |
484b2a0c | 63 | + |
188419c4 | 64 | Only available with the option:--kernel option. |
484b2a0c PP |
65 | |
66 | Per-thread:: | |
188419c4 | 67 | Prefix: `perf:thread:` |
484b2a0c | 68 | + |
188419c4 PP |
69 | Only available with the option:--userspace, option:--jul, or |
70 | option:--log4j option. | |
71 | -- | |
72 | + | |
73 | Add Performance Monitoring Unit (PMU) counter context fields by raw ID | |
74 | with the ++perf:cpu:raw:r++__N__++:++__NAME__ (option:--kernel option) | |
75 | or ++perf:thread:raw:r++__N__++:++__NAME__ (option:--userspace, | |
76 | option:--jul, or option:--log4j option) types, with: | |
77 | + | |
78 | -- | |
484b2a0c PP |
79 | 'N':: |
80 | A hexadecimal event descriptor which follows the man:perf-record(1) | |
81 | format: a concatenation of the event number and umask value which | |
82 | the manufacturer of the processor provides. | |
83 | + | |
188419c4 | 84 | The possible values for this part are processor-specific. |
484b2a0c PP |
85 | |
86 | 'NAME':: | |
188419c4 PP |
87 | Custom name to identify the counter. |
88 | -- | |
2e4886b8 | 89 | |
188419c4 PP |
90 | * An LTTng application-specific context field name: |
91 | + | |
2e4886b8 PP |
92 | [verse] |
93 | $app.'PROVIDER':__TYPE__ | |
188419c4 | 94 | + |
2e4886b8 PP |
95 | 'PROVIDER':: |
96 | Provider name. | |
97 | ||
98 | 'TYPE':: | |
99 | Context type name. | |
100 | ||
188419c4 PP |
101 | IMPORTANT: Make sure to **single-quote** 'TYPE' when you run the |
102 | `add-context` command from a shell, as `$` is a special character for | |
103 | variable substitution in most shells. | |
484b2a0c | 104 | |
188419c4 PP |
105 | NOTE: As of LTTng{nbsp}{lttng_version}, you may :not: add context fields |
106 | to be recorded to the event records of a given channel once its tracing | |
107 | session has been started (see man:lttng-start(1)) at least once. | |
2e4886b8 PP |
108 | |
109 | ||
110 | include::common-cmd-options-head.txt[] | |
111 | ||
112 | ||
484b2a0c PP |
113 | Tracing domain |
114 | ~~~~~~~~~~~~~~ | |
2e4886b8 PP |
115 | One of: |
116 | ||
117 | option:-j, option:--jul:: | |
484b2a0c PP |
118 | Add context fields to be recorded to the event records of one or |
119 | more channels of the `java.util.logging` (JUL) tracing domain. | |
2e4886b8 PP |
120 | |
121 | option:-k, option:--kernel:: | |
484b2a0c PP |
122 | Add context fields to be recorded to the event records of one or |
123 | more channels of the Linux kernel tracing domain. | |
2e4886b8 PP |
124 | |
125 | option:-l, option:--log4j:: | |
484b2a0c PP |
126 | Add context fields to be recorded to the event records of one or |
127 | more channels of the Apache log4j tracing domain. | |
2e4886b8 PP |
128 | |
129 | option:-u, option:--userspace:: | |
484b2a0c PP |
130 | Add context fields to be recorded to the event records of one or |
131 | more channels of the user space tracing domain. | |
2e4886b8 PP |
132 | |
133 | ||
484b2a0c PP |
134 | Recording target |
135 | ~~~~~~~~~~~~~~~~ | |
59b19c3c | 136 | option:-c 'CHANNEL', option:--channel='CHANNEL':: |
484b2a0c PP |
137 | Add context fields to be recorded to the event records of a channel |
138 | named 'CHANNEL' instead of all the channels of the selected | |
139 | tracing session. | |
2e4886b8 | 140 | |
59b19c3c | 141 | option:-s 'SESSION', option:--session='SESSION':: |
484b2a0c PP |
142 | Add context fields to be recorded to the event records of one or |
143 | more channels of the tracing session named 'SESSION' instead of the | |
144 | current tracing session. | |
2e4886b8 PP |
145 | |
146 | ||
484b2a0c PP |
147 | Context field type |
148 | ~~~~~~~~~~~~~~~~~~ | |
2e4886b8 | 149 | option:--list:: |
484b2a0c PP |
150 | List the available context field types. |
151 | + | |
152 | You may :not: use this option with the option:--channel, | |
153 | option:--session, or option:--type options. | |
2e4886b8 | 154 | |
59b19c3c | 155 | option:-t 'TYPE', option:--type='TYPE':: |
484b2a0c PP |
156 | Add a context field having the type 'TYPE' to be recorded. |
157 | + | |
158 | Repeat this option to add more than one context field. | |
2e4886b8 PP |
159 | |
160 | ||
161 | include::common-cmd-help-options.txt[] | |
162 | ||
163 | ||
164 | include::common-cmd-footer.txt[] | |
165 | ||
166 | ||
167 | SEE ALSO | |
168 | -------- | |
484b2a0c | 169 | man:lttng(1), |
188419c4 PP |
170 | man:lttng-concepts(7), |
171 | man:lttng-enable-channel(1) |