1 = babeltrace2-source.ctf.lttng-live(7)
2 :manpagetype: component class
3 :revdate: 14 September 2019
8 babeltrace2-source.ctf.lttng-live - Babeltrace 2's LTTng live source
14 A Babeltrace~2 compcls:source.ctf.lttng-live message iterator
15 connects to a local or remote https://lttng.org/[LTTng] relay daemon,
16 receives the streams of a specific tracing session, and emits
17 corresponding messages.
23 | +--------------------+
24 | | src.ctf.lttng-live |
26 | out @--> Sorted messages of one
27 +--------------------+ or more streams
30 More information about LTTng live is available in the
31 https://lttng.org/docs/#doc-lttng-live[LTTng Documentation].
33 include::common-see-babeltrace2-intro.txt[]
35 A compcls:source.ctf.lttng-live component has a single output port: its
36 message iterator muxes (sorts) the messages from the various CTF data
39 A compcls:source.ctf.lttng-live message iterator handles the messages of
40 one, and only one LTTng tracing session. A single LTTng tracing session
41 can contain one or more traces, depending on the active tracing domains
42 and the configured user space buffering scheme.
44 The component connects to an LTTng relay daemon using the param:inputs
45 parameter. This is an array of exactly one string which is the URL of
46 the LTTng relay daemon to connect to.
48 By default, if the remote tracing session name does not exist, the
49 message iterator returns "try again later". This default mode makes the
50 message iterator never end: even if the remote tracing session is
51 destroyed, the message iterator keeps on waiting for a tracing session
52 with the same name to exist. You can change this behaviour with the
53 param:session-not-found-action initialization parameter.
55 NOTE: As of this version, you can only create one message iterator per
56 compcls:source.ctf.lttng-live component. This is because the LTTng live
57 protocol accepts at most one client per tracing session per LTTng relay
61 == INITIALIZATION PARAMETERS
63 param:inputs='URL' vtype:[array of one string]::
64 Use 'URL' to connect to the LTTng relay daemon.
66 'URL' is an array of exactly one string of which the format is:
70 net[4]://__RDHOST__[:__RDPORT__]/host/__TGTHOST__/__SESSION__
73 LTTng relay daemon's host name or IP address.
76 LTTng relay daemon's listening port.
78 If not specified, the component uses the default port ({defrdport}).
81 Target's host name or IP address.
84 Name of the LTTng tracing session from which to receive data.
87 param:session-not-found-action=(`continue` | `fail` | `end`) vtype:[optional string]::
88 When the message iterator does not find the specified remote tracing
89 session ('SESSION' part of the param:inputs parameter), do one of:
92 `continue` (default)::
93 Keep on trying, returning "try again later" to the downstream user
94 until the tracing session exists.
96 With this action, the message iterator never ends, as the LTTng live
97 protocol cannot currently indicate that a tracing session will never
111 +--------------------+
112 | src.ctf.lttng-live |
115 +--------------------+
127 === `babeltrace.support-info`
129 See man:babeltrace2-query-babeltrace.support-info(7) to learn more
130 about this query object.
132 For a string input which honors the LTTng live URL format (see the
133 param:inputs parameter), the result object is 0.75.
138 You can query the `sessions` object to get a list of available LTTng
139 tracing sessions for a given LTTng relay daemon URL.
143 nlparam:url='URL' vtype:[string]::
144 Use 'URL' to connect to the LTTng relay daemon.
146 The format of 'URL' is:
150 net[4]://__RDHOST__[:__RDPORT__]
153 LTTng relay daemon's host name or IP address.
156 LTTng relay daemon's listening port.
158 If not specified, the query operation uses the default port
162 Result object (array of maps, one element for each available tracing
165 qres:client-count vtype:[unsigned integer]::
166 Current number of LTTng live clients connected to the relay daemon
167 to receive data from this tracing session.
169 qres:session-name vtype:[string]::
170 Tracing session's name.
172 qres:stream-count vtype:[unsigned integer]::
173 Current number of CTF streams in this tracing sessions, including
174 the metadata streams.
176 qres:target-hostname vtype:[string]::
177 Hostname of the tracing session.
179 This is not necessarily the relay daemon's hostname.
181 qres:timer-us vtype:[unsigned integer]::
182 Tracing session's configured live timer's period (µs)
183 (see man:lttng-create(1)).
185 qres:url vtype:[string]::
186 URL to use as the first element of the param:inputs parameter to
187 connect to the same LTTng relay daemon and receive data from this
191 include::common-footer.txt[]
196 man:babeltrace2-intro(7),
197 man:babeltrace2-plugin-ctf(7),