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

   1 babeltrace2-source.ctf.lttng-live(7)
   2 ===================================
   3 :manpagetype: component class
   4 :revdate: 5 October 2017
   5
   6
   7 NAME
   8 ----
   9 babeltrace2-source.ctf.lttng-live - Babeltrace's LTTng live source
  10 component class
  11
  12
  13 DESCRIPTION
  14 -----------
  15 The Babeltrace compcls:source.ctf.lttng-live source component class,
  16 provided by the man:babeltrace2-plugin-ctf(7) plugin, once instantiated,
  17 connects to a local or remote http://lttng.org/[LTTng] relay daemon and
  18 emits the received notifications on its output ports. More information
  19 about LTTng live is available in the
  20 http://lttng.org/docs/#doc-lttng-live[LTTng Documentation].
  21
  22 A compcls:source.ctf.lttng-live component handles the notifications of
  23 one, and only one LTTng tracing session. A single LTTng tracing session
  24 can contain one or more traces, depending on the active tracing domains
  25 and the configured user space buffering scheme.
  26
  27 The component connects to an LTTng relay daemon using the param:url
  28 parameter.
  29
  30 For each trace, the component creates one output port per effective data
  31 stream. The name of a data stream output port is `stream-` followed by
  32 its unique LTTng live ID within the tracing session.
  33
  34 The component names each trace `[HOSTNAME/]SESSION/PATH`, with:
  35
  36 `HOSTNAME`::
  37     Value of the trace's `hostname` environment constant. If this
  38     environment constant does not exist, or if its value is not a
  39     string, then this part is omitted.
  40
  41 `SESSION`::
  42     Tracing session name.
  43
  44 `PATH`::
  45     Other path elements up to the trace directory containing the
  46     `metadata` file from the LTTng relay daemon's point of view.
  47     For example:
  48 +
  49 ----
  50 kernel
  51 ----
  52 +
  53 ----
  54 ust/uid/1000/64-bit
  55 ----
  56
  57 For example:
  58
  59 ----
  60 myhost/auto-20150909-223909/ust/uid/1000/64-bit
  61 ----
  62
  63 A compcls:source.ctf.lttng-live never blocks: it asks the downstream
  64 component to try again later instead.
  65
  66
  67 INITIALIZATION PARAMETERS
  68 -------------------------
  69 param:url='URL' (string, mandatory)::
  70     The URL to use to connect to the LTTng relay daemon. The format
  71     of 'URL' is:
  72 +
  73 --
  74 [verse]
  75 net[4]://__RDHOST__[:__RDPORT__]/host/__TGTHOST__/__SESSION__
  76
  77 'RDHOST'::
  78     LTTng relay daemon's host name or IP address.
  79
  80 'RDPORT'::
  81     LTTng relay daemon's listening port. If not specified, the default
  82     port, 5344, is used.
  83
  84 'TGTHOST'::
  85     Target's host name or IP address.
  86
  87 'SESSION'::
  88     Name of the LTTng tracing session from which to receive data.
  89 --
  90
  91
  92 PORTS
  93 -----
  94 Output
  95 ~~~~~~
  96 When you create the component, its only output port is `no-stream`. This
  97 port exists as long as there is no data stream output port. The port
  98 only asks the downstream component to try again later.
  99
 100 For each received LTTng trace, the component creates one output port for
 101 each effective data stream. The name of a data stream output port is
 102 `stream-ID`, where `ID` is a unique LTTng live ID within the tracing
 103 session.
 104
 105
 106 QUERY OBJECTS
 107 -------------
 108 `sessions`
 109 ~~~~~~~~~~
 110 You can query the `sessions` object to get a list of available LTTng
 111 live tracing sessions for a given LTTng relay daemon URL.
 112
 113 Parameters:
 114
 115 `url` (string, mandatory)::
 116     The URL to use to connect to the LTTng relay daemon. The format
 117     of 'URL' is:
 118 +
 119 --
 120 [verse]
 121 net[4]://__RDHOST__[:__RDPORT__]
 122
 123 'RDHOST'::
 124     LTTng relay daemon's host name or IP address.
 125
 126 'RDPORT'::
 127     LTTng relay daemon's listening port. If not specified, the default
 128     port, 5344, is used.
 129 --
 130
 131 Returned object (array of maps, one element for each tracing session):
 132
 133 `url` (string)::
 134     URL to use as the param:url parameter to connect to the same LTTng
 135     relay daemon and receive data from this tracing session.
 136
 137 `target-hostname` (string)::
 138     Hostname of the tracing session. This is not necessarily the
 139     relay daemon's hostname.
 140
 141 `session-name` (string)::
 142     Tracing session's name.
 143
 144 `timer-us` (integer)::
 145     Tracing session's configured live timer (µs)
 146     (see man:lttng-create(1)).
 147
 148 `stream-count` (integer)::
 149     Current number of streams in this tracing sessions, including the
 150     metadata streams.
 151
 152 `client-count` (integer)::
 153     Current number of LTTng live clients connected to the relay daemon
 154     to receive data from this tracing session.
 155
 156
 157 LIMITATIONS
 158 -----------
 159 A compcls:source.ctf.lttng-live component only accepts a connection
 160 to one of its output port if all its output ports are connected to the
 161 input ports of the same downstream component.
 162
 163
 164 ENVIRONMENT VARIABLES
 165 ---------------------
 166 include::common-ctf-plugin-env.txt[]
 167
 168
 169 Component class
 170 ~~~~~~~~~~~~~~~
 171 include::common-common-compat-env.txt[]
 172
 173 `BABELTRACE_SRC_CTF_LTTNG_LIVE_LOG_LEVEL`::
 174     Component class's log level. The available values are the
 175     same as for the manopt:babeltrace2(1):--log-level option of
 176     man:babeltrace2(1).
 177
 178
 179 include::common-footer.txt[]
 180
 181
 182 SEE ALSO
 183 --------
 184 man:babeltrace2-plugin-ctf(7),
 185 man:babeltrace2-intro(7),
 186 man:lttng-relayd(8),
 187 man:lttng-create(1)