Commit | Line | Data |
---|---|---|
90d125c7 | 1 | Useless change |
28ed9628 PP |
2 | LTTng-UST |
3 | ========= | |
4 | ||
5 | The LTTng User Space Tracing (LTTng-UST) library allows any C/C++ | |
6 | application to be instrumented for and traced by | |
7 | [LTTng](http://lttng.org/). LTTng-UST also includes a logging | |
8 | back-end for Java applications and various dynamically loadable | |
9 | user space tracing helpers for any application. | |
10 | ||
11 | ||
12 | Prerequisites | |
13 | ------------- | |
14 | ||
a610548a MD |
15 | LTTng-UST depends on **[liburcu](http://liburcu.org/) >= 0.12** at build |
16 | time. It also optionally depends on libnuma. | |
28ed9628 PP |
17 | |
18 | ||
19 | Building | |
20 | -------- | |
21 | ||
22 | ### Prerequisites | |
23 | ||
24 | This source tree is based on the Autotools suite from GNU to simplify | |
25 | portability. Here are some things you should have on your system in order to | |
26 | compile the Git repository tree: | |
27 | ||
6f9466c5 | 28 | - [GNU Autotools](http://www.gnu.org/software/autoconf/) |
90e5d8e4 MJ |
29 | (**Automake >= 1.12**, **Autoconf >= 2.69**, |
30 | **Autoheader >= 2.69**; | |
28ed9628 | 31 | make sure your system-wide `automake` points to a recent version!) |
6f9466c5 | 32 | - **[GNU Libtool](https://www.gnu.org/software/libtool/) >= 2.2** |
ff1ee9bc | 33 | - **[pkg-config](https://www.freedesktop.org/wiki/Software/pkg-config/)** |
c5123a13 PP |
34 | |
35 | ||
36 | ### Optional dependencies | |
28ed9628 | 37 | |
b49b04f4 | 38 | Optional packages to build LTTng-ust man pages: |
4ddbd0b7 PP |
39 | |
40 | - **[AsciiDoc](http://www.methods.co.nz/asciidoc/) >= 8.4.5** | |
41 | (previous versions may work, but were not tested) | |
42 | - **[xmlto](https://fedorahosted.org/xmlto/) >= 0.0.21** (previous | |
43 | versions may work, but were not tested) | |
44 | ||
45 | Note that the man pages are already built in a distribution tarball. | |
46 | In this case, you only need AsciiDoc and xmlto if you indend to modify | |
47 | the AsciiDoc man page sources. | |
48 | ||
c5123a13 PP |
49 | Needed for `make check` and tests: |
50 | ||
51 | - **[Perl](https://www.perl.org/)** | |
52 | ||
53 | ||
54 | ### Building steps | |
55 | ||
28ed9628 PP |
56 | If you get the tree from the Git repository, you will need to run |
57 | ||
58 | ./bootstrap | |
59 | ||
60 | in its root. It calls all the GNU tools needed to prepare the tree | |
61 | configuration. | |
62 | ||
63 | To build LTTng-UST, do: | |
64 | ||
65 | ./configure | |
66 | make | |
67 | sudo make install | |
68 | sudo ldconfig | |
69 | ||
70 | **Note:** the `configure` script sets `/usr/local` as the default prefix for | |
71 | files it installs. However, this path is not part of most distributions' | |
72 | default library path, which will cause builds depending on `liblttng-ust` | |
73 | to fail unless `-L/usr/local/lib` is added to `LDFLAGS`. You may provide a | |
74 | custom prefix to `configure` by using the `--prefix` switch | |
75 | (e.g., `--prefix=/usr`). LTTng-UST needs to be a shared library, _even if_ | |
76 | the tracepoint probe provider is statically linked into the application. | |
77 | ||
78 | ||
79 | Using | |
80 | ----- | |
81 | ||
82 | First of all, create an instrumentation header following the | |
83 | [tracepoint examples](doc/examples). | |
84 | ||
85 | There are two ways to compile the tracepoint provider and link it with | |
86 | your application: statically or dynamically. Please follow carefully one | |
87 | or the other method. | |
88 | ||
89 | ||
90 | ### Static linking | |
91 | ||
92 | This method links the tracepoint provider with the application, | |
93 | either directly or through a static library (`.a`): | |
94 | ||
95 | 1. Into exactly one unit (C/C++ source file) of your _application_, | |
88c7c4ea | 96 | define `LTTNG_UST_TRACEPOINT_DEFINE` and include the tracepoint provider |
28ed9628 PP |
97 | header. |
98 | 2. Include the tracepoint provider header into all C/C++ files using | |
99 | the provider and insert tracepoints using the `tracepoint()` macro. | |
88c7c4ea | 100 | 3. Use `-I.` when compiling the unit defining `LTTNG_UST_TRACEPOINT_DEFINE` |
28ed9628 PP |
101 | (e.g., `tp.c`). |
102 | 4. Link the application with `-ldl` on Linux, or with `-lc` on BSD, | |
103 | and with `-llttng-ust`. | |
104 | ||
105 | Example: | |
106 | ||
107 | gcc -c -I. tp.c | |
108 | gcc -c some-source.c | |
109 | gcc -c other-source.c | |
110 | gcc -o my-app tp.o some-source.o other-source.o -ldl -llttng-ust | |
111 | ||
112 | Run the application directly: | |
113 | ||
114 | ./my-app | |
115 | ||
116 | Other relevant examples: | |
117 | ||
118 | - [`doc/examples/easy-ust`](doc/examples/easy-ust) | |
119 | - [`doc/examples/hello-static-lib`](doc/examples/hello-static-lib) | |
120 | ||
121 | ||
122 | ### Dynamic loading | |
123 | ||
124 | This method decouples the tracepoint provider from the application, | |
125 | making it dynamically loadable. | |
126 | ||
127 | 1. Into exactly one unit of your _application_, define | |
88c7c4ea | 128 | `LTTNG_UST_TRACEPOINT_DEFINE` _and_ `LTTNG_UST_TRACEPOINT_PROBE_DYNAMIC_LINKAGE`, |
28ed9628 PP |
129 | then include the tracepoint provider header. |
130 | 2. Include the tracepoint provider header into all C/C++ files using | |
131 | the provider and insert tracepoints using the `tracepoint()` macro. | |
132 | 3. Use `-I.` and `-fpic` when compiling the tracepoint provider | |
133 | (e.g., `tp.c`). | |
134 | 4. Link the tracepoint provider with `-llttng-ust` and make it a | |
135 | shared object with `-shared`. | |
136 | 5. Link the application with `-ldl` on Linux, or with `-lc` on BSD. | |
137 | ||
138 | Example: | |
139 | ||
140 | gcc -c -I. -fpic tp.c | |
141 | gcc -o tp.so -shared tp.o -llttng-ust | |
142 | gcc -o my-app some-source.c other-source.c -ldl | |
143 | ||
144 | To run _without_ LTTng-UST support: | |
145 | ||
146 | ./my-app | |
147 | ||
148 | To run with LTTng-UST support (register your tracepoint provider, | |
149 | `tp.so`): | |
150 | ||
151 | LD_PRELOAD=./tp.so ./my-app | |
152 | ||
153 | You could also use `libdl` directly in your application and `dlopen()` | |
154 | your tracepoint provider shared object (`tp.so`) to make LTTng-UST | |
155 | tracing possible. | |
156 | ||
157 | Other relevant examples: | |
158 | ||
159 | - [`doc/examples/demo`](doc/examples/demo) | |
160 | ||
161 | ||
162 | ### Controlling tracing and viewing traces | |
163 | ||
164 | Use [LTTng-tools](https://lttng.org/download) to control the tracer. | |
165 | Use [Babeltrace](https://lttng.org/babeltrace) to print traces as a | |
166 | human-readable text log. | |
167 | ||
168 | ||
169 | ### Environment variables and compile flags | |
170 | ||
171 | - `liblttng-ust` debug can be activated by setting the environment | |
172 | variable `LTTNG_UST_DEBUG` when launching the user application. It | |
173 | can also be enabled at build time by compiling LTTng-UST with | |
174 | `-DLTTNG_UST_DEBUG`. | |
9ff107a9 MJ |
175 | - `liblttng-ust` abort on critical can be activated by setting the |
176 | environment variable `LTTNG_UST_ABORT_ON_CRITICAL` when launching the user | |
177 | application. It can also be enabled at build time by compiling LTTng-UST with | |
178 | `-DLTTNG_UST_ABORT_ON_CRITICAL`. | |
28ed9628 PP |
179 | - The environment variable `LTTNG_UST_REGISTER_TIMEOUT` can be used to |
180 | specify how long the applications should wait for the session | |
181 | daemon _registration done_ command before proceeding to execute the | |
182 | main program. The default is 3000 ms (3 seconds). The timeout value | |
183 | is specified in milliseconds. The value 0 means _don't wait_. The | |
184 | value -1 means _wait forever_. Setting this environment variable to 0 | |
185 | is recommended for applications with time constraints on the process | |
186 | startup time. | |
187 | - The compilation flag `-DLTTNG_UST_DEBUG_VALGRIND` should be enabled | |
188 | at build time to allow `liblttng-ust` to be used with Valgrind | |
189 | (side-effect: disables per-CPU buffering). | |
190 | ||
191 | ||
192 | ### Notes | |
193 | ||
194 | #### C++ support | |
195 | ||
196 | Since LTTng-UST 2.3, both tracepoints and tracepoint providers can be | |
197 | compiled in C++. To compile tracepoint probes in C++, you need | |
7850c5cc | 198 | G++ >= 4.7 or Clang >= 4.0. The C++ compilers need to support C++11. |
28ed9628 PP |
199 | |
200 | ||
201 | Contact | |
202 | ------- | |
203 | ||
204 | Maintainer: [Mathieu Desnoyers](mailto:mathieu.desnoyers@efficios.com) | |
205 | ||
206 | Mailing list: [`lttng-dev@lists.lttng.org`](https://lttng.org/cgi-bin/mailman/listinfo/lttng-dev) | |
207 | ||
208 | ||
209 | Package contents | |
210 | ---------------- | |
211 | ||
212 | This package contains the following elements: | |
213 | ||
214 | - `doc`: LTTng-UST documentation and examples. | |
215 | - `include`: the public header files that will be installed on the | |
216 | system. | |
217 | - `liblttng-ust`: the actual userspace tracing library that must be | |
218 | linked to the instrumented programs. | |
219 | - `liblttng-ust-comm`: a static library shared between `liblttng-ust` | |
220 | and LTTng-tools, that provides functions that allow these components | |
221 | to communicate together. | |
222 | - `liblttng-ust-ctl`: a library to control tracing in other processes; | |
223 | used by LTTng-tools. | |
224 | - `liblttng-ust-cyg-profile`: a library that can be preloaded (using | |
225 | `LD_PRELOAD`) to instrument function entries and exits when the target | |
226 | application is built with the GCC flag `-finstrument-functions`. | |
227 | - `liblttng-ust-dl`: a library that can be preloaded to instrument | |
228 | calls to `dlopen()` and `dlclose()`. | |
229 | - `liblttng-ust-fork`: a library that is preloaded and that hijacks | |
230 | calls to several system calls in order to trace across these calls. | |
231 | It _has_ to be preloaded in order to hijack calls. In contrast, | |
232 | `liblttng-ust` may be linked at build time. | |
233 | - `liblttng-ust-java`: a simple library that uses JNI to allow tracing | |
380a81f4 | 234 | in Java programs. (Configure with `--enable-jni-interface`). |
b49b04f4 MJ |
235 | - `liblttng-ust-java-agent`: a package that includes a JNI library and a |
236 | JAR library to provide an LTTng-UST logging back-end for Java | |
380a81f4 GB |
237 | applications using Java Util Logging or Log4j. (Configure with |
238 | `--enable-java-agent-jul` or `--enable-java-agent-log4j` or | |
464c4756 | 239 | `--enable-java-agent-log4j2` or `--enable-java-agent-all`). |
28ed9628 PP |
240 | - `liblttng-ust-libc-wrapper`: an example library that can be |
241 | preloaded to instrument some calls to libc (currently `malloc()` and | |
242 | `free()`) and to POSIX threads (mutexes currently instrumented) in | |
243 | any program without need to recompile it. | |
b49b04f4 | 244 | - `liblttng-ust-python-agent`: a library used by python-lttngust to allow |
380a81f4 | 245 | tracing in Python applications. (Configure with `--enable-python-agent`) |
28ed9628 | 246 | - `libringbuffer`: the ring buffer implementation used within LTTng-UST. |
b49b04f4 MJ |
247 | - `python-lttngust`: a package to provide an LTTng-UST logging back-end |
248 | for Python applications using the standard logging framework. | |
28ed9628 PP |
249 | - `snprintf`: an asynchronous signal-safe version of `snprintf()`. |
250 | - `tests`: various test programs. | |
251 | - `tools`: home of `lttng-gen-tp`. |