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

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