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