'\" t
.\"     Title: babeltrace2-source.ctf.lttng-live
.\"    Author: [see the "AUTHORS" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 14 September 2019
.\"    Manual: Babeltrace\ \&2 manual
.\"    Source: Babeltrace 2.0.6
.\"  Language: English
.\"
.TH "BABELTRACE2\-SOURCE\" "7" "14 September 2019" "Babeltrace 2\&.0\&.6" "Babeltrace\ \&2 manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
babeltrace2-source.ctf.lttng-live \- Babeltrace 2\*(Aqs LTTng live source component class
.SH "DESCRIPTION"
.sp
A Babeltrace\ \&2 \fBsource.ctf.lttng-live\fR 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\&.
.sp
.if n \{\
.RS 4
.\}
.nf
CTF streams over
LTTng live (TCP)
  |
  |   +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
  |   | src\&.ctf\&.lttng\-live |
  \*(Aq\-\->|                    |
      |                out @\-\-> Sorted messages of one
      +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+    or more streams
.fi
.if n \{\
.RE
.\}
.sp
More information about LTTng live is available in the LTTng Documentation (see <https://lttng.org/docs/#doc-lttng-live>)\&.
.sp
See \fBbabeltrace2-intro\fR(7) to learn more about the Babeltrace\ \&2 project and its core concepts\&.
.sp
A \fBsource.ctf.lttng-live\fR component has a single output port: its message iterator muxes (sorts) the messages from the various CTF data streams internally\&.
.sp
A \fBsource.ctf.lttng-live\fR 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\&.
.sp
The component connects to an LTTng relay daemon using the \fBinputs\fR parameter\&. This is an array of exactly one string which is the URL of the LTTng relay daemon to connect to\&.
.sp
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 \fBsession-not-found-action\fR initialization parameter\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.sp
As of this version, you can only create one message iterator per \fBsource.ctf.lttng-live\fR component\&. This is because the LTTng live protocol accepts at most one client per tracing session per LTTng relay daemon\&.
.sp .5v
.RE
.SH "INITIALIZATION PARAMETERS"
.PP
\fBinputs\fR=\fIURL\fR [array of one string]
.RS 4
Use
\fIURL\fR
to connect to the LTTng relay daemon\&.
.sp
\fIURL\fR
is an array of exactly one string of which the format is:
.sp
.if n \{\
.RS 4
.\}
.nf
net[4]://\fIRDHOST\fR[:\fIRDPORT\fR]/host/\fITGTHOST\fR/\fISESSION\fR
.fi
.if n \{\
.RE
.\}
.PP
\fIRDHOST\fR
.RS 4
LTTng relay daemon\(cqs host name or IP address\&.
.RE
.PP
\fIRDPORT\fR
.RS 4
LTTng relay daemon\(cqs listening port\&.
.sp
If not specified, the component uses the default port (5344)\&.
.RE
.PP
\fITGTHOST\fR
.RS 4
Target\(cqs host name or IP address\&.
.RE
.PP
\fISESSION\fR
.RS 4
Name of the LTTng tracing session from which to receive data\&.
.RE
.RE
.PP
\fBsession-not-found-action\fR=(\fBcontinue\fR | \fBfail\fR | \fBend\fR) [optional string]
.RS 4
When the message iterator does not find the specified remote tracing session (\fISESSION\fR
part of the
\fBinputs\fR
parameter), do one of:
.PP
\fBcontinue\fR (default)
.RS 4
Keep on trying, returning "try again later" to the downstream user until the tracing session exists\&.
.sp
With this action, the message iterator never ends, as the LTTng live protocol cannot currently indicate that a tracing session will never exist\&.
.RE
.PP
\fBfail\fR
.RS 4
Fail\&.
.RE
.PP
\fBend\fR
.RS 4
End\&.
.RE
.RE
.SH "PORTS"
.sp
.if n \{\
.RS 4
.\}
.nf
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
| src\&.ctf\&.lttng\-live |
|                    |
|                out @
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
.fi
.if n \{\
.RE
.\}
.SS "Output"
.PP
\fBout\fR
.RS 4
Single output port\&.
.RE
.SH "QUERY OBJECTS"
.SS "babeltrace\&.support\-info"
.sp
See \fBbabeltrace2-query-babeltrace.support-info\fR(7) to learn more about this query object\&.
.sp
For a string input which honors the LTTng live URL format (see the \fBinputs\fR parameter), the result object is 0\&.75\&.
.SS "sessions"
.sp
You can query the \fBsessions\fR object to get a list of available LTTng tracing sessions for a given LTTng relay daemon URL\&.
.sp
Parameters:
.PP
\fBurl\fR=\fIURL\fR [string]
.RS 4
Use
\fIURL\fR
to connect to the LTTng relay daemon\&.
.sp
The format of
\fIURL\fR
is:
.sp
.if n \{\
.RS 4
.\}
.nf
net[4]://\fIRDHOST\fR[:\fIRDPORT\fR]
.fi
.if n \{\
.RE
.\}
.PP
\fIRDHOST\fR
.RS 4
LTTng relay daemon\(cqs host name or IP address\&.
.RE
.PP
\fIRDPORT\fR
.RS 4
LTTng relay daemon\(cqs listening port\&.
.sp
If not specified, the query operation uses the default port (5344)\&.
.RE
.RE
.sp
Result object (array of maps, one element for each available tracing session):
.PP
\fBclient-count\fR [unsigned integer]
.RS 4
Current number of LTTng live clients connected to the relay daemon to receive data from this tracing session\&.
.RE
.PP
\fBsession-name\fR [string]
.RS 4
Tracing session\(cqs name\&.
.RE
.PP
\fBstream-count\fR [unsigned integer]
.RS 4
Current number of CTF streams in this tracing sessions, including the metadata streams\&.
.RE
.PP
\fBtarget-hostname\fR [string]
.RS 4
Hostname of the tracing session\&.
.sp
This is not necessarily the relay daemon\(cqs hostname\&.
.RE
.PP
\fBtimer-us\fR [unsigned integer]
.RS 4
Tracing session\(cqs configured live timer\(cqs period (\(mcs) (see
\fBlttng-create\fR(1))\&.
.RE
.PP
\fBurl\fR [string]
.RS 4
URL to use as the first element of the
\fBinputs\fR
parameter to connect to the same LTTng relay daemon and receive data from this tracing session\&.
.RE
.SH "BUGS"
.sp
If you encounter any issue or usability problem, please report it on the Babeltrace bug tracker (see <https://bugs.lttng.org/projects/babeltrace>)\&.
.SH "RESOURCES"
.sp
The Babeltrace project shares some communication channels with the LTTng project (see <https://lttng.org/>)\&.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Babeltrace website (see <https://babeltrace.org/>)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Mailing list (see <https://lists.lttng.org>)
for support and development:
\fBlttng-dev@lists.lttng.org\fR
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
IRC channel (see <irc://irc.oftc.net/lttng>):
\fB#lttng\fR
on
\fBirc.oftc.net\fR
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Bug tracker (see <https://bugs.lttng.org/projects/babeltrace>)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Git repository (see <https://git.efficios.com/?p=babeltrace.git>)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
GitHub project (see <https://github.com/efficios/babeltrace>)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Continuous integration (see <https://ci.lttng.org/view/Babeltrace/>)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Code review (see <https://review.lttng.org/q/project:babeltrace>)
.RE
.SH "AUTHORS"
.sp
The Babeltrace\ \&2 project is the result of hard work by many regular developers and occasional contributors\&.
.sp
The current project maintainer is J\('er\('emie Galarneau <mailto:jeremie.galarneau@efficios.com>\&.
.SH "COPYRIGHT"
.sp
This component class is part of the Babeltrace\ \&2 project\&.
.sp
Babeltrace is distributed under the MIT license (see <https://opensource.org/licenses/MIT>)\&.
.SH "SEE ALSO"
.sp
\fBbabeltrace2-intro\fR(7), \fBbabeltrace2-plugin-ctf\fR(7), \fBlttng-relayd\fR(8), \fBlttng-create\fR(1)