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

   1 lttng-add-context(1)
   2 ====================
   3 :revdate: 6 May 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 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).
  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 tracing 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 tracing 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 tracing
 113 session has been started (see man:lttng-start(1)) at least once.
 114
 115 See the <<examples,EXAMPLES>> section below for usage examples.
 116
 117
 118 include::common-lttng-cmd-options-head.txt[]
 119
 120
 121 Tracing domain
 122 ~~~~~~~~~~~~~~
 123 One of:
 124
 125 option:-j, option:--jul::
 126     Add context fields to be recorded to the event records of one or
 127     more channels of the `java.util.logging` (JUL) tracing domain.
 128
 129 option:-k, option:--kernel::
 130     Add context fields to be recorded to the event records of one or
 131     more channels of the Linux kernel tracing domain.
 132
 133 option:-l, option:--log4j::
 134     Add context fields to be recorded to the event records of one or
 135     more channels of the Apache log4j tracing domain.
 136
 137 option:-u, option:--userspace::
 138     Add context fields to be recorded to the event records of one or
 139     more channels of the user space tracing domain.
 140
 141
 142 Recording target
 143 ~~~~~~~~~~~~~~~~
 144 option:-c 'CHANNEL', option:--channel='CHANNEL'::
 145     Add context fields to be recorded to the event records of a channel
 146     named 'CHANNEL' instead of all the channels of the selected
 147     tracing session.
 148
 149 option:-s 'SESSION', option:--session='SESSION'::
 150     Add context fields to be recorded to the event records of one or
 151     more channels of the tracing session named 'SESSION' instead of the
 152     current tracing session.
 153
 154
 155 Context field type
 156 ~~~~~~~~~~~~~~~~~~
 157 option:--list::
 158     List the available context field types.
 159 +
 160 You may :not: use this option with the option:--channel,
 161 option:--session, or option:--type options.
 162
 163 option:-t 'TYPE', option:--type='TYPE'::
 164     Add a context field having the type 'TYPE' to be recorded.
 165 +
 166 Repeat this option to add more than one context field.
 167
 168
 169 include::common-lttng-cmd-help-options.txt[]
 170
 171
 172 include::common-lttng-cmd-after-options.txt[]
 173
 174
 175 [[examples]]
 176 EXAMPLES
 177 --------
 178 .List the available context field types.
 179 ====
 180 See the option:--list option.
 181
 182 [role="term"]
 183 ----
 184 $ lttng add-context --list
 185 ----
 186 ====
 187
 188 .Add a single statically-known context field to be recorded to all the Linux kernel channels of the current tracing session.
 189 ====
 190 [role="term"]
 191 ----
 192 $ lttng add-context --kernel --type=pid
 193 ----
 194 ====
 195
 196 .Add three statically-known context fields to be recorded to a specific user space channel of a specific tracing session.
 197 ====
 198 See the option:--session and option:--channel options.
 199
 200 [role="term"]
 201 ----
 202 $ lttng add-context --userspace --session=my-session \
 203                     --channel=my-channel \
 204                     --type=vpid --type=procname --type=ip
 205 ----
 206 ====
 207
 208 .Add a perf counter context field to be recorded to a specific Linux kernel channel of the current tracing session.
 209 ====
 210 See the option:--channel option.
 211
 212 [role="term"]
 213 ----
 214 $ lttng add-context --kernel --channel=my-channel \
 215                     --type=perf:cpu:cache-misses
 216 ----
 217 ====
 218
 219 .Add an LTTng application-specific context field to be recorded to all the JUL channels of the current tracing session.
 220 ====
 221 [role="term"]
 222 ----
 223 $ lttng add-context --jul --type='$app.my_server:user_cnt'
 224 ----
 225 ====
 226
 227
 228 include::common-footer.txt[]
 229
 230
 231 SEE ALSO
 232 --------
 233 man:lttng(1),
 234 man:lttng-enable-channel(1),
 235 man:lttng-concepts(7)