'\" t
.\" Title: babeltrace2-source.ctf.lttng-live
.\" Author: [see the "AUTHORS" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot
.\" Date: 14 September 2019
.\" Manual: Babeltrace\ \&2 manual
.\" Source: Babeltrace 2.0.5
.\" Language: English
.\"
.TH "BABELTRACE2\-SOURCE\" "7" "14 September 2019" "Babeltrace 2\&.0\&.5" "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 ) 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 )\&.
.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 )\&.
.SH "RESOURCES"
.sp
The Babeltrace project shares some communication channels with the LTTng project (see )\&.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Babeltrace website (see )
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Mailing list (see )
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 ):
\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 )
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Git repository (see )
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
GitHub project (see )
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Continuous integration (see )
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Code review (see )
.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 \&.
.SH "COPYRIGHT"
.sp
This component class is part of the Babeltrace\ \&2 project\&.
.sp
Babeltrace is distributed under the MIT license (see )\&.
.SH "SEE ALSO"
.sp
\fBbabeltrace2-intro\fR(7), \fBbabeltrace2-plugin-ctf\fR(7), \fBlttng-relayd\fR(8), \fBlttng-create\fR(1)