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 a given channel, or of all the channels 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:--list option::
  44     List the available context field types.
  45
  46 See man:lttng-concepts(7) to learn more about tracing sessions and
  47 channels.
  48
  49 Without the option:--channel option, LTTng adds context fields to be
  50 recorded to the event records of *all* the channels of the selected
  51 tracing session.
  52
  53 Repeat the option:--type='TYPE' option to add more than one context
  54 field to be recorded. 'TYPE' is one of:
  55
  56 * A statically-known, or built-in context field named.
  57
  58 * A perf counter name:
  59 +
  60 --
  61 Per-CPU::
  62     Prefix: `perf:cpu:`
  63 +
  64 Only available with the option:--kernel option.
  65
  66 Per-thread::
  67     Prefix: `perf:thread:`
  68 +
  69 Only available with the option:--userspace, option:--jul, or
  70 option:--log4j option.
  71 --
  72 +
  73 Add Performance Monitoring Unit (PMU) counter context fields by raw ID
  74 with the ++perf:cpu:raw:r++__N__++:++__NAME__ (option:--kernel option)
  75 or ++perf:thread:raw:r++__N__++:++__NAME__ (option:--userspace,
  76 option:--jul, or option:--log4j option) types, with:
  77 +
  78 --
  79 'N'::
  80     A hexadecimal event descriptor which follows the man:perf-record(1)
  81     format: a concatenation of the event number and umask value which
  82     the manufacturer of the processor provides.
  83 +
  84 The possible values for this part are processor-specific.
  85
  86 'NAME'::
  87     Custom name to identify the counter.
  88 --
  89
  90 * An LTTng application-specific context field name:
  91 +
  92 [verse]
  93 $app.'PROVIDER':__TYPE__
  94 +
  95 'PROVIDER'::
  96     Provider name.
  97
  98 'TYPE'::
  99     Context type name.
 100
 101 IMPORTANT: Make sure to **single-quote** 'TYPE' when you run the
 102 `add-context` command from a shell, as `$` is a special character for
 103 variable substitution in most shells.
 104
 105 NOTE: As of LTTng{nbsp}{lttng_version}, you may :not: add context fields
 106 to be recorded to the event records of a given channel once its tracing
 107 session has been started (see man:lttng-start(1)) at least once.
 108
 109
 110 include::common-cmd-options-head.txt[]
 111
 112
 113 Tracing domain
 114 ~~~~~~~~~~~~~~
 115 One of:
 116
 117 option:-j, option:--jul::
 118     Add context fields to be recorded to the event records of one or
 119     more channels of the `java.util.logging` (JUL) tracing domain.
 120
 121 option:-k, option:--kernel::
 122     Add context fields to be recorded to the event records of one or
 123     more channels of the Linux kernel tracing domain.
 124
 125 option:-l, option:--log4j::
 126     Add context fields to be recorded to the event records of one or
 127     more channels of the Apache log4j tracing domain.
 128
 129 option:-u, option:--userspace::
 130     Add context fields to be recorded to the event records of one or
 131     more channels of the user space tracing domain.
 132
 133
 134 Recording target
 135 ~~~~~~~~~~~~~~~~
 136 option:-c 'CHANNEL', option:--channel='CHANNEL'::
 137     Add context fields to be recorded to the event records of a channel
 138     named 'CHANNEL' instead of all the channels of the selected
 139     tracing session.
 140
 141 option:-s 'SESSION', option:--session='SESSION'::
 142     Add context fields to be recorded to the event records of one or
 143     more channels of the tracing session named 'SESSION' instead of the
 144     current tracing session.
 145
 146
 147 Context field type
 148 ~~~~~~~~~~~~~~~~~~
 149 option:--list::
 150     List the available context field types.
 151 +
 152 You may :not: use this option with the option:--channel,
 153 option:--session, or option:--type options.
 154
 155 option:-t 'TYPE', option:--type='TYPE'::
 156     Add a context field having the type 'TYPE' to be recorded.
 157 +
 158 Repeat this option to add more than one context field.
 159
 160
 161 include::common-cmd-help-options.txt[]
 162
 163
 164 include::common-cmd-footer.txt[]
 165
 166
 167 SEE ALSO
 168 --------
 169 man:lttng(1),
 170 man:lttng-enable-channel(1),
 171 man:lttng-concepts(7)