| 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] |
| 15 | *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *add-context* |
| 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] |
| 23 | *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *add-context* option:--list |
| 24 | |
| 25 | |
| 26 | DESCRIPTION |
| 27 | ----------- |
| 28 | The `lttng add-context` command adds one or more context fields to a |
| 29 | channel. |
| 30 | |
| 31 | Channels are created with the man:lttng-enable-channel(1) command. |
| 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 | |
| 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 | |
| 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 | |
| 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 | |
| 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 | ~~~~~~ |
| 101 | option:-c, option:--channel='CHANNEL':: |
| 102 | Add context fields to a channel named 'CHANNEL' instead of adding |
| 103 | them to all the channels. |
| 104 | |
| 105 | option:-s, option:--session='SESSION':: |
| 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 | |
| 115 | option:-t, option:--type='TYPE':: |
| 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 | -------- |
| 128 | man:lttng(1) |