doc/man/lttng-add-context.1.txt

   1 lttng-add-context(1)
   2 ====================
   3 :revdate: 14 June 2021
   4
   5
   6 NAME
   7 ----
   8 lttng-add-context - Add context fields to be recorded by LTTng
   9
  10
  11 SYNOPSIS
  12 --------
  13 Add context fields to be recorded to the event records of one or more
  14 channels:
  15
  16 [verse]
  17 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *add-context*
  18       (option:--kernel | option:--userspace | option:--jul | option:--log4j)
  19       [option:--session='SESSION'] [option:--channel='CHANNEL']
  20       option:--type='TYPE' [option:--type='TYPE']...
  21
  22 List the available context field types:
  23
  24 [verse]
  25 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *add-context* option:--list
  26
  27
  28 DESCRIPTION
  29 -----------
  30 The `lttng add-context` command can:
  31
  32 Without the option:--list option::
  33     Add one or more context fields to be recorded by LTTng to the event
  34     records of:
  35 +
  36 With the option:--session='SESSION' option:::
  37     The recording session named 'SESSION'.
  38
  39 Without the option:--session option:::
  40     The current recording session (see man:lttng-concepts(7) to learn
  41     more about the current recording session).
  42
  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 recording session.
  48
  49 With the option:--list option::
  50     List the available context field types.
  51
  52 See man:lttng-concepts(7) to learn more about recording sessions and
  53 channels.
  54
  55 Repeat the option:--type='TYPE' option to add more than one context
  56 field to be recorded. 'TYPE' is one of:
  57
  58 * A statically-known, or built-in context field named.
  59
  60 * A perf counter name:
  61 +
  62 --
  63 Per-CPU::
  64     Prefix: `perf:cpu:`
  65 +
  66 Only available with the option:--kernel option.
  67
  68 Per-thread::
  69     Prefix: `perf:thread:`
  70 +
  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 --
  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 +
  86 The possible values for this part are processor-specific.
  87
  88 'NAME'::
  89     Custom name to identify the counter.
  90 --
  91
  92 * An LTTng application-specific context field name:
  93 +
  94 --
  95 [verse]
  96 $app.'PROVIDER':__TYPE__
  97 +
  98 'PROVIDER'::
  99     Provider name.
 100
 101 'TYPE'::
 102     Context type name.
 103 --
 104 +
 105 Only available with the option:--jul and option:--log4j options.
 106
 107 IMPORTANT: Make sure to **single-quote** 'TYPE' when you run the
 108 `add-context` command from a shell, as `$` is a special character for
 109 variable substitution in most shells.
 110
 111 NOTE: As of LTTng{nbsp}{lttng_version}, you may :not: add context fields
 112 to be recorded to the event records of a given channel once its
 113 recording session has been started (see man:lttng-start(1)) at least
 114 once.
 115
 116 See the ``<<examples,EXAMPLES>>'' section below for usage examples.
 117
 118
 119 include::common-lttng-cmd-options-head.txt[]
 120
 121
 122 Tracing domain
 123 ~~~~~~~~~~~~~~
 124 One of:
 125
 126 option:-j, option:--jul::
 127     Add context fields to be recorded to the event records of one or
 128     more channels of the `java.util.logging` (JUL) tracing domain.
 129
 130 option:-k, option:--kernel::
 131     Add context fields to be recorded to the event records of one or
 132     more channels of the Linux kernel tracing domain.
 133
 134 option:-l, option:--log4j::
 135     Add context fields to be recorded to the event records of one or
 136     more channels of the Apache log4j tracing domain.
 137
 138 option:-u, option:--userspace::
 139     Add context fields to be recorded to the event records of one or
 140     more channels of the user space tracing domain.
 141
 142
 143 Recording target
 144 ~~~~~~~~~~~~~~~~
 145 option:-c 'CHANNEL', option:--channel='CHANNEL'::
 146     Add context fields to be recorded to the event records of a channel
 147     named 'CHANNEL' instead of all the channels of the selected
 148     recording session.
 149
 150 option:-s 'SESSION', option:--session='SESSION'::
 151     Add context fields to be recorded to the event records of one or
 152     more channels of the recording session named 'SESSION' instead of
 153     the current recording session.
 154
 155
 156 Context field type
 157 ~~~~~~~~~~~~~~~~~~
 158 option:--list::
 159     List the available context field types.
 160 +
 161 You may :not: use this option with the option:--channel,
 162 option:--session, or option:--type options.
 163
 164 option:-t 'TYPE', option:--type='TYPE'::
 165     Add a context field having the type 'TYPE' to be recorded.
 166 +
 167 Repeat this option to add more than one context field.
 168
 169
 170 include::common-lttng-cmd-help-options.txt[]
 171
 172
 173 include::common-lttng-cmd-after-options.txt[]
 174
 175
 176 [[examples]]
 177 EXAMPLES
 178 --------
 179 .List the available context field types.
 180 ====
 181 See the option:--list option.
 182
 183 [role="term"]
 184 ----
 185 $ lttng add-context --list
 186 ----
 187 ====
 188
 189 .Add a single statically-known context field to be recorded to all the Linux kernel channels of the current recording session.
 190 ====
 191 [role="term"]
 192 ----
 193 $ lttng add-context --kernel --type=pid
 194 ----
 195 ====
 196
 197 .Add three statically-known context fields to be recorded to a specific user space channel of a specific recording session.
 198 ====
 199 See the option:--session and option:--channel options.
 200
 201 [role="term"]
 202 ----
 203 $ lttng add-context --userspace --session=my-session \
 204                     --channel=my-channel \
 205                     --type=vpid --type=procname --type=ip
 206 ----
 207 ====
 208
 209 .Add a perf counter context field to be recorded to a specific Linux kernel channel of the current recording session.
 210 ====
 211 See the option:--channel option.
 212
 213 [role="term"]
 214 ----
 215 $ lttng add-context --kernel --channel=my-channel \
 216                     --type=perf:cpu:cache-misses
 217 ----
 218 ====
 219
 220 .Add an LTTng application-specific context field to be recorded to all the JUL channels of the current recording session.
 221 ====
 222 [role="term"]
 223 ----
 224 $ lttng add-context --jul --type='$app.my_server:user_cnt'
 225 ----
 226 ====
 227
 228
 229 include::common-footer.txt[]
 230
 231
 232 SEE ALSO
 233 --------
 234 man:lttng(1),
 235 man:lttng-enable-channel(1),
 236 man:lttng-concepts(7)