Commit | Line | Data |
---|---|---|
2e4886b8 PP |
1 | lttng-add-context(1) |
2 | ==================== | |
4605890e | 3 | :revdate: 5 Februrary 2018 |
2e4886b8 PP |
4 | |
5 | ||
6 | NAME | |
7 | ---- | |
8 | lttng-add-context - Add context fields to an LTTng channel | |
9 | ||
10 | ||
11 | SYNOPSIS | |
12 | -------- | |
13 | Add context fields to a channel: | |
14 | ||
15 | [verse] | |
ce19b9ed | 16 | *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *add-context* |
2e4886b8 PP |
17 | (option:--kernel | option:--userspace | option:--jul | option:--log4j) |
18 | [option:--session='SESSION'] [option:--channel='CHANNEL'] | |
19 | option:--type='TYPE' [option:--type='TYPE']... | |
20 | ||
21 | List the available context fields: | |
22 | ||
23 | [verse] | |
d1cff337 | 24 | *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *add-context* option:--list |
2e4886b8 PP |
25 | |
26 | ||
27 | DESCRIPTION | |
28 | ----------- | |
29 | The `lttng add-context` command adds one or more context fields to a | |
30 | channel. | |
31 | ||
7c1a4458 | 32 | Channels are created with the man:lttng-enable-channel(1) command. |
2e4886b8 PP |
33 | |
34 | When context fields are added to a channel, all the events emitted | |
35 | within this channel contain the dynamic values of those context fields. | |
36 | ||
37 | If the option:--session option is omitted, the current tracing session | |
38 | is used. If the option:--channel option is omitted, the context fields | |
39 | are added to all the selected tracing session's channels. | |
40 | ||
41 | Many context fields can be added to a channel at once by repeating the | |
42 | option:--type option. | |
43 | ||
44 | perf counters are available as per-CPU (`perf:cpu:` prefix) as well as | |
45 | per-thread (`perf:thread:` prefix) counters. Currently, per-CPU counters | |
46 | can only be used in the Linux kernel tracing domain, while per-thread | |
47 | counters can only be used in the user space tracing domain. | |
48 | ||
4fe444da | 49 | It is also possible to enable PMU counters by raw ID using the |
954eb3bf PP |
50 | `perf:cpu:raw:rN:NAME` (Linux kernel tracing domain) or |
51 | `perf:thread:raw:rN:NAME` (user space tracing domain), with: | |
52 | ||
53 | `N`:: | |
54 | A hexadecimal event descriptor which is the same format as used | |
deb35f49 | 55 | by man:perf-record(1): a concatenation of the event number and umask |
954eb3bf PP |
56 | value provided by the processor's manufacturer. The possible values |
57 | for this field are processor-specific. | |
58 | ||
59 | `NAME`:: | |
60 | Custom name to easily recognize the counter. | |
4fe444da | 61 | |
2e4886b8 PP |
62 | Application-specific context fields can be added to a channel using the |
63 | following syntax: | |
64 | ||
65 | [verse] | |
66 | $app.'PROVIDER':__TYPE__ | |
67 | ||
68 | with: | |
69 | ||
70 | 'PROVIDER':: | |
71 | Provider name. | |
72 | ||
73 | 'TYPE':: | |
74 | Context type name. | |
75 | ||
60f7980c PP |
76 | NOTE: Make sure to **single-quote** the type when running the command |
77 | from a shell, as `$` is a special character for variable substitution in | |
78 | most shells. | |
79 | ||
2e4886b8 PP |
80 | Use the option:--list option without other arguments to list the |
81 | available context field names. | |
82 | ||
15623b7d JR |
83 | See the <<limitations,LIMITATIONS>> section below for a list of |
84 | limitations to consider. | |
2e4886b8 PP |
85 | |
86 | include::common-cmd-options-head.txt[] | |
87 | ||
88 | ||
89 | Domain | |
90 | ~~~~~~ | |
91 | One of: | |
92 | ||
93 | option:-j, option:--jul:: | |
94 | Add context to channel in the `java.util.logging` (JUL) domain. | |
95 | ||
96 | option:-k, option:--kernel:: | |
97 | Add context to channel in the Linux kernel domain. | |
98 | ||
99 | option:-l, option:--log4j:: | |
100 | Add context to channel in the Apache log4j domain. | |
101 | ||
102 | option:-u, option:--userspace:: | |
103 | Add context to channel in the user space domain. | |
104 | ||
105 | ||
106 | Target | |
107 | ~~~~~~ | |
59b19c3c | 108 | option:-c 'CHANNEL', option:--channel='CHANNEL':: |
2e4886b8 PP |
109 | Add context fields to a channel named 'CHANNEL' instead of adding |
110 | them to all the channels. | |
111 | ||
59b19c3c | 112 | option:-s 'SESSION', option:--session='SESSION':: |
2e4886b8 PP |
113 | Add context fields to a channel in the tracing session named 'SESSION' |
114 | instead of the current tracing session. | |
115 | ||
116 | ||
117 | Context | |
118 | ~~~~~~~ | |
119 | option:--list:: | |
120 | List the available context fields. Use this option alone. | |
121 | ||
59b19c3c | 122 | option:-t 'TYPE', option:--type='TYPE':: |
2e4886b8 PP |
123 | Add context field named 'TYPE'. This option can be repeated as |
124 | many times as needed on the command-line. | |
125 | ||
126 | ||
127 | include::common-cmd-help-options.txt[] | |
128 | ||
15623b7d JR |
129 | [[limitations]] |
130 | LIMITATIONS | |
131 | ----------- | |
132 | As of this version of LTTng, it is not possible to add context fields to | |
133 | a channel once its tracing session has been started (see man:lttng-start(1)) | |
134 | at least once. | |
2e4886b8 PP |
135 | |
136 | include::common-cmd-footer.txt[] | |
137 | ||
138 | ||
139 | SEE ALSO | |
140 | -------- | |
7c1a4458 | 141 | man:lttng(1) |