1BABELTRACE2-SOURCE()                                      BABELTRACE2-SOURCE()
2
3
4

NAME

6       babeltrace2-source.ctf.lttng-live - Babeltrace 2's LTTng live source
7       component class
8

DESCRIPTION

10       A Babeltrace 2 source.ctf.lttng-live message iterator connects to a
11       local or remote LTTng (see <https://lttng.org/>) relay daemon, receives
12       the streams of a specific tracing session, and emits corresponding
13       messages.
14
15           CTF streams over
16           LTTng live (TCP)
17             |
18             |   +--------------------+
19             |   | src.ctf.lttng-live |
20             '-->|                    |
21                 |                out @--> Sorted messages of one
22                 +--------------------+    or more streams
23
24       More information about LTTng live is available in the LTTng
25       Documentation (see <https://lttng.org/docs/#doc-lttng-live>).
26
27       See babeltrace2-intro(7) to learn more about the Babeltrace 2 project
28       and its core concepts.
29
30       A source.ctf.lttng-live component has a single output port: its message
31       iterator muxes (sorts) the messages from the various CTF data streams
32       internally.
33
34       A source.ctf.lttng-live message iterator handles the messages of one,
35       and only one LTTng tracing session. A single LTTng tracing session can
36       contain one or more traces, depending on the active tracing domains and
37       the configured user space buffering scheme.
38
39       The component connects to an LTTng relay daemon using the inputs
40       parameter. This is an array of exactly one string which is the URL of
41       the LTTng relay daemon to connect to.
42
43       By default, if the remote tracing session name does not exist, the
44       message iterator returns "try again later". This default mode makes the
45       message iterator never end: even if the remote tracing session is
46       destroyed, the message iterator keeps on waiting for a tracing session
47       with the same name to exist. You can change this behaviour with the
48       session-not-found-action initialization parameter.
49
50           Note
51           As of this version, you can only create one message iterator per
52           source.ctf.lttng-live component. This is because the LTTng live
53           protocol accepts at most one client per tracing session per LTTng
54           relay daemon.
55

INITIALIZATION PARAMETERS

57       inputs=URL [array of one string]
58           Use URL to connect to the LTTng relay daemon.
59
60           URL is an array of exactly one string of which the format is:
61
62               net[4]://RDHOST[:RDPORT]/host/TGTHOST/SESSION
63
64           RDHOST
65               LTTng relay daemon’s host name or IP address.
66
67           RDPORT
68               LTTng relay daemon’s listening port.
69
70               If not specified, the component uses the default port (5344).
71
72           TGTHOST
73               Target’s host name or IP address.
74
75           SESSION
76               Name of the LTTng tracing session from which to receive data.
77
78       session-not-found-action=(continue | fail | end) [optional string]
79           When the message iterator does not find the specified remote
80           tracing session (SESSION part of the inputs parameter), do one of:
81
82           continue (default)
83               Keep on trying, returning "try again later" to the downstream
84               user until the tracing session exists.
85
86               With this action, the message iterator never ends, as the LTTng
87               live protocol cannot currently indicate that a tracing session
88               will never exist.
89
90           fail
91               Fail.
92
93           end
94               End.
95

PORTS

97           +--------------------+
98           | src.ctf.lttng-live |
99           |                    |
100           |                out @
101           +--------------------+
102
103   Output
104       out
105           Single output port.
106

QUERY OBJECTS

108   babeltrace.support-info
109       See babeltrace2-query-babeltrace.support-info(7) to learn more about
110       this query object.
111
112       For a string input which honors the LTTng live URL format (see the
113       inputs parameter), the result object is 0.75.
114
115   sessions
116       You can query the sessions object to get a list of available LTTng
117       tracing sessions for a given LTTng relay daemon URL.
118
119       Parameters:
120
121       url=URL [string]
122           Use URL to connect to the LTTng relay daemon.
123
124           The format of URL is:
125
126               net[4]://RDHOST[:RDPORT]
127
128           RDHOST
129               LTTng relay daemon’s host name or IP address.
130
131           RDPORT
132               LTTng relay daemon’s listening port.
133
134               If not specified, the query operation uses the default port
135               (5344).
136
137       Result object (array of maps, one element for each available tracing
138       session):
139
140       client-count [unsigned integer]
141           Current number of LTTng live clients connected to the relay daemon
142           to receive data from this tracing session.
143
144       session-name [string]
145           Tracing session’s name.
146
147       stream-count [unsigned integer]
148           Current number of CTF streams in this tracing sessions, including
149           the metadata streams.
150
151       target-hostname [string]
152           Hostname of the tracing session.
153
154           This is not necessarily the relay daemon’s hostname.
155
156       timer-us [unsigned integer]
157           Tracing session’s configured live timer’s period (µs) (see lttng-
158           create(1)).
159
160       url [string]
161           URL to use as the first element of the inputs parameter to connect
162           to the same LTTng relay daemon and receive data from this tracing
163           session.
164

BUGS

166       If you encounter any issue or usability problem, please report it on
167       the Babeltrace bug tracker (see
168       <https://bugs.lttng.org/projects/babeltrace>).
169

RESOURCES

171       The Babeltrace project shares some communication channels with the
172       LTTng project (see <https://lttng.org/>).
173
174       •   Babeltrace website (see <https://babeltrace.org/>)
175
176       •   Mailing list (see <https://lists.lttng.org>) for support and
177           development: lttng-dev@lists.lttng.org
178
179       •   IRC channel (see <irc://irc.oftc.net/lttng>): #lttng on
180           irc.oftc.net
181
182       •   Bug tracker (see <https://bugs.lttng.org/projects/babeltrace>)
183
184       •   Git repository (see <https://git.efficios.com/?p=babeltrace.git>)
185
186       •   GitHub project (see <https://github.com/efficios/babeltrace>)
187
188       •   Continuous integration (see
189           <https://ci.lttng.org/view/Babeltrace/>)
190
191       •   Code review (see <https://review.lttng.org/q/project:babeltrace>)
192

AUTHORS

194       The Babeltrace 2 project is the result of hard work by many regular
195       developers and occasional contributors.
196
197       The current project maintainer is Jérémie Galarneau
198       <mailto:jeremie.galarneau@efficios.com>.
199
201       This component class is part of the Babeltrace 2 project.
202
203       Babeltrace is distributed under the MIT license (see
204       <https://opensource.org/licenses/MIT>).
205

SEE ALSO

207       babeltrace2-intro(7), babeltrace2-plugin-ctf(7), lttng-relayd(8),
208       lttng-create(1)
209
210
211
212                                                          BABELTRACE2-SOURCE()
Impressum