| 1 | .TH "LTTNG-UST" "3" "February 16, 2012" "" "" |
| 2 | |
| 3 | .SH "NAME" |
| 4 | lttng-ust \(em Linux Trace Toolkit Next Generation User-Space Tracer |
| 5 | |
| 6 | .SH "SYNOPSIS" |
| 7 | |
| 8 | .PP |
| 9 | .nf |
| 10 | Link liblttng-ust.so with applications, following this manpage. |
| 11 | .fi |
| 12 | .SH "DESCRIPTION" |
| 13 | |
| 14 | .PP |
| 15 | LTTng-UST, the Linux Trace Toolkit Next Generation Userspace Tracer, is |
| 16 | port of the low-overhead tracing capabilities of the LTTng kernel tracer |
| 17 | to user-space. The library "liblttng-ust" enables tracing of |
| 18 | applications and libraries. |
| 19 | |
| 20 | .SH "USAGE" |
| 21 | .PP |
| 22 | The simple way to generate the lttng-ust tracepoint probes is to use the |
| 23 | lttng-gen-tp(1) tool. See the lttng-gen-tp(1) manpage for explanation. |
| 24 | .PP |
| 25 | |
| 26 | .PP |
| 27 | Here is the way to do it manually, without the lttng-gen-tp(1) helper |
| 28 | script, through an example: |
| 29 | .PP |
| 30 | |
| 31 | .SH "CREATION OF TRACEPOINT PROVIDER" |
| 32 | |
| 33 | .nf |
| 34 | |
| 35 | To create a tracepoint provider, within a build tree similar to |
| 36 | examples/easy-ust installed with lttng-ust documentation, a |
| 37 | sample_component_provider.h for the general layout. This manpage will |
| 38 | focus on the various types that can be recorded into a trace event: |
| 39 | |
| 40 | TRACEPOINT_EVENT( |
| 41 | /* |
| 42 | * provider name, not a variable but a string starting with a |
| 43 | * letter and containing either letters, numbers or underscores. |
| 44 | * Needs to be the same as TRACEPOINT_PROVIDER. Needs to |
| 45 | * follow the namespacing guide-lines in lttng/tracepoint.h: |
| 46 | * |
| 47 | * Must be included before include tracepoint provider |
| 48 | * ex.: project_event |
| 49 | * ex.: project_component_event |
| 50 | * |
| 51 | * Optional company name goes here |
| 52 | * ex.: com_efficios_project_component_event |
| 53 | * |
| 54 | * In this example, "sample" is the project, and "component" is the |
| 55 | * component. |
| 56 | */ |
| 57 | sample_component, |
| 58 | |
| 59 | /* |
| 60 | * tracepoint name, same format as sample provider. Does not |
| 61 | * need to be declared before. in this case the name is |
| 62 | * "message" |
| 63 | */ |
| 64 | message, |
| 65 | |
| 66 | /* |
| 67 | * TP_ARGS macro contains the arguments passed for the tracepoint |
| 68 | * it is in the following format |
| 69 | * TP_ARGS(type1, name1, type2, name2, ... type10, |
| 70 | name10) |
| 71 | * where there can be from zero to ten elements. |
| 72 | * typeN is the datatype, such as int, struct or double **. |
| 73 | * name is the variable name (in "int myInt" the name would be |
| 74 | * myint) |
| 75 | * TP_ARGS() is valid to mean no arguments |
| 76 | * TP_ARGS(void) is valid too |
| 77 | */ |
| 78 | TP_ARGS(int, anint, int, netint, long *, values, |
| 79 | char *, text, size_t, textlen, |
| 80 | double, doublearg, float, floatarg), |
| 81 | |
| 82 | /* |
| 83 | * TP_FIELDS describes how to write the fields of the trace event. |
| 84 | * You can put expressions in the "argument expression" area, |
| 85 | * typically using the input arguments from TP_ARGS. |
| 86 | */ |
| 87 | TP_FIELDS( |
| 88 | /* |
| 89 | * ctf_integer: standard integer field. |
| 90 | * args: (type, field name, argument expression) |
| 91 | */ |
| 92 | ctf_integer(int, intfield, anint) |
| 93 | ctf_integer(long, longfield, anint) |
| 94 | |
| 95 | /* |
| 96 | * ctf_integer_hex: integer field printed as hexadecimal. |
| 97 | * args: (type, field name, argument expression) |
| 98 | */ |
| 99 | ctf_integer_hex(int, intfield2, anint) |
| 100 | |
| 101 | /* |
| 102 | * ctf_integer_network: integer field in network byte |
| 103 | * order. (_hex: printed as hexadecimal too) |
| 104 | * args: (type, field name, argument expression) |
| 105 | */ |
| 106 | ctf_integer_network(int, netintfield, netint) |
| 107 | ctf_integer_network_hex(int, netintfieldhex, netint) |
| 108 | |
| 109 | /* |
| 110 | * ctf_array: a statically-sized array. |
| 111 | * args: (type, field name, argument expression, value) |
| 112 | */ |
| 113 | ctf_array(long, arrfield1, values, 3) |
| 114 | |
| 115 | /* |
| 116 | * ctf_array_text: a statically-sized array, printed as |
| 117 | * a string. No need to be terminated by a null |
| 118 | * character. |
| 119 | */ |
| 120 | ctf_array_text(char, arrfield2, text, 10) |
| 121 | |
| 122 | /* |
| 123 | * ctf_sequence: a dynamically-sized array. |
| 124 | * args: (type, field name, argument expression, |
| 125 | * type of length expression, length expression) |
| 126 | */ |
| 127 | ctf_sequence(char, seqfield1, text, |
| 128 | size_t, textlen) |
| 129 | |
| 130 | /* |
| 131 | * ctf_sequence_text: a dynamically-sized array, printed |
| 132 | * as string. No need to be null-terminated. |
| 133 | */ |
| 134 | ctf_sequence_text(char, seqfield2, text, |
| 135 | size_t, textlen) |
| 136 | |
| 137 | /* |
| 138 | * ctf_string: null-terminated string. |
| 139 | * args: (field name, argument expression) |
| 140 | */ |
| 141 | ctf_string(stringfield, text) |
| 142 | |
| 143 | /* |
| 144 | * ctf_float: floating-point number. |
| 145 | * args: (type, field name, argument expression) |
| 146 | */ |
| 147 | ctf_float(float, floatfield, floatarg) |
| 148 | ctf_float(double, doublefield, doublearg) |
| 149 | ) |
| 150 | ) |
| 151 | .fi |
| 152 | |
| 153 | .SH "ASSIGNING LOGLEVEL TO EVENTS" |
| 154 | |
| 155 | .nf |
| 156 | |
| 157 | Optionally, a loglevel can be assigned to a TRACEPOINT_EVENT using the |
| 158 | following construct: |
| 159 | |
| 160 | TRACEPOINT_LOGLEVEL(< [com_company_]project[_component] >, |
| 161 | < event >, < loglevel_name >) |
| 162 | |
| 163 | The first field is the provider name, the second field is the name of |
| 164 | the tracepoint, and the third field is the loglevel name. A |
| 165 | TRACEPOINT_EVENT should be declared prior to the the TRACEPOINT_LOGLEVEL |
| 166 | for a given tracepoint name. The TRACEPOINT_PROVIDER must be already |
| 167 | declared before declaring a TRACEPOINT_LOGLEVEL. |
| 168 | |
| 169 | The loglevels go from 0 to 14. Higher numbers imply the most verbosity |
| 170 | (higher event throughput expected. |
| 171 | |
| 172 | Loglevels 0 through 6, and loglevel 14, match syslog(3) loglevels |
| 173 | semantic. Loglevels 7 through 13 offer more fine-grained selection of |
| 174 | debug information. |
| 175 | |
| 176 | TRACE_EMERG 0 |
| 177 | system is unusable |
| 178 | |
| 179 | TRACE_ALERT 1 |
| 180 | action must be taken immediately |
| 181 | |
| 182 | TRACE_CRIT 2 |
| 183 | critical conditions |
| 184 | |
| 185 | TRACE_ERR 3 |
| 186 | error conditions |
| 187 | |
| 188 | TRACE_WARNING 4 |
| 189 | warning conditions |
| 190 | |
| 191 | TRACE_NOTICE 5 |
| 192 | normal, but significant, condition |
| 193 | |
| 194 | TRACE_INFO 6 |
| 195 | informational message |
| 196 | |
| 197 | TRACE_DEBUG_SYSTEM 7 |
| 198 | debug information with system-level scope (set of programs) |
| 199 | |
| 200 | TRACE_DEBUG_PROGRAM 8 |
| 201 | debug information with program-level scope (set of processes) |
| 202 | |
| 203 | TRACE_DEBUG_PROCESS 9 |
| 204 | debug information with process-level scope (set of modules) |
| 205 | |
| 206 | TRACE_DEBUG_MODULE 10 |
| 207 | debug information with module (executable/library) scope (set of |
| 208 | units) |
| 209 | |
| 210 | TRACE_DEBUG_UNIT 11 |
| 211 | debug information with compilation unit scope (set of functions) |
| 212 | |
| 213 | TRACE_DEBUG_FUNCTION 12 |
| 214 | debug information with function-level scope |
| 215 | |
| 216 | TRACE_DEBUG_LINE 13 |
| 217 | debug information with line-level scope (TRACEPOINT_EVENT default) |
| 218 | |
| 219 | TRACE_DEBUG 14 |
| 220 | debug-level message (trace_printf default) |
| 221 | |
| 222 | See lttng(1) for information on how to use LTTng-UST loglevels. |
| 223 | |
| 224 | .fi |
| 225 | |
| 226 | .SH "ADDING TRACEPOINTS TO YOUR CODE" |
| 227 | |
| 228 | .nf |
| 229 | |
| 230 | Include the provider header in each C files you plan to instrument, |
| 231 | following the building/linking directives in the next section. |
| 232 | |
| 233 | For instance, add within a function: |
| 234 | |
| 235 | tracepoint(ust_tests_hello, tptest, i, netint, values, |
| 236 | text, strlen(text), dbl, flt); |
| 237 | |
| 238 | As a call to the tracepoint. It will only be activated when requested by |
| 239 | lttng(1) through lttng-sessiond(8). |
| 240 | |
| 241 | .fi |
| 242 | |
| 243 | .SH "BUILDING/LINKING THE TRACEPOINT PROVIDER" |
| 244 | |
| 245 | .nf |
| 246 | There are 2 ways to compile the Tracepoint Provider with the |
| 247 | application: either statically or dynamically. Please follow |
| 248 | carefully: |
| 249 | |
| 250 | 1.1) Compile the Tracepoint provider with the application, either |
| 251 | directly or through a static library (.a): |
| 252 | - Into exactly one object of your application: define |
| 253 | "TRACEPOINT_DEFINE" and include the tracepoint provider. |
| 254 | - Use "-I." for the compilation unit containing the tracepoint |
| 255 | provider include (e.g. tp.c). |
| 256 | - Link application with "-ldl". |
| 257 | - If building the provider directly into the application, |
| 258 | link the application with "-llttng-ust". |
| 259 | - If building a static library for the provider, link the static |
| 260 | library with "-lllttng-ust". |
| 261 | - Include the tracepoint provider header into all C files using |
| 262 | the provider. |
| 263 | - Example: |
| 264 | tests/hello/ hello.c tp.c ust_tests_hello.h Makefile.example |
| 265 | |
| 266 | 2) Compile the Tracepoint Provider separately from the application, |
| 267 | using dynamic linking: |
| 268 | - Into exactly one object of your application: define |
| 269 | "TRACEPOINT_DEFINE" _and_ also define |
| 270 | "TRACEPOINT_PROBE_DYNAMIC_LINKAGE", then include the tracepoint |
| 271 | provider header. |
| 272 | - Include the tracepoint provider header into all instrumented C |
| 273 | files that use the provider. |
| 274 | - Compile the tracepoint provider with "-I.". |
| 275 | - Link the tracepoint provider with "-llttng-ust". |
| 276 | - Link application with "-ldl". |
| 277 | - Set a LD_PRELOAD environment to preload the tracepoint provider |
| 278 | shared object before starting the application when tracing is |
| 279 | needed. |
| 280 | - Example: |
| 281 | - tests/demo/ demo.c tp*.c ust_tests_demo*.h demo-trace |
| 282 | |
| 283 | - Note about dlopen() usage: due to locking side-effects due to the |
| 284 | way libc lazily resolves Thread-Local Storage (TLS) symbols when a |
| 285 | library is dlopen'd, linking the tracepoint probe or liblttng-ust |
| 286 | with dlopen() is discouraged. They should be linked with the |
| 287 | application using "-llibname" or loaded with LD_PRELOAD. |
| 288 | - Enable instrumentation and control tracing with the "lttng" command |
| 289 | from lttng-tools. See lttng-tools doc/quickstart.txt. |
| 290 | |
| 291 | .fi |
| 292 | |
| 293 | .SH "ENVIRONMENT VARIABLES" |
| 294 | |
| 295 | .PP |
| 296 | .IP "LTTNG_UST_DEBUG" |
| 297 | Activate liblttng-ust debug output. |
| 298 | .PP |
| 299 | .IP "LTTNG_UST_REGISTER_TIMEOUT" |
| 300 | The environment variable "LTTNG_UST_REGISTER_TIMEOUT" can be used to |
| 301 | specify how long the applications should wait for sessiond |
| 302 | "registration done" command before proceeding to execute the main |
| 303 | program. The default is 3000ms (3 seconds). The timeout value is |
| 304 | specified in milliseconds. The value 0 means "don't wait". The value |
| 305 | -1 means "wait forever". Setting this environment variable to 0 is |
| 306 | recommended for applications with time constraints on the process |
| 307 | startup time. |
| 308 | .PP |
| 309 | |
| 310 | .SH "SEE ALSO" |
| 311 | |
| 312 | .PP |
| 313 | lttng-gen-tp(1), lttng(1), babeltrace(1), lttng-sessiond(8) |
| 314 | .PP |
| 315 | .SH "BUGS" |
| 316 | |
| 317 | .PP |
| 318 | No knows bugs at this point. |
| 319 | |
| 320 | If you encounter any issues or usability problem, please report it on |
| 321 | our mailing list <lttng-dev@lists.lttng.org> to help improve this |
| 322 | project. |
| 323 | .SH "CREDITS" |
| 324 | |
| 325 | liblttng-ust is distributed under the GNU Lesser General Public License |
| 326 | version 2.1. The headers are distributed under the MIT license. |
| 327 | .PP |
| 328 | See http://lttng.org for more information on the LTTng project. |
| 329 | .PP |
| 330 | Mailing list for support and development: <lttng-dev@lists.lttng.org>. |
| 331 | .PP |
| 332 | You can find us on IRC server irc.oftc.net (OFTC) in #lttng. |
| 333 | .PP |
| 334 | .SH "THANKS" |
| 335 | |
| 336 | Thanks to Ericsson for funding this work, providing real-life use-cases, |
| 337 | and testing. |
| 338 | |
| 339 | Special thanks to Michel Dagenais and the DORSAL laboratory at |
| 340 | Polytechnique de Montreal for the LTTng journey. |
| 341 | .PP |
| 342 | .SH "AUTHORS" |
| 343 | |
| 344 | .PP |
| 345 | liblttng-ust was originally written by Mathieu Desnoyers, with additional |
| 346 | contributions from various other people. It is currently maintained by |
| 347 | Mathieu Desnoyers <mathieu.desnoyers@efficios.com>. |
| 348 | .PP |