[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
~~~~~~~~~~~~~~~~~~~~
If an application that uses `liblttng-ust` becomes part of a tracing
session, information about its currently loaded shared objects, their
-build IDs, and their debug link informations are emitted as events
+build IDs, and their debug link information are emitted as events
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.
+|===
[[example]]
are located in a specific directory under `$LTTNG_HOME` (or `$HOME` if
`$LTTNG_HOME` is not set).
+`LTTNG_UST_BLOCKING_RETRY_TIMEOUT`::
+ Maximum duration (milliseconds) to retry event tracing when
+ there's no space left for the event record in the sub-buffer.
++
+--
+`0` (default)::
+ Never block the application.
+
+Positive value::
+ Block the application for the specified number of milliseconds. If
+ there's no space left after this duration, discard the event
+ record.
+
+Negative value::
+ Block the application until there's space left for the event record.
+--
++
+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 to a non-zero value 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`].
+
`LTTNG_UST_DEBUG`::
Activates `liblttng-ust`'s debug and error output if set to `1`.
+`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`].
+
`LTTNG_UST_REGISTER_TIMEOUT`::
Waiting time for the _registration done_ session daemon command
before proceeding to execute the main program (milliseconds).
+
Default: {lttng_ust_register_timeout}.
+`LTTNG_UST_BLOCKING_RETRY_TIMEOUT`::
+ Maximum time during which event tracing retry is attempted on buffer
+ full condition (millliseconds). Setting this environment to non-zero
+ value effectively blocks the application on buffer full condition.
+ Setting this environment variable to non-zero values may
+ significantly affect application timings. Setting this to a negative
+ value may block the application indefinitely if there is no consumer
+ emptying the ring buffer. The delay between retry attempts is the
+ minimum between the specified timeout value and 100ms. This option
+ can be useful in workloads generating very large trace data
+ throughput, where blocking the application is an acceptable
+ trade-off to not discard events. _Use with caution_.
++
+The value `0` means _do not retry_. The value `-1` means _retry forever_.
+Value > `0` means a maximum timeout of the given value.
++
+Default: {lttng_ust_blocking_retry_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`.
-`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`].
-
-`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`].
-
include::common-footer.txt[]
projects / lttng-ust.git / blobdiff