Fix: MI: bump MI schema version to 4.0 in mi-lttng.c
[lttng-tools.git] / 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)
This page took 0.033405 seconds and 4 git commands to generate.