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