lttng-gen-tp(1) [debian man page]
LTTNG-GEN-TP(1) LTTNG-GEN-TP(1)
NAME
lttng-gen-tp -- LTTng UST 2.0 tracepoint code generator
SYNOPSIS
lttng-gen-tp [OPTIONS] TEMPLATE_FILE
DESCRIPTION
The LTTng project aims at providing highly efficient tracing tools for Linux. It's tracers help tracking down performance issues and
debugging problems involving multiple concurrent processes and threads. Tracing across multiple systems is also possible.
The lttng-gen-tp tool simplify the generation of the UST tracepoint files. It takes a simple template file and generate the necessary code
to use the defined tracepoints in your application. The section TEMPLATE FILE FORMAT describe the content of the template file.
Currently, the tool can generate the .h, .c and .o associated to your tracepoint. The generated .h can be directly included in your appli-
cation. You can let the tool generate the .o or compile the .c yourself. You can compile the .c into a .o, .a or .so at your choice and
link it with your application. Refer to the UST documentation for the advantages and disadvantage of each form. To compile the resulting
.c file, you need to add the options "-llttng-ust -I.". Note for C++ support: although an application instrumented with tracepoints can be
compiled with g++, tracepoint probes should be compiled with gcc (only tested with gcc so far).
OPTIONS
This program follow the usual GNU command line syntax with long options starting with two dashes. Below is a summary of the available
options.
-h, --help
Show summary of possible options and commands.
-v, --verbose
Increase verbosity.
-o, --output
Specify the generated file. The type of the generated file depend on the file extension (.h, .c, .o). This option can be specfied
multiple times to generate different file type.
When no output is specified de default files are generated with the same base filename as the template file. The default files are: .h, .c,
.o.
TEMPLATE FILE FORMAT
The template file, which has the usual extension .tp, contains a list of TRACEPOINT_EVENT definitions and other optional definition entries
like TRACEPOINT_LOGLEVEL. (See lttng-ust(3) for the complete list of available definition.)
You write them as you would write them in a C header file. You can add comments with /* */, // and #.
The provider name (the first field of TRACEPOINT_EVENT) must be the same for the whole file.
Example
TRACEPOINT_EVENT(
sample_tracepoint,
message, // Comment
TP_ARGS(char *, text),
/* Next are the fields */
TP_FIELDS(
ctf_string(message, text)
)
)
ENVIRONMENT VARIABLES
When the tool generate an .o file, it will look for the following environment variables
CC Specifer which C compiler to use. If the variable is not specified, the tool will try "cc" and "gcc"
CFLAGS Flags directly passed to the compiler
SEE ALSO
lttng-ust(3), lttng(1)
BUGS
If you encounter any issues or usability problem, please report it on our mailing list <lttng-dev@lists.lttng.org> to help improve this
project.
CREDITS
lttng-gen-tp is distributed under the GNU General Public License version 2. See the file COPYING for details.
A Web site is available at http://lttng.org for more information on the LTTng project.
You can also find our git tree at http://git.lttng.org.
Mailing lists for support and development: <lttng-dev@lists.lttng.org>.
You can find us on IRC server irc.oftc.net (OFTC) in #lttng.
AUTHORS
lttng-gen-tp is written by Yannick Brosseau <yannick.brosseau@gmail.com>.
February 16, 2012 LTTNG-GEN-TP(1)
Check Out this Related Man Page
LTTNG-UST(3) LTTNG-UST(3)
NAME
lttng-ust -- Linux Trace Toolkit Next Generation User-Space Tracer
SYNOPSIS
Link liblttng-ust.so with applications, following this manpage.
DESCRIPTION
LTTng-UST, the Linux Trace Toolkit Next Generation Userspace Tracer, is port of the low-overhead tracing capabilities of the LTTng kernel
tracer to user-space. The library "liblttng-ust" enables tracing of applications and libraries.
USAGE
The simple way to generate the lttng-ust tracepoint probes is to use the lttng-gen-tp(1) tool. See the lttng-gen-tp(1) manpage for explana-
tion.
Here is the way to do it manually, without the lttng-gen-tp(1) helper script, through an example:
CREATION OF TRACEPOINT PROVIDER
To create a tracepoint provider, within a build tree similar to
examples/easy-ust installed with lttng-ust documentation, a
sample_component_provider.h for the general layout. This manpage will
focus on the various types that can be recorded into a trace event:
TRACEPOINT_EVENT(
/*
* provider name, not a variable but a string starting with a
* letter and containing either letters, numbers or underscores.
* Needs to be the same as TRACEPOINT_PROVIDER. Needs to
* follow the namespacing guide-lines in lttng/tracepoint.h:
*
* Must be included before include tracepoint provider
* ex.: project_event
* ex.: project_component_event
*
* Optional company name goes here
* ex.: com_efficios_project_component_event
*
* In this example, "sample" is the project, and "component" is the
* component.
*/
sample_component,
/*
* tracepoint name, same format as sample provider. Does not
* need to be declared before. in this case the name is
* "message"
*/
message,
/*
* TP_ARGS macro contains the arguments passed for the tracepoint
* it is in the following format
* TP_ARGS(type1, name1, type2, name2, ... type10,
name10)
* where there can be from zero to ten elements.
* typeN is the datatype, such as int, struct or double **.
* name is the variable name (in "int myInt" the name would be
* myint)
* TP_ARGS() is valid to mean no arguments
* TP_ARGS(void) is valid too
*/
TP_ARGS(int, anint, int, netint, long *, values,
char *, text, size_t, textlen,
double, doublearg, float, floatarg),
/*
* TP_FIELDS describes how to write the fields of the trace event.
* You can put expressions in the "argument expression" area,
* typically using the input arguments from TP_ARGS.
*/
TP_FIELDS(
/*
* ctf_integer: standard integer field.
* args: (type, field name, argument expression)
*/
ctf_integer(int, intfield, anint)
ctf_integer(long, longfield, anint)
/*
* ctf_integer_hex: integer field printed as hexadecimal.
* args: (type, field name, argument expression)
*/
ctf_integer_hex(int, intfield2, anint)
/*
* ctf_integer_network: integer field in network byte
* order. (_hex: printed as hexadecimal too)
* args: (type, field name, argument expression)
*/
ctf_integer_network(int, netintfield, netint)
ctf_integer_network_hex(int, netintfieldhex, netint)
/*
* ctf_array: a statically-sized array.
* args: (type, field name, argument expression, value)
*/
ctf_array(long, arrfield1, values, 3)
/*
* ctf_array_text: a statically-sized array, printed as
* a string. No need to be terminated by a null
* character.
*/
ctf_array_text(char, arrfield2, text, 10)
/*
* ctf_sequence: a dynamically-sized array.
* args: (type, field name, argument expression,
* type of length expression, length expression)
*/
ctf_sequence(char, seqfield1, text,
size_t, textlen)
/*
* ctf_sequence_text: a dynamically-sized array, printed
* as string. No need to be null-terminated.
*/
ctf_sequence_text(char, seqfield2, text,
size_t, textlen)
/*
* ctf_string: null-terminated string.
* args: (field name, argument expression)
*/
ctf_string(stringfield, text)
/*
* ctf_float: floating-point number.
* args: (type, field name, argument expression)
*/
ctf_float(float, floatfield, floatarg)
ctf_float(double, doublefield, doublearg)
)
)
ASSIGNING LOGLEVEL TO EVENTS
Optionally, a loglevel can be assigned to a TRACEPOINT_EVENT using the
following construct:
TRACEPOINT_LOGLEVEL(< [com_company_]project[_component] >,
< event >, < loglevel_name >)
The first field is the provider name, the second field is the name of
the tracepoint, and the third field is the loglevel name. A
TRACEPOINT_EVENT should be declared prior to the the TRACEPOINT_LOGLEVEL
for a given tracepoint name. The TRACEPOINT_PROVIDER must be already
declared before declaring a TRACEPOINT_LOGLEVEL.
The loglevels go from 0 to 14. Higher numbers imply the most verbosity
(higher event throughput expected.
Loglevels 0 through 6, and loglevel 14, match syslog(3) loglevels
semantic. Loglevels 7 through 13 offer more fine-grained selection of
debug information.
TRACE_EMERG 0
system is unusable
TRACE_ALERT 1
action must be taken immediately
TRACE_CRIT 2
critical conditions
TRACE_ERR 3
error conditions
TRACE_WARNING 4
warning conditions
TRACE_NOTICE 5
normal, but significant, condition
TRACE_INFO 6
informational message
TRACE_DEBUG_SYSTEM 7
debug information with system-level scope (set of programs)
TRACE_DEBUG_PROGRAM 8
debug information with program-level scope (set of processes)
TRACE_DEBUG_PROCESS 9
debug information with process-level scope (set of modules)
TRACE_DEBUG_MODULE 10
debug information with module (executable/library) scope (set of
units)
TRACE_DEBUG_UNIT 11
debug information with compilation unit scope (set of functions)
TRACE_DEBUG_FUNCTION 12
debug information with function-level scope
TRACE_DEBUG_LINE 13
debug information with line-level scope (TRACEPOINT_EVENT default)
TRACE_DEBUG 14
debug-level message (trace_printf default)
See lttng(1) for information on how to use LTTng-UST loglevels.
ADDING TRACEPOINTS TO YOUR CODE
Include the provider header in each C files you plan to instrument,
following the building/linking directives in the next section.
For instance, add within a function:
tracepoint(ust_tests_hello, tptest, i, netint, values,
text, strlen(text), dbl, flt);
As a call to the tracepoint. It will only be activated when requested by
lttng(1) through lttng-sessiond(8).
BUILDING
/LINKING THE TRACEPOINT PROVIDER
There are 2 ways to compile the Tracepoint Provider with the
application: either statically or dynamically. Please follow
carefully:
1.1) Compile the Tracepoint provider with the application, either
directly or through a static library (.a):
- Into exactly one object of your application: define
"TRACEPOINT_DEFINE" and include the tracepoint provider.
- Use "-I." for the compilation unit containing the tracepoint
provider include (e.g. tp.c).
- Link application with "-ldl".
- If building the provider directly into the application,
link the application with "-llttng-ust".
- If building a static library for the provider, link the static
library with "-lllttng-ust".
- Include the tracepoint provider header into all C files using
the provider.
- Example:
tests/hello/ hello.c tp.c ust_tests_hello.h Makefile.example
2) Compile the Tracepoint Provider separately from the application,
using dynamic linking:
- Into exactly one object of your application: define
"TRACEPOINT_DEFINE" _and_ also define
"TRACEPOINT_PROBE_DYNAMIC_LINKAGE", then include the tracepoint
provider header.
- Include the tracepoint provider header into all instrumented C
files that use the provider.
- Compile the tracepoint provider with "-I.".
- Link the tracepoint provider with "-llttng-ust".
- Link application with "-ldl".
- Set a LD_PRELOAD environment to preload the tracepoint provider
shared object before starting the application when tracing is
needed.
- Example:
- tests/demo/ demo.c tp*.c ust_tests_demo*.h demo-trace
- Note about dlopen() usage: due to locking side-effects due to the
way libc lazily resolves Thread-Local Storage (TLS) symbols when a
library is dlopen'd, linking the tracepoint probe or liblttng-ust
with dlopen() is discouraged. They should be linked with the
application using "-llibname" or loaded with LD_PRELOAD.
- Enable instrumentation and control tracing with the "lttng" command
from lttng-tools. See lttng-tools doc/quickstart.txt.
- Note for C++ support: although an application instrumented with
tracepoints can be compiled with g++, tracepoint probes should be
compiled with gcc (only tested with gcc so far).
ENVIRONMENT VARIABLES
LTTNG_UST_DEBUG
Activate liblttng-ust debug output.
LTTNG_UST_REGISTER_TIMEOUT
The environment variable "LTTNG_UST_REGISTER_TIMEOUT" can be used to specify how long the applications should wait for sessiond
"registration done" command before proceeding to execute the main program. The default is 3000ms (3 seconds). The timeout value is
specified in milliseconds. The value 0 means "don't wait". The value -1 means "wait forever". Setting this environment variable to 0
is recommended for applications with time constraints on the process startup time.
SEE ALSO
lttng-gen-tp(1), lttng(1), babeltrace(1), lttng-sessiond(8)
BUGS
No knows bugs at this point.
If you encounter any issues or usability problem, please report it on our mailing list <lttng-dev@lists.lttng.org> to help improve this
project.
CREDITS
liblttng-ust is distributed under the GNU Lesser General Public License version 2.1. The headers are distributed under the MIT license.
See http://lttng.org for more information on the LTTng project.
Mailing list for support and development: <lttng-dev@lists.lttng.org>.
You can find us on IRC server irc.oftc.net (OFTC) in #lttng.
THANKS
Thanks to Ericsson for funding this work, providing real-life use-cases, and testing.
Special thanks to Michel Dagenais and the DORSAL laboratory at Polytechnique de Montreal for the LTTng journey.
AUTHORS
liblttng-ust was originally written by Mathieu Desnoyers, with additional contributions from various other people. It is currently main-
tained by Mathieu Desnoyers <mathieu.desnoyers@efficios.com>.
February 16, 2012 LTTNG-UST(3)