| 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) |