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

   1 lttng-add-context(1)
   2 ====================
   3 :revdate: 3 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 [verse]
  95 $app.'PROVIDER':__TYPE__
  96 +
  97 'PROVIDER'::
  98     Provider name.
  99
 100 'TYPE'::
 101     Context type name.
 102
 103 IMPORTANT: Make sure to **single-quote** 'TYPE' when you run the
 104 `add-context` command from a shell, as `$` is a special character for
 105 variable substitution in most shells.
 106
 107 NOTE: As of LTTng{nbsp}{lttng_version}, you may :not: add context fields
 108 to be recorded to the event records of a given channel once its tracing
 109 session has been started (see man:lttng-start(1)) at least once.
 110
 111
 112 include::common-lttng-cmd-options-head.txt[]
 113
 114
 115 Tracing domain
 116 ~~~~~~~~~~~~~~
 117 One of:
 118
 119 option:-j, option:--jul::
 120     Add context fields to be recorded to the event records of one or
 121     more channels of the `java.util.logging` (JUL) tracing domain.
 122
 123 option:-k, option:--kernel::
 124     Add context fields to be recorded to the event records of one or
 125     more channels of the Linux kernel tracing domain.
 126
 127 option:-l, option:--log4j::
 128     Add context fields to be recorded to the event records of one or
 129     more channels of the Apache log4j tracing domain.
 130
 131 option:-u, option:--userspace::
 132     Add context fields to be recorded to the event records of one or
 133     more channels of the user space tracing domain.
 134
 135
 136 Recording target
 137 ~~~~~~~~~~~~~~~~
 138 option:-c 'CHANNEL', option:--channel='CHANNEL'::
 139     Add context fields to be recorded to the event records of a channel
 140     named 'CHANNEL' instead of all the channels of the selected
 141     tracing session.
 142
 143 option:-s 'SESSION', option:--session='SESSION'::
 144     Add context fields to be recorded to the event records of one or
 145     more channels of the tracing session named 'SESSION' instead of the
 146     current tracing session.
 147
 148
 149 Context field type
 150 ~~~~~~~~~~~~~~~~~~
 151 option:--list::
 152     List the available context field types.
 153 +
 154 You may :not: use this option with the option:--channel,
 155 option:--session, or option:--type options.
 156
 157 option:-t 'TYPE', option:--type='TYPE'::
 158     Add a context field having the type 'TYPE' to be recorded.
 159 +
 160 Repeat this option to add more than one context field.
 161
 162
 163 include::common-lttng-cmd-help-options.txt[]
 164
 165
 166 include::common-lttng-cmd-after-options.txt[]
 167
 168
 169 include::common-footer.txt[]
 170
 171
 172 SEE ALSO
 173 --------
 174 man:lttng(1),
 175 man:lttng-enable-channel(1),
 176 man:lttng-concepts(7)