BABELTRACE2-SOURCE.CTF.LTTNG-LIVE(7)

📦
version 2.1.2 · 6 versions
, in fedora 43, fedora 44, nixos 26.05, nixpkgs unstable, ubuntu resolute, ubuntu stonking

✨ babeltrace2-source.ctf.lttng-live ✨

okay bestie, welcome to the BABELTRACE2-SOURCE manual section 💖 this is where we talk about the Babeltrace 2 source.ctf.lttng-live component class, and honestly? it's giving main character energy for anyone who wants live trace data without waiting around. let's get into it 🫶

🌸 NAME 🌸

babeltrace2-source.ctf.lttng-live — the Babeltrace 2 LTTng live source component class 💅

🦋 DESCRIPTION 🦋

A Babeltrace 2 source.ctf.lttng-live message iterator rolls up to a local or remote LTTng relay daemon (peep <https://lttng.org/> if you've never met it), receives the streams of one specific tracing session, and emits the corresponding messages. that's the whole vibe ✨

CTF streams over
LTTng live (TCP)
  |
  |   +--------------------+
  |   | src.ctf.lttng-live |
  '-->|                    |
      |                out @--> Sorted messages of one
      +--------------------+    or more streams

want the full lore on LTTng live? it lives in the LTTng Documentation at <https://lttng.org/docs/#doc-lttng-live> 📚

and if you wanna actually understand the Babeltrace 2 project and its core concepts, go read babeltrace2-intro(7) — it's the prerequisite, no cap.

A source.ctf.lttng-live component has exactly one output port: its message iterator muxes (aka sorts) the messages from all the various CTF data streams internally. so you get the tidy version, not the chaos version 🙈

A source.ctf.lttng-live message iterator handles the messages of one, and only one LTTng tracing session. and a single LTTng tracing session can contain one or more traces, depending on the active tracing domains and the configured user space buffering scheme. so like, one session, but potentially many traces inside it 🎀

The component connects to an LTTng relay daemon using the inputs parameter. that parameter is an array of exactly one string, and that string is the URL of the LTTng relay daemon you're connecting to. periodt.

By default, if the remote tracing session name doesn't exist, the message iterator returns "try again later". and this default mode means the message iterator never ends — even if the remote tracing session gets destroyed, it just keeps on waiting for a tracing session with the same name to exist 😭 like it will literally wait forever. if you want different behaviour, change it 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. it's not us being gatekeepy, it's the protocol.

As of this version, a source.ctf.lttng-live component can connect to an LTTng relay daemon using the LTTng 2.4 or LTTng 2.15 protocol. the 2.15 one is required for CTF 2 support (see <https://diamon.org/ctf/>) ✨

The "get supported MIP versions" method of source.ctf.lttng-live always reports that it supports MIP versions 0 and 1. but heads up: if you attempt to make a source.ctf.lttng-live component read a CTF 2 recording session within a trace processing graph configured with MIP 0, then the message iterator will fail at initialization or "next" method call time. consider yourself warned bestie 🫠

🎀 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, and its format is:

net[4]://RDHOST[:RDPORT]/host/TGTHOST/SESSION
  • RDHOST — Host name or IP address of the LTTng relay daemon.
  • RDPORT — Listening port of the LTTng relay daemon. If not specified, then the component uses the default port (5344).
  • TGTHOST — Target 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 doesn't find the specified remote tracing session (that's the SESSION part of the inputs parameter), do one of these:
    • 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. it's giving eternal optimism 🕯️
    • fail — Fail. that's it. that's the action 💀
    • end — End. also that's it 🌸

🌈 PORTS 🌈

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

Output

  • out — Single output port. just the one. the one and only 👑

🧚 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. yes, very specific, we love a precise number ✨

sessions

You can query the sessions object to get a list of available LTTng tracing sessions for a given LTTng relay daemon URL. it's literally the guest list 🎟️

Parameters:

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

The format of URL is:

net[4]://RDHOST[:RDPORT]
  • RDHOST — Host name or IP address of the LTTng relay daemon.
  • RDPORT — Listening port of the LTTng relay daemon. If not specified, then 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 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 isn't necessarily the hostname of the relay daemon. so like, don't assume, okay? 🙈
  • timer-us [unsigned integer] — Configured period (µs) of the live timer of the tracing session (see lttng-create(1)).
  • trace-format [string] — Format of the trace(s) of the tracing session amongst:
  • 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. it's the plug-and-play link, iconic 💅

💀 BUGS 💀

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

🌸 RESOURCES 🌸

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

come hang out, the community is lowkey adorable 🌈

👑 AUTHORS 👑

The Babeltrace 2 project is the result of hard work by many regular developers and occasional contributors. shoutout to every single one of them, genuinely 🫶

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

This component class is part of the Babeltrace 2 project.

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

⭐ SEE ALSO ⭐

babeltrace2-intro(7), babeltrace2-plugin-ctf(7), lttng-relayd(8), lttng-create(1)

okay that's the whole page bestie, you're officially fluent in source.ctf.lttng-live 💅 this was the BABELTRACE2-SOURCE manual section, and that's a wrap — slay, go connect to a relay daemon, and remember: the message iterator never ends unless you tell it to ✨🦋🎀

📦 where this page comes from