X-Git-Url: http://git.lttng.org/?a=blobdiff_plain;f=doc%2Fman%2Flttng-ust.3.txt;h=43bc226565ceaa3b3d268f882c929df86b8911d7;hb=6f97f9c2bbc74605e3de2b05333ecf25fa52d6fc;hp=dda9cec6e55c7fcfcc52384036d8206042005809;hpb=885adac87fb5d9ce7384be7eabe52248ed99fc0f;p=lttng-ust.git diff --git a/doc/man/lttng-ust.3.txt b/doc/man/lttng-ust.3.txt index dda9cec6..43bc2265 100644 --- a/doc/man/lttng-ust.3.txt +++ b/doc/man/lttng-ust.3.txt @@ -758,7 +758,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 @@ -776,19 +776,21 @@ This event has no fields. + This event has no fields. -`lttng_ust_statedump:soinfo`:: - Emitted when information about a currently loaded shared object is - found. +`lttng_ust_statedump:bin_info`:: + Emitted when information about a currently loaded executable or + shared object is found. + Fields: + [options="header"] -|============================================================== +|================================================================== | Field name | Description -| `baddr` | Base address of loaded library -| `memsz` | Size of loaded library in memory -| `sopath` | Path to loaded library file -|============================================================== +| `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 +|================================================================== `lttng_ust_statedump:build_id`:: Emitted when a build ID is found in a currently loaded shared @@ -843,6 +845,39 @@ 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 +---------------------------------------------- + +You may also enable specific events: + +[role="term"] +---------------------------------------------------------- +lttng enable-event --userspace my_provider:big_event +lttng enable-event --userspace my_provider:event_instance2 +---------------------------------------------------------- + +Run the application: + +[role="term"] +-------------------- +./app some arguments +-------------------- + +Stop the current tracing session and inspect the recorded events: + +[role="term"] +---------- +lttng stop +lttng view +---------- + Tracepoint provider header file ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1053,23 +1088,48 @@ int main(int argc, char* argv[]) ENVIRONMENT VARIABLES --------------------- -`LTTNG_UST_DEBUG`:: - Activate `liblttng-ust` debug and error output. - -`LTTNG_UST_REGISTER_TIMEOUT`:: - Specify how long the applications should wait for the - _registration done_ session daemon command before proceeding to - execute the main program (milliseconds). +`LTTNG_HOME`:: + Alternative user's home directory. This variable is useful when the + user running the instrumented application has a non-writable home + directory. + -The value 0 means _do not 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. +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). + +`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. +-- + -Default: 3000. +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_WITHOUT_BADDR_STATEDUMP`:: - Prevent `liblttng-ust` from performing a base address state dump - (see the <> section above). +`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 @@ -1077,11 +1137,38 @@ Default: 3000. 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`]. +`LTTNG_UST_REGISTER_TIMEOUT`:: + Waiting time for the _registration done_ session daemon command + before proceeding to execute the main program (milliseconds). ++ +The value `0` means _do not 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. ++ +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`. include::common-footer.txt[]