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

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