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