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