901e17514c85d06fa81b4e4280fefa905a2e28b1
[lttng-ust.git] / README
1 LTTNG USERSPACE TRACER (UST)
2 ----------------------------
3
4 UST web site and manual: http://lttng.org/ust
5
6 Updated versions of this package may be found at:
7
8 * Website: http://lttng.org/ust
9 * Releases: http://lttng.org/files/ust/releases
10 * GitWeb: http://git.lttng.org (project: ust)
11 * Git: git://git.lttng.org/ust.git
12
13
14 PREREQUISITES:
15
16 - liburcu
17 Userspace RCU library, by Mathieu Desnoyers and Paul E. McKenney
18
19 -> This release depends on liburcu v0.6
20
21 * Debian/Ubuntu package: liburcu-dev
22 * Website: http://lttng.org/urcu
23 * Releases: http://lttng.org/files/urcu
24 * GitWeb: http://lttng.org/cgi-bin/gitweb.cgi?p=userspace-rcu.git;a=summary
25 * Git: git://lttng.org/userspace-rcu.git
26
27
28 INSTALLATION INSTRUCTIONS:
29
30 - Download, compile and install liburcu.
31 - In this package's tree, run ./configure.
32 - Run make.
33 - Run make install.
34 - Run ldconfig.
35 - See the manual for usage instructions.
36
37 If compiling from the git repository, run ./bootstrap before running
38 the configure script, to generate it.
39
40
41 USAGE:
42
43 - Create an instrumentation header following the tracepoint examples.
44 (see tracepoint.h and tests/hello/tp.h).
45 - Link application with -lust.
46 - (TODO: start tracing with the "lttng" command from lttng-tools)
47
48 ENVIRONMENT VARIABLES:
49
50 - libust debug can be activated by setting the environment variable
51 "UST_DEBUG" when launching the application. It can also be enabled
52 at compile-time by compiling libust with -DUST_DEBUG.
53
54 - The environment variable "UST_REGISTER_TIMEOUT" can be used to
55 specify how long the applications should wait for sessiond
56 "registration done" command before proceeding to execute the main
57 program. The default is 3000ms (3 seconds). The timeout value is
58 specified in milliseconds. The value 0 means "don't wait". The value
59 -1 means "wait forever".
60
61
62 TRACE VIEWER:
63
64 LTTV is used for viewing UST traces. LTTV may be obtained at
65 http://lttng.org in the Downloads section.
66
67 This release has been tested with LTTV 0.12.32.
68
69
70 CONTACT:
71
72 Maintainer: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
73 Mailing list: ltt-dev@lists.casi.polymtl.ca
74
75
76 PACKAGE CONTENTS:
77
78 This package contains the following elements.
79
80 - libust
81 The actual userspace tracing library that must be linked to the
82 instrumented programs.
83
84 - ustctl
85 A program to control the tracing of userspace applications. It can list
86 markers, start the tracing, stop the tracing, enable/disable markers, etc.
87
88 - include
89 The public header files that will be installed on the system.
90
91 - ust-consumerd
92 The daemon that collects trace data and writes it to the disk.
93
94 - doc
95 The documentation.
96
97 - tests
98 Various test programs
99
100 - libustinstr-malloc
101 An example library that can be LD_PRELOAD'ed to instrument calls to malloc()
102 in any program without need to recompile it.
103
104 - libustfork
105 A library that is LD_PRELOAD'ed, and that hijacks calls to several system
106 calls in order to trace across these calls. It _has_ to be LD_PRELOAD'ed
107 in order to hijack calls. In contrast, libust may be linked at build time.
108
109 - libustctl
110 A library to control tracing in other processes. Used by ustctl.
111
112 - libustcomm
113 A static library shared between libust, ust-consumerd and libustctl, that
114 provides functions that allow these components to communicate together.
115
116 - libustconsumer
117 A library to create ust consumers by registering callbacks, used by
118 ust-consumerd.
119
120 - snprintf
121 An asynchronous signal-safe version of snprintf.
122
123 - java
124 A simple library that uses JNI to allow tracing in java programs.
125 See java/README for build instructions.
This page took 0.036624 seconds and 4 git commands to generate.