Ubuntu Manpage: babeltrace2-source.ctf.lttng-live - Babeltrace 2's LTTng live source component class

NAME

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

DESCRIPTION

A Babeltrace 2 source.ctf.lttng-live message iterator connects to a local or remote LTTng
(see <https://lttng.org/>) relay daemon, receives the streams of a specific tracing
session, and emits corresponding messages.

More information about LTTng live is available in the LTTng Documentation (see
<https://lttng.org/docs/#doc-lttng-live>).

See babeltrace2-intro(7) to learn more about the Babeltrace 2 project and its core
concepts.

A source.ctf.lttng-live component has a single output port: its message iterator muxes
(sorts) the messages from the various CTF data streams internally.

A source.ctf.lttng-live message iterator handles the messages of one, and only one LTTng
tracing session. A single LTTng tracing session can contain one or more traces, depending
on the active tracing domains and the configured user space buffering scheme.

The component connects to an LTTng relay daemon using the inputs parameter. This is an
array of exactly one string which is the URL of the LTTng relay daemon to connect to.

By default, if the remote tracing session name does not exist, the message iterator
returns "try again later". This default mode makes the message iterator never end: even if
the remote tracing session is destroyed, the message iterator keeps on waiting for a
tracing session with the same name to exist. You can change this behaviour with the
session-not-found-action initialization parameter.

Note
As of this version, you can only create one message iterator per source.ctf.lttng-live
component. This is because the LTTng live protocol accepts at most one client per
tracing session per LTTng relay daemon.

INITIALIZATION PARAMETERS

       inputs=URL [array of one string]
           Use URL to connect to the LTTng relay daemon.

           URL is an array of exactly one string of which the format is:

               net[4]://RDHOST[:RDPORT]/host/TGTHOST/SESSION

           RDHOST
               LTTng relay daemon’s host name or IP address.

           RDPORT
               LTTng relay daemon’s listening port.

               If not specified, the component uses the default port (5344).

           TGTHOST
               Target’s host name or IP address.

           SESSION
               Name of the LTTng tracing session from which to receive data.

       session-not-found-action=(continue | fail | end) [optional string]
           When the message iterator does not find the specified remote tracing session (SESSION
           part of the inputs parameter), do one of:

           continue (default)
               Keep on trying, returning "try again later" to the downstream user until the
               tracing session exists.

               With this action, the message iterator never ends, as the LTTng live protocol
               cannot currently indicate that a tracing session will never exist.

           fail
               Fail.

           end
               End.

PORTS

           +--------------------+
           | src.ctf.lttng-live |
           |                    |
           |                out @
           +--------------------+

   Output
       out
           Single output port.

QUERY OBJECTS

   babeltrace.support-info
       See babeltrace2-query-babeltrace.support-info(7) to learn more about this query object.

       For a string input which honors the LTTng live URL format (see the inputs parameter), the
       result object is 0.75.

   sessions
       You can query the sessions object to get a list of available LTTng tracing sessions for a
       given LTTng relay daemon URL.

       Parameters:

       url=URL [string]
           Use URL to connect to the LTTng relay daemon.

           The format of URL is:

               net[4]://RDHOST[:RDPORT]

           RDHOST
               LTTng relay daemon’s host name or IP address.

           RDPORT
               LTTng relay daemon’s listening port.

               If not specified, the query operation uses the default port (5344).

       Result object (array of maps, one element for each available tracing session):

       client-count [unsigned integer]
           Current number of LTTng live clients connected to the relay daemon to receive data
           from this tracing session.

       session-name [string]
           Tracing session’s name.

       stream-count [unsigned integer]
           Current number of CTF streams in this tracing sessions, including the metadata
           streams.

       target-hostname [string]
           Hostname of the tracing session.

           This is not necessarily the relay daemon’s hostname.

       timer-us [unsigned integer]
           Tracing session’s configured live timer’s period (µs) (see lttng-create(1)).

       url [string]
           URL to use as the first element of the inputs parameter to connect to the same LTTng
           relay daemon and receive data from this tracing session.

BUGS

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

RESOURCES

       The Babeltrace project shares some communication channels with the LTTng project (see
       <https://lttng.org/>).

       •   Babeltrace website (see <https://babeltrace.org/>)

       •   Mailing list (see <https://lists.lttng.org>) for support and development: lttng-
           dev@lists.lttng.org

       •   IRC channel (see <irc://irc.oftc.net/lttng>): #lttng on irc.oftc.net

       •   Bug tracker (see <https://bugs.lttng.org/projects/babeltrace>)

       •   Git repository (see <https://git.efficios.com/?p=babeltrace.git>)

       •   GitHub project (see <https://github.com/efficios/babeltrace>)

       •   Continuous integration (see <https://ci.lttng.org/view/Babeltrace/>)

       •   Code review (see <https://review.lttng.org/q/project:babeltrace>)

AUTHORS

       The Babeltrace 2 project is the result of hard work by many regular developers and
       occasional contributors.

       The current project maintainer is Jérémie Galarneau
       <mailto:jeremie.galarneau@efficios.com>.

COPYRIGHT

       This component class is part of the Babeltrace 2 project.

       Babeltrace is distributed under the MIT license (see
       <https://opensource.org/licenses/MIT>).