Commit | Line | Data |
---|---|---|
0659f3af PP |
1 | babeltrace-source.ctf.lttng-live(7) |
2 | =================================== | |
3 | :manpagetype: component class | |
4 | :revdate: 5 October 2017 | |
5 | ||
6 | ||
7 | NAME | |
8 | ---- | |
9 | babeltrace-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:babeltrace-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:babeltrace(1):--log-level option of | |
176 | man:babeltrace(1). | |
177 | ||
178 | ||
179 | include::common-footer.txt[] | |
180 | ||
181 | ||
182 | SEE ALSO | |
183 | -------- | |
184 | man:babeltrace-plugin-ctf(7), | |
185 | man:babeltrace-intro(7), | |
186 | man:lttng-relayd(8), | |
187 | man:lttng-create(1) |