doc/man/babeltrace2-source.ctf.lttng-live.7.txt

   1 = babeltrace2-source.ctf.lttng-live(7)
   2 :manpagetype: component class
   3 :revdate: 14 September 2019
   4
   5
   6 == NAME
   7
   8 babeltrace2-source.ctf.lttng-live - Babeltrace 2's LTTng live source
   9 component class
  10
  11
  12 == DESCRIPTION
  13
  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.
  18
  19 ----
  20 CTF streams over
  21 LTTng live (TCP)
  22   |
  23   |   +--------------------+
  24   |   | src.ctf.lttng-live |
  25   '-->|                    |
  26       |                out @--> Sorted messages of one
  27       +--------------------+    or more streams
  28 ----
  29
  30 More information about LTTng live is available in the
  31 https://lttng.org/docs/#doc-lttng-live[LTTng Documentation].
  32
  33 include::common-see-babeltrace2-intro.txt[]
  34
  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
  37 streams internally.
  38
  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.
  43
  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.
  47
  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.
  54
  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
  58 daemon.
  59
  60
  61 == INITIALIZATION PARAMETERS
  62
  63 param:inputs='URL' vtype:[array of one string]::
  64     Use 'URL' to connect to the LTTng relay daemon.
  65 +
  66 'URL' is an array of exactly one string of which the format is:
  67 +
  68 --
  69 [verse]
  70 net[4]://__RDHOST__[:__RDPORT__]/host/__TGTHOST__/__SESSION__
  71
  72 'RDHOST'::
  73     LTTng relay daemon's host name or IP address.
  74
  75 'RDPORT'::
  76     LTTng relay daemon's listening port.
  77 +
  78 If not specified, the component uses the default port ({defrdport}).
  79
  80 'TGTHOST'::
  81     Target's host name or IP address.
  82
  83 'SESSION'::
  84     Name of the LTTng tracing session from which to receive data.
  85 --
  86
  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:
  90 +
  91 --
  92 `continue` (default)::
  93     Keep on trying, returning "try again later" to the downstream user
  94     until the tracing session exists.
  95 +
  96 With this action, the message iterator never ends, as the LTTng live
  97 protocol cannot currently indicate that a tracing session will never
  98 exist.
  99
 100 `fail`::
 101     Fail.
 102
 103 `end`::
 104     End.
 105 --
 106
 107
 108 == PORTS
 109
 110 ----
 111 +--------------------+
 112 | src.ctf.lttng-live |
 113 |                    |
 114 |                out @
 115 +--------------------+
 116 ----
 117
 118
 119 === Output
 120
 121 `out`::
 122     Single output port.
 123
 124
 125 == QUERY OBJECTS
 126
 127 === `babeltrace.support-info`
 128
 129 See man:babeltrace2-query-babeltrace.support-info(7) to learn more
 130 about this query object.
 131
 132 For a string input which honors the LTTng live URL format (see the
 133 param:inputs parameter), the result object is 0.75.
 134
 135
 136 === `sessions`
 137
 138 You can query the `sessions` object to get a list of available LTTng
 139 tracing sessions for a given LTTng relay daemon URL.
 140
 141 Parameters:
 142
 143 nlparam:url='URL' vtype:[string]::
 144     Use 'URL' to connect to the LTTng relay daemon.
 145 +
 146 The format of 'URL' is:
 147 +
 148 --
 149 [verse]
 150 net[4]://__RDHOST__[:__RDPORT__]
 151
 152 'RDHOST'::
 153     LTTng relay daemon's host name or IP address.
 154
 155 'RDPORT'::
 156     LTTng relay daemon's listening port.
 157 +
 158 If not specified, the query operation uses the default port
 159 ({defrdport}).
 160 --
 161
 162 Result object (array of maps, one element for each available tracing
 163 session):
 164
 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.
 168
 169 qres:session-name vtype:[string]::
 170     Tracing session's name.
 171
 172 qres:stream-count vtype:[unsigned integer]::
 173     Current number of CTF streams in this tracing sessions, including
 174     the metadata streams.
 175
 176 qres:target-hostname vtype:[string]::
 177     Hostname of the tracing session.
 178 +
 179 This is not necessarily the relay daemon's hostname.
 180
 181 qres:timer-us vtype:[unsigned integer]::
 182     Tracing session's configured live timer's period (µs)
 183     (see man:lttng-create(1)).
 184
 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
 188     tracing session.
 189
 190
 191 include::common-footer.txt[]
 192
 193
 194 == SEE ALSO
 195
 196 man:babeltrace2-intro(7),
 197 man:babeltrace2-plugin-ctf(7),
 198 man:lttng-relayd(8),
 199 man:lttng-create(1)