X-Git-Url: http://git.liburcu.org/?a=blobdiff_plain;f=doc%2Fman%2Flttng-ust.3.txt;h=bf24967231b756d0d58fbec18e79b0fb329d148a;hb=2842c6c82f70ff2c5a996c063cc7d2ef2a06f289;hp=816bebc7232a53f8b1752996c0eab97ae0892b81;hpb=14dd1c6f0cb8124a1399dbdea0f3a3335ae22ca8;p=lttng-ust.git diff --git a/doc/man/lttng-ust.3.txt b/doc/man/lttng-ust.3.txt index 816bebc7..bf249672 100644 --- a/doc/man/lttng-ust.3.txt +++ b/doc/man/lttng-ust.3.txt @@ -23,6 +23,12 @@ SYNOPSIS #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') @@ -38,8 +44,20 @@ SYNOPSIS #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') @@ -250,11 +268,18 @@ Null-terminated string: *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: @@ -262,11 +287,22 @@ 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: @@ -758,7 +794,7 @@ LTTng-UST state dump ~~~~~~~~~~~~~~~~~~~~ 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 @@ -1098,9 +1134,45 @@ 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). +`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). @@ -1111,23 +1183,29 @@ with time constraints on the process startup time. + 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 <> 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[]