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

   1 lttng-add-context(1)
   2 ====================
   3
   4
   5 NAME
   6 ----
   7 lttng-add-context - Add context fields to an LTTng channel
   8
   9
  10 SYNOPSIS
  11 --------
  12 Add context fields to a channel:
  13
  14 [verse]
  15 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *add-context*
  16       (option:--kernel | option:--userspace | option:--jul | option:--log4j)
  17       [option:--session='SESSION'] [option:--channel='CHANNEL']
  18       option:--type='TYPE' [option:--type='TYPE']...
  19
  20 List the available context fields:
  21
  22 [verse]
  23 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *add-context* option:--list
  24
  25
  26 DESCRIPTION
  27 -----------
  28 The `lttng add-context` command adds one or more context fields to a
  29 channel.
  30
  31 Channels are created with the man:lttng-enable-channel(1) command.
  32
  33 When context fields are added to a channel, all the events emitted
  34 within this channel contain the dynamic values of those context fields.
  35
  36 If the option:--session option is omitted, the current tracing session
  37 is used. If the option:--channel option is omitted, the context fields
  38 are added to all the selected tracing session's channels.
  39
  40 Many context fields can be added to a channel at once by repeating the
  41 option:--type option.
  42
  43 perf counters are available as per-CPU (`perf:cpu:` prefix) as well as
  44 per-thread (`perf:thread:` prefix) counters. Currently, per-CPU counters
  45 can only be used in the Linux kernel tracing domain, while per-thread
  46 counters can only be used in the user space tracing domain.
  47
  48 It is also possible to enable PMU counters by raw ID using the
  49 `perf:cpu:raw:rN:NAME` (Linux kernel tracing domain) or
  50 `perf:thread:raw:rN:NAME` (user space tracing domain), with:
  51
  52 `N`::
  53     A hexadecimal event descriptor which is the same format as used
  54     by man:perf-record(1): a concatenation of the event number and umask
  55     value provided by the processor's manufacturer. The possible values
  56     for this field are processor-specific.
  57
  58 `NAME`::
  59     Custom name to easily recognize the counter.
  60
  61 Application-specific context fields can be added to a channel using the
  62 following syntax:
  63
  64 [verse]
  65 $app.'PROVIDER':__TYPE__
  66
  67 with:
  68
  69 'PROVIDER'::
  70     Provider name.
  71
  72 'TYPE'::
  73     Context type name.
  74
  75 NOTE: Make sure to **single-quote** the type when running the command
  76 from a shell, as `$` is a special character for variable substitution in
  77 most shells.
  78
  79 Use the option:--list option without other arguments to list the
  80 available context field names.
  81
  82 See the <<limitations,LIMITATIONS>> section below for a list of
  83 limitations to consider.
  84
  85 include::common-cmd-options-head.txt[]
  86
  87
  88 Domain
  89 ~~~~~~
  90 One of:
  91
  92 option:-j, option:--jul::
  93     Add context to channel in the `java.util.logging` (JUL) domain.
  94
  95 option:-k, option:--kernel::
  96     Add context to channel in the Linux kernel domain.
  97
  98 option:-l, option:--log4j::
  99     Add context to channel in the Apache log4j domain.
 100
 101 option:-u, option:--userspace::
 102     Add context to channel in the user space domain.
 103
 104
 105 Target
 106 ~~~~~~
 107 option:-c 'CHANNEL', option:--channel='CHANNEL'::
 108     Add context fields to a channel named 'CHANNEL' instead of adding
 109     them to all the channels.
 110
 111 option:-s 'SESSION', option:--session='SESSION'::
 112     Add context fields to a channel in the tracing session named 'SESSION'
 113     instead of the current tracing session.
 114
 115
 116 Context
 117 ~~~~~~~
 118 option:--list::
 119     List the available context fields. Use this option alone.
 120
 121 option:-t 'TYPE', option:--type='TYPE'::
 122     Add context field named 'TYPE'. This option can be repeated as
 123     many times as needed on the command-line.
 124
 125
 126 include::common-cmd-help-options.txt[]
 127
 128 [[limitations]]
 129 LIMITATIONS
 130 -----------
 131 As of this version of LTTng, it is not possible to add context fields to
 132 a channel once its tracing session has been started (see man:lttng-start(1))
 133 at least once.
 134
 135 include::common-cmd-footer.txt[]
 136
 137
 138 SEE ALSO
 139 --------
 140 man:lttng(1)