[verse]
#define *TRACEPOINT_ENUM*('prov_name', 'enum_name', 'mappings')
#define *TRACEPOINT_EVENT*('prov_name', 't_name', 'args', 'fields')
-#define *TRACEPOINT_EVENT_CLASS*('prov_name', 'class_name',
- 'args', 'fields')
-#define *TRACEPOINT_EVENT_INSTANCE*('prov_name', 'class_name',
- 't_name', 'args')
+#define *TRACEPOINT_EVENT_CLASS*('prov_name', 'class_name', 'args', 'fields')
+#define *TRACEPOINT_EVENT_INSTANCE*('prov_name', 'class_name', 't_name', 'args')
#define *TRACEPOINT_LOGLEVEL*('prov_name', 't_name', 'level')
#define *ctf_array*('int_type', 'field_name', 'expr', 'count')
#define *ctf_array_nowrite*('int_type', 'field_name', 'expr', 'count')
+#define *ctf_array_hex*('int_type', 'field_name', 'expr', 'count')
+#define *ctf_array_nowrite_hex*('int_type', 'field_name', 'expr', 'count')
+#define *ctf_array_network*('int_type', 'field_name', 'expr', 'count')
+#define *ctf_array_network_nowrite*('int_type', 'field_name', 'expr', 'count')
+#define *ctf_array_network_hex*('int_type', 'field_name', 'expr', 'count')
+#define *ctf_array_network_nowrite_hex*('int_type', 'field_name', 'expr', 'count')
#define *ctf_array_text*(char, 'field_name', 'expr', 'count')
#define *ctf_array_text_nowrite*(char, 'field_name', 'expr', 'count')
#define *ctf_enum*('prov_name', 'enum_name', 'int_type', 'field_name', 'expr')
-#define *ctf_enum_nowrite*('prov_name', 'enum_name', 'int_type',
- 'field_name', 'expr')
+#define *ctf_enum_nowrite*('prov_name', 'enum_name', 'int_type', 'field_name',
+ 'expr')
#define *ctf_enum_value*('label', 'value')
#define *ctf_enum_range*('label', 'start', 'end')
#define *ctf_float*('float_type', 'field_name', 'expr')
#define *ctf_integer_network_hex*('int_type', 'field_name', 'expr')
#define *ctf_integer_nowrite*('int_type', 'field_name', 'expr')
#define *ctf_sequence*('int_type', 'field_name', 'expr', 'len_type', 'len_expr')
-#define *ctf_sequence_nowrite*('int_type', 'field_name', 'expr',
- 'len_type', 'len_expr')
+#define *ctf_sequence_nowrite*('int_type', 'field_name', 'expr', 'len_type',
+ 'len_expr')
+#define *ctf_sequence_hex*('int_type', 'field_name', 'expr', 'len_type',
+ 'len_expr')
+#define *ctf_sequence_nowrite_hex*('int_type', 'field_name', 'expr', 'len_type',
+ 'len_expr')
+#define *ctf_sequence_network*('int_type', 'field_name', 'expr', 'len_type',
+ 'len_expr')
+#define *ctf_sequence_network_nowrite*('int_type', 'field_name', 'expr',
+ 'len_type', 'len_expr')
+#define *ctf_sequence_network_hex*('int_type', 'field_name', 'expr', 'len_type',
+ 'len_expr')
+#define *ctf_sequence_network_nowrite_hex*('int_type', 'field_name', 'expr',
+ 'len_type', 'len_expr')
#define *ctf_sequence_text*(char, 'field_name', 'expr', 'len_type', 'len_expr')
-#define *ctf_sequence_text_nowrite*(char, 'field_name', 'expr',
- 'len_type', 'len_expr')
+#define *ctf_sequence_text_nowrite*(char, 'field_name', 'expr', 'len_type',
+ 'len_expr')
#define *ctf_string*('field_name', 'expr')
#define *ctf_string_nowrite*('field_name', 'expr')
#define *do_tracepoint*('prov_name', 't_name', ...)
*ctf_string*('field_name', 'expr')
*ctf_string_nowrite*('field_name', 'expr')
-Statically-sized array of integers:
+Statically-sized array of integers (`_hex` versions displayed in
+hexadecimal, `_network` versions in network byte order):
[verse]
*ctf_array*('int_type', 'field_name', 'expr', 'count')
*ctf_array_nowrite*('int_type', 'field_name', 'expr', 'count')
+*ctf_array_hex*('int_type', 'field_name', 'expr', 'count')
+*ctf_array_nowrite_hex*('int_type', 'field_name', 'expr', 'count')
+*ctf_array_network*('int_type', 'field_name', 'expr', 'count')
+*ctf_array_network_nowrite*('int_type', 'field_name', 'expr', 'count')
+*ctf_array_network_hex*('int_type', 'field_name', 'expr', 'count')
+*ctf_array_network_nowrite_hex*('int_type', 'field_name', 'expr', 'count')
Statically-sized array, printed as text; no need to be null-terminated:
*ctf_array_text*(char, 'field_name', 'expr', 'count')
*ctf_array_text_nowrite*(char, 'field_name', 'expr', 'count')
-Dynamically-sized array of integers:
+Dynamically-sized array of integers (`_hex` versions displayed in
+hexadecimal, `_network` versions in network byte order):
[verse]
*ctf_sequence*('int_type', 'field_name', 'expr', 'len_type', 'len_expr')
*ctf_sequence_nowrite*('int_type', 'field_name', 'expr', 'len_type', 'len_expr')
+*ctf_sequence_hex*('int_type', 'field_name', 'expr', 'len_type', 'len_expr')
+*ctf_sequence_nowrite_hex*('int_type', 'field_name', 'expr', 'len_type',
+ 'len_expr')
+*ctf_sequence_network*('int_type', 'field_name', 'expr', 'len_type', 'len_expr')
+*ctf_sequence_network_nowrite*('int_type', 'field_name', 'expr', 'len_type',
+ 'len_expr')
+*ctf_sequence_network_hex*('int_type', 'field_name', 'expr', 'len_type',
+ 'len_expr')
+*ctf_sequence_network_nowrite_hex*('int_type', 'field_name', 'expr',
+ 'len_type', 'len_expr')
Dynamically-sized array, displayed as text; no need to be null-terminated:
The parameters are:
-'int_type'::
- Integer C type. The size of this type determines the size of the
- integer/enumeration field.
-
-'float_type'::
- Float C type (`float` or `double`). The size of this type determines
- the size of the floating point number field.
+'count'::
+ Number of elements in array/sequence. This must be known at
+ compile time.
-'field_name'::
- Event field name (C identifier syntax, :not: a literal string).
+'enum_name'::
+ Name of an enumeration field previously defined with the
+ `TRACEPOINT_ENUM()` macro. See the
+ <<tracepoint-enum,`TRACEPOINT_ENUM()` usage>> section for more
+ information.
'expr'::
C expression resulting in the field's value. This expression can
of a given tracepoint are defined in the `TP_ARGS()` macro (see
the <<creating-tp,Creating a tracepoint provider>> section above).
-'count'::
- Number of elements in array/sequence. This must be known at
- compile time.
+'field_name'::
+ Event field name (C identifier syntax, :not: a literal string).
-'len_type'::
- Unsigned integer C type of sequence's length.
+'float_type'::
+ Float C type (`float` or `double`). The size of this type determines
+ the size of the floating point number field.
+
+'int_type'::
+ Integer C type. The size of this type determines the size of the
+ integer/enumeration field.
'len_expr'::
C expression resulting in the sequence's length. This expression
can use one or more arguments passed to the tracepoint.
+'len_type'::
+ Unsigned integer C type of sequence's length.
+
'prov_name'::
Tracepoint provider name. This must be the same as the tracepoint
provider name used in a previous field definition.
-'enum_name'::
- Name of an enumeration field previously defined with the
- `TRACEPOINT_ENUM()` macro. See the
- <<tracepoint-enum,`TRACEPOINT_ENUM()` usage>> section for more
- information.
-
The `_nowrite` versions omit themselves from the recorded trace, but are
otherwise identical. Their primary purpose is to make some of the
event context available to the event filters without having to commit
Create the tracepoint provider object file:
[role="term"]
---------------
-cc -c -I. tp.c
---------------
+----
+$ cc -c -I. tp.c
+----
NOTE: Although an application instrumented with LTTng-UST tracepoints
can be compiled with a C++ compiler, tracepoint probes should be
tracepoint provider object files, as a static library:
[role="term"]
----------------
-ar rc tp.a tp.o
----------------
+----
+$ ar rc tp.a tp.o
+----
Using a static library does have the advantage of centralising the
tracepoint providers objects so they can be shared between multiple
(`libc` on a BSD system):
[role="term"]
--------------------------------------
-cc -o app tp.o app.o -llttng-ust -ldl
--------------------------------------
+----
+$ cc -o app tp.o app.o -llttng-ust -ldl
+----
[[build-dynamic]]
nloption:-fpic option:
[role="term"]
---------------------
-cc -c -fpic -I. tp.c
---------------------
+----
+$ cc -c -fpic -I. tp.c
+----
It is then linked as a shared library like this:
[role="term"]
--------------------------------------------------------
-cc -shared -Wl,--no-as-needed -o tp.so tp.o -llttng-ust
--------------------------------------------------------
+----
+$ cc -shared -Wl,--no-as-needed -o tp.so tp.o -llttng-ust
+----
This tracepoint provider shared object isn't linked with the user
application: it must be loaded manually. This is why the application is
libdl:
[role="term"]
---------------------------------
-cc -o app app.o tp-define.o -ldl
---------------------------------
+----
+$ cc -o app app.o tp-define.o -ldl
+----
There are two ways to dynamically load the tracepoint provider shared
object:
application with the `LD_PRELOAD` environment variable (see
man:ld.so(8)).
+To use `liblttng-ust` with a daemon application which closes file
+descriptors that were not opened by it, preload the `liblttng-ust-fd.so`
+library before you start the application. Typical use cases include
+daemons closing all file descriptors after man:fork(2), and buggy
+applications doing ``double-closes''.
+
Context information
~~~~~~~~~~~~~~~~~~~
reverse-lookup the source location that caused the event
to be emitted.
-+perf:thread:COUNTER+::
+`perf:thread:COUNTER`::
perf counter named 'COUNTER'. Use `lttng add-context --list` to
list the available perf counters.
+
Only available on IA-32 and x86-64 architectures.
+`perf:thread:raw:rN:NAME`::
+ perf counter with raw ID 'N' and custom name 'NAME'. See
+ man:lttng-add-context(1) for more details.
+
`pthread_id`::
POSIX thread identifier. Can be used on architectures where
`pthread_t` maps nicely to an `unsigned long` type.
`vpid`::
Virtual process ID: process ID as seen from the point of view of
- the process namespace.
+ the current man:pid_namespaces(7).
`vtid`::
Virtual thread ID: thread ID as seen from the point of view of
- the process namespace.
+ the current man:pid_namespaces(7).
+
+The following man:namespaces(7) context fields are supported by LTTng-UST:
+
+`cgroup_ns`::
+ Cgroup root directory namespace: inode number of the current
+ man:cgroup_namespaces(7) in the proc filesystem.
+
+`ipc_ns`::
+ System V IPC, POSIX message queues namespace: inode number of the
+ current man:ipc_namespaces(7) namespace in the proc filesystem.
+
+`mnt_ns`::
+ Mount points namespace: inode number of the current
+ man:mount_namespaces(7) in the proc filesystem.
+
+`net_ns`::
+ Network devices, stacks, ports namespace: inode number of the
+ current man:network_namespaces(7) in the proc filesystem.
+
+`pid_ns`::
+ Process IDs namespace: inode number of the current
+ man:pid_namespaces(7) in the proc filesystem.
+
+`user_ns`::
+ User and group IDs namespace: inode number of the current
+ man:user_namespaces(7) in the proc filesystem.
+
+`uts_ns`::
+ Hostname and NIS domain name namespace: inode number of the
+ current man:uts_namespaces(7) in the proc filesystem.
+
+The following man:credentials(7) context fields are supported by LTTng-UST:
+
+`vuid`::
+ Virtual real user ID: real user ID as seen from the point of view of
+ the current man:user_namespaces(7).
+
+`vgid`::
+ Virtual real group ID: real group ID as seen from the point of view of
+ the current man:user_namespaces(7).
+
+`veuid`::
+ Virtual effective user ID: effective user ID as seen from the point of
+ view of the current man:user_namespaces(7).
+
+`vegid`::
+ Virtual effective group ID: effective group ID as seen from the point of
+ view of the current man:user_namespaces(7).
+
+`vsuid`::
+ Virtual saved set-user ID: saved set-user ID as seen from the point of
+ view of the current man:user_namespaces(7).
+
+`vsgid`::
+ Virtual saved set-group ID: saved set-group ID as seen from the point of
+ view of the current man:user_namespaces(7).
[[state-dump]]
by the tracer.
The following LTTng-UST state dump events exist and must be enabled
-to record application state dumps.
+to record application state dumps. Note that, during the state dump
+phase, LTTng-UST can also emit _shared library load/unload_ events
+(see <<ust-lib,Shared library load/unload tracking>> below).
`lttng_ust_statedump:start`::
Emitted when the state dump begins.
Fields:
+
[options="header"]
-|==================================================================
-| Field name | Description
-| `baddr` | Base address of loaded executable
-| `memsz` | Size of loaded executable in memory
-| `path` | Path to loaded executable file
-| `is_pic` | Whether the executable is
- position-independent code
-|==================================================================
+|===
+|Field name |Description
+
+|`baddr`
+|Base address of loaded executable.
+
+|`memsz`
+|Size of loaded executable in memory.
+
+|`path`
+|Path to loaded executable file.
+
+|`is_pic`
+|Whether or not the executable is position-independent code.
+
+|`has_build_id`
+|Whether or not the executable has a build ID. If this field is 1, you
+can expect that an `lttng_ust_statedump:build_id` event record follows
+this one (not necessarily immediately after).
+
+|`has_debug_link`
+|Whether or not the executable has debug link information. If this field
+is 1, you can expect that an `lttng_ust_statedump:debug_link` event
+record follows this one (not necessarily immediately after).
+|===
`lttng_ust_statedump:build_id`::
Emitted when a build ID is found in a currently loaded shared
Fields:
+
[options="header"]
-|==============================================================
-| Field name | Description
-| `baddr` | Base address of loaded library
-| `build_id` | Build ID
-|==============================================================
+|===
+|Field name |Description
+
+|`baddr`
+|Base address of loaded library.
+
+|`build_id`
+|Build ID.
+|===
`lttng_ust_statedump:debug_link`::
Emitted when debug link information is found in a currently loaded
Fields:
+
[options="header"]
-|==============================================================
-| Field name | Description
-| `baddr` | Base address of loaded library
-| `crc` | Debug link file's CRC
-| `filename` | Debug link file name
-|==============================================================
+|===
+|Field name |Description
+
+|`baddr`
+|Base address of loaded library.
+
+|`crc`
+|Debug link file's CRC.
+
+|`filename`
+|Debug link file name.
+|===
+
+
+[[ust-lib]]
+Shared library load/unload tracking
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The <<state-dump,LTTng-UST state dump>> and the LTTng-UST helper library
+to instrument the dynamic linker (see man:liblttng-ust-dl(3)) can emit
+**shared library load/unload tracking** events.
+
+The following shared library load/unload tracking events exist and must
+be enabled to track the loading and unloading of shared libraries:
+
+`lttng_ust_lib:load`::
+ Emitted when a shared library (shared object) is loaded.
++
+Fields:
++
+[options="header"]
+|===
+|Field name |Description
+
+|`baddr`
+|Base address of loaded library.
+
+|`memsz`
+|Size of loaded library in memory.
+
+|`path`
+|Path to loaded library file.
+
+|`has_build_id`
+|Whether or not the library has a build ID. If this field is 1, you
+can expect that an `lttng_ust_lib:build_id` event record follows
+this one (not necessarily immediately after).
+
+|`has_debug_link`
+|Whether or not the library has debug link information. If this field
+is 1, you can expect that an `lttng_ust_lib:debug_link` event
+record follows this one (not necessarily immediately after).
+|===
+
+`lttng_ust_lib:unload`::
+ Emitted when a shared library (shared object) is unloaded.
++
+Fields:
++
+[options="header"]
+|===
+|Field name |Description
+
+|`baddr`
+|Base address of unloaded library.
+|===
+
+`lttng_ust_lib:build_id`::
+ Emitted when a build ID is found in a loaded shared library (shared
+ object). See
+ https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html[Debugging Information in Separate Files]
+ for more information about build IDs.
++
+Fields:
++
+[options="header"]
+|===
+|Field name |Description
+
+|`baddr`
+|Base address of loaded library.
+
+|`build_id`
+|Build ID.
+|===
+
+`lttng_ust_lib:debug_link`::
+ Emitted when debug link information is found in a loaded
+ shared library (shared object). See
+ https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html[Debugging Information in Separate Files]
+ for more information about debug links.
++
+Fields:
++
+[options="header"]
+|===
+|Field name |Description
+
+|`baddr`
+|Base address of loaded library.
+
+|`crc`
+|Debug link file's CRC.
+
+|`filename`
+|Debug link file name.
+|===
+
+
+Detect if LTTng-UST is loaded
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+To detect if `liblttng-ust` is loaded from an application:
+
+. Define the `lttng_ust_loaded` weak symbol globally:
++
+------------------------------------------------------------------------
+int lttng_ust_loaded __attribute__((weak));
+------------------------------------------------------------------------
++
+This weak symbol is set by the constructor of `liblttng-ust`.
+
+. Test `lttng_ust_loaded` where needed:
++
+------------------------------------------------------------------------
+/* ... */
+
+if (lttng_ust_loaded) {
+ /* LTTng-UST is loaded */
+} else {
+ /* LTTng-UST is NOT loaded */
+}
+
+/* ... */
+------------------------------------------------------------------------
[[example]]
EXAMPLE
-------
NOTE: A few examples are available in the
-https://github.com/lttng/lttng-ust/tree/master/doc/examples[`doc/examples`]
+https://github.com/lttng/lttng-ust/tree/v{lttng_version}/doc/examples[`doc/examples`]
directory of LTTng-UST's source tree.
This example shows all the features documented in the previous
like this:
[role="term"]
--------------------------------------
-cc -c -I. tp.c
-cc -c app.c
-cc -o app tp.o app.o -llttng-ust -ldl
--------------------------------------
+----
+$ cc -c -I. tp.c
+$ cc -c app.c
+$ cc -o app tp.o app.o -llttng-ust -ldl
+----
Using the man:lttng(1) tool, create an LTTng tracing session, enable
all the events of this tracepoint provider, and start tracing:
[role="term"]
-----------------------------------------------
-lttng create my-session
-lttng enable-event --userspace 'my_provider:*'
-lttng start
-----------------------------------------------
+----
+$ lttng create my-session
+$ lttng enable-event --userspace 'my_provider:*'
+$ lttng start
+----
You may also enable specific events:
[role="term"]
-----------------------------------------------------------
-lttng enable-event --userspace my_provider:big_event
-lttng enable-event --userspace my_provider:event_instance2
-----------------------------------------------------------
+----
+$ lttng enable-event --userspace my_provider:big_event
+$ lttng enable-event --userspace my_provider:event_instance2
+----
Run the application:
[role="term"]
---------------------
-./app some arguments
---------------------
+----
+$ ./app some arguments
+----
Stop the current tracing session and inspect the recorded events:
[role="term"]
-----------
-lttng stop
-lttng view
-----------
+----
+$ lttng stop
+$ lttng view
+----
Tracepoint provider header file
are located in a specific directory under `$LTTNG_HOME` (or `$HOME` if
`$LTTNG_HOME` is not set).
+`LTTNG_UST_ALLOW_BLOCKING`::
+ If set, allow the application to retry event tracing when there's
+ no space left for the event record in the sub-buffer, therefore
+ effectively blocking the application until space is made available
+ or the configured timeout is reached.
++
+To allow an application to block during tracing, you also need to
+specify a blocking timeout when you create a channel with the
+nloption:--blocking-timeout option of the man:lttng-enable-channel(1)
+command.
++
+This option can be useful in workloads generating very large trace data
+throughput, where blocking the application is an acceptable trade-off to
+prevent discarding event records.
++
+WARNING: Setting this environment variable may significantly
+affect application timings.
+
`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/master/doc/examples/clock-override[`examples/clock-override`].
+ https://github.com/lttng/lttng-ust/tree/v{lttng_version}/doc/examples/clock-override[`examples/clock-override`].
`LTTNG_UST_DEBUG`::
- Activates `liblttng-ust`'s debug and error output if set to `1`.
+ If set, enable `liblttng-ust`'s debug and error output.
`LTTNG_UST_GETCPU_PLUGIN`::
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/master/doc/examples/getcpu-override[`examples/getcpu-override`].
+ https://github.com/lttng/lttng-ust/tree/v{lttng_version}/doc/examples/getcpu-override[`examples/getcpu-override`].
`LTTNG_UST_REGISTER_TIMEOUT`::
Waiting time for the _registration done_ session daemon command
Default: {lttng_ust_register_timeout}.
`LTTNG_UST_WITHOUT_BADDR_STATEDUMP`::
- Prevents `liblttng-ust` from performing a base address state dump
- (see the <<state-dump,LTTng-UST state dump>> section above) if
- set to `1`.
+ If set, prevents `liblttng-ust` from performing a base address state
+ dump (see the <<state-dump,LTTng-UST state dump>> section above).
include::common-footer.txt[]
projects / lttng-ust.git / blobdiff