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