+// SPDX-FileCopyrightText: 2016 Philippe Proulx <pproulx@efficios.com>
+// SPDX-License-Identifier: CC-BY-4.0
+//
lttng-ust(3)
============
:object-type: library
#define *lttng_ust_tracepoint*('prov_name', 't_name', ...)
#define *lttng_ust_tracepoint_enabled*('prov_name', 't_name')
-Link with `-llttng-ust -llttng-ust-common -ldl`, following this man page.
+Link with, following this manual page:
+
+* `-llttng-ust -ldl`
+* If you define `_LGPL_SOURCE` before including
+ `<lttng/tracepoint.h>` (directly or indirectly): `-llttng-ust-common`
DESCRIPTION
`lttng_ust_do_tracepoint()` have a `STAP_PROBEV()` call, so if you need
it, you should emit this call yourself.
+Tracing in C/C++ constructors and destructors
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+As of LTTng-UST{nbsp}2.13, tracepoint definitions are implemented using
+compound literals. In the following cases, those compound literals are
+allocated on the heap:
+
+* g++{nbsp}<=={nbsp}4.8 is used as the compiler or,
+* `LTTNG_UST_ALLOCATE_COMPOUND_LITERAL_ON_HEAP` is defined in the C pre-processor flags
+and the application is compiled with a C++ compiler
+
+When the compound literals are heap-allocated, there are some cases in which
+both C-style and C++ constructors and destructors will not be traced.
+
+1. C-style constructors and destructors in statically linked archives
+2. C-style constructors and destructors in the application itself
+3. Some C++-style constructors and destructors in the application and statically linked archives
+
+In the 3rd case above, which C++-style constructors and destructors will not be traced depends
+on the initialization order within each translation unit and across the entire program when
+all translation units are linked together.
[[build-static]]
Statically linking the tracepoint provider
provider's API changes).
Then, link your application with this object file (or with the static
-library containing it) and with `liblttng-ust`, `liblttng-ust-common`,
-and `libdl` (`libc` on a BSD system):
+library containing it) and with `liblttng-ust` and `libdl` (`libc` on a
+BSD system):
[role="term"]
----
-$ cc -o app tp.o app.o -llttng-ust -llttng-ust-common -ldl
+$ cc -o app tp.o app.o -llttng-ust -ldl
----
[role="term"]
----
-$ cc -shared -Wl,--no-as-needed -o tp.so tp.o -llttng-ust \
- -llttng-ust-common
+$ cc -shared -Wl,--no-as-needed -o tp.so tp.o -llttng-ust
----
This tracepoint provider shared object isn't linked with the user
[[example]]
EXAMPLE
-------
+
NOTE: A few examples are available in the
-https://github.com/lttng/lttng-ust/tree/v{lttng_version}/doc/examples[`doc/examples`]
+https://github.com/lttng/lttng-ust/tree/stable-{lttng_version}/doc/examples[`doc/examples`]
directory of LTTng-UST's source tree.
This example shows all the features documented in the previous
----
$ cc -c -I. tp.c
$ cc -c app.c
-$ cc -o app tp.o app.o -llttng-ust -llttng-ust-common -ldl
+$ cc -o app tp.o app.o -llttng-ust -ldl
----
Using the man:lttng(1) tool, create an LTTng tracing session, enable
lttng_ust_field_array(int, array_field, array_arg, 7)
lttng_ust_field_array_text(char, array_text_field,
array_arg, 5)
- lttng_ust_field_sequence(int, seq_field, array_arg, int,
+ lttng_ust_field_sequence(int, seq_field, array_arg, unsigned int,
my_integer_arg / 10)
lttng_ust_field_sequence_text(char, seq_text_field,
- array_arg, int,
+ array_arg, unsigned int,
my_integer_arg / 5)
lttng_ust_field_enum(my_provider, my_enum, int,
enum_field, array_arg[1])
ENVIRONMENT VARIABLES
---------------------
+`LTTNG_UST_APP_PATH`::
+ Path under which unix sockets used for the communication between
+ the application (tracee) instrumented with `liblttng-ust` and the
+ LTTng session and consumer daemons (part of the LTTng-tools project)
+ are located. When `$LTTNG_UST_APP_PATH` is specified, only this path
+ is considered for connecting to a session daemon. The
+ `$LTTNG_UST_APP_PATH` target directory must exist and be accessible
+ by the user before the application is executed for tracing to work.
+ Setting this environment variable disables connection to root and
+ per-user session daemons.
+
`LTTNG_HOME`::
Alternative user's home directory. This variable is useful when the
user running the instrumented application has a non-writable home
- directory.
-+
-Unix sockets used for the communication between `liblttng-ust` and the
-LTTng session and consumer daemons (part of the LTTng-tools project)
-are located in a specific directory under `$LTTNG_HOME` (or `$HOME` if
-`$LTTNG_HOME` is not set).
+ directory. This path is where unix sockets for communication with
+ the per-user session daemon are located.
`LTTNG_UST_ALLOW_BLOCKING`::
If set, allow the application to retry event tracing when there's
WARNING: Setting this environment variable may significantly
affect application timings.
+`LTTNG_UST_ABORT_ON_CRITICAL`::
+ If set, abort the instrumented application on a critical error message.
+
`LTTNG_UST_CLOCK_PLUGIN`::
Path to the shared object which acts as the clock override plugin.
An example of such a plugin can be found in the LTTng-UST
documentation under
- https://github.com/lttng/lttng-ust/tree/v{lttng_version}/doc/examples/clock-override[`examples/clock-override`].
+ https://github.com/lttng/lttng-ust/tree/stable-{lttng_version}/doc/examples/clock-override[`examples/clock-override`].
`LTTNG_UST_DEBUG`::
If set, enable `liblttng-ust`'s debug and error output.
Path to the shared object which acts as the `getcpu()` override
plugin. An example of such a plugin can be found in the LTTng-UST
documentation under
- https://github.com/lttng/lttng-ust/tree/v{lttng_version}/doc/examples/getcpu-override[`examples/getcpu-override`].
+ https://github.com/lttng/lttng-ust/tree/stable-{lttng_version}/doc/examples/getcpu-override[`examples/getcpu-override`].
+
+`LTTNG_UST_MAP_POPULATE_POLICY`::
++
+--
+If set, override the policy used to populate shared memory pages
+within the application. The expected values are:
+
+`none`:::
+ Do not pre-populate any pages, take minor faults on first access
+ while tracing.
+
+`cpu_possible`:::
+ Pre-populate pages for all possible CPUs in the system, as
+ listed by `/sys/devices/system/cpu/possible`.
+--
++
+Default: `none`. If the policy is unknown, use the default.
`LTTNG_UST_REGISTER_TIMEOUT`::
Waiting time for the _registration done_ session daemon command
projects / lttng-ust.git / blobdiff