a026452db22b5ecabb3a2721f4c73e14aa59491f
[lttng-tools.git] / 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)
This page took 0.043502 seconds and 3 git commands to generate.