Commit | Line | Data |
---|---|---|
e70712b3 | 1 | = babeltrace2-source.ctf.lttng-live(7) |
0659f3af | 2 | :manpagetype: component class |
e70712b3 | 3 | :revdate: 14 September 2019 |
0659f3af PP |
4 | |
5 | ||
e70712b3 PP |
6 | == NAME |
7 | ||
8 | babeltrace2-source.ctf.lttng-live - Babeltrace 2's LTTng live source | |
0659f3af PP |
9 | component class |
10 | ||
11 | ||
e70712b3 | 12 | == DESCRIPTION |
0659f3af | 13 | |
e70712b3 PP |
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. | |
0659f3af | 18 | |
e70712b3 PP |
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 | ---- | |
0659f3af | 29 | |
e70712b3 PP |
30 | More information about LTTng live is available in the |
31 | https://lttng.org/docs/#doc-lttng-live[LTTng Documentation]. | |
0659f3af | 32 | |
e70712b3 | 33 | include::common-see-babeltrace2-intro.txt[] |
0659f3af | 34 | |
e70712b3 PP |
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. | |
0659f3af | 38 | |
e70712b3 PP |
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. | |
0659f3af | 43 | |
e70712b3 PP |
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. | |
0659f3af | 47 | |
e70712b3 PP |
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. | |
0659f3af | 54 | |
e70712b3 PP |
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. | |
0659f3af | 59 | |
0659f3af | 60 | |
e70712b3 | 61 | == INITIALIZATION PARAMETERS |
0659f3af | 62 | |
e70712b3 PP |
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: | |
0659f3af PP |
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':: | |
e70712b3 PP |
76 | LTTng relay daemon's listening port. |
77 | + | |
78 | If not specified, the component uses the default port ({defrdport}). | |
0659f3af PP |
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 | ||
e70712b3 PP |
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. | |
0659f3af | 102 | |
e70712b3 PP |
103 | `end`:: |
104 | End. | |
105 | -- | |
0659f3af | 106 | |
0659f3af | 107 | |
e70712b3 PP |
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` | |
0659f3af | 137 | |
0659f3af | 138 | You can query the `sessions` object to get a list of available LTTng |
e70712b3 | 139 | tracing sessions for a given LTTng relay daemon URL. |
0659f3af PP |
140 | |
141 | Parameters: | |
142 | ||
e70712b3 PP |
143 | nlparam:url='URL' vtype:[string]:: |
144 | Use 'URL' to connect to the LTTng relay daemon. | |
145 | + | |
146 | The format of 'URL' is: | |
0659f3af PP |
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':: | |
e70712b3 PP |
156 | LTTng relay daemon's listening port. |
157 | + | |
158 | If not specified, the query operation uses the default port | |
159 | ({defrdport}). | |
0659f3af PP |
160 | -- |
161 | ||
e70712b3 PP |
162 | Result object (array of maps, one element for each available tracing |
163 | session): | |
0659f3af | 164 | |
e70712b3 | 165 | qres:client-count vtype:[unsigned integer]:: |
0659f3af PP |
166 | Current number of LTTng live clients connected to the relay daemon |
167 | to receive data from this tracing session. | |
168 | ||
e70712b3 PP |
169 | qres:session-name vtype:[string]:: |
170 | Tracing session's name. | |
0659f3af | 171 | |
e70712b3 PP |
172 | qres:stream-count vtype:[unsigned integer]:: |
173 | Current number of CTF streams in this tracing sessions, including | |
174 | the metadata streams. | |
0659f3af | 175 | |
e70712b3 PP |
176 | qres:target-hostname vtype:[string]:: |
177 | Hostname of the tracing session. | |
178 | + | |
179 | This is not necessarily the relay daemon's hostname. | |
0659f3af | 180 | |
e70712b3 PP |
181 | qres:timer-us vtype:[unsigned integer]:: |
182 | Tracing session's configured live timer's period (µs) | |
183 | (see man:lttng-create(1)). | |
0659f3af | 184 | |
e70712b3 PP |
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. | |
0659f3af PP |
189 | |
190 | ||
191 | include::common-footer.txt[] | |
192 | ||
193 | ||
e70712b3 PP |
194 | == SEE ALSO |
195 | ||
a8be4294 | 196 | man:babeltrace2-intro(7), |
e70712b3 | 197 | man:babeltrace2-plugin-ctf(7), |
0659f3af PP |
198 | man:lttng-relayd(8), |
199 | man:lttng-create(1) |