X-Git-Url: https://git.lttng.org/?a=blobdiff_plain;f=doc%2Fman%2Flttng-ust.3.txt;h=ff0e14f75ca6b86002c979ecbb2d86c228f884fd;hb=2b4444ce6a9fa02ae46a67085c17aef55dc85941;hp=2fddbdc5e8a12ddc30d03f7242756282a793080d;hpb=4ddbd0b790be981d023f344a83e67a8746fa3688;p=lttng-ust.git diff --git a/doc/man/lttng-ust.3.txt b/doc/man/lttng-ust.3.txt index 2fddbdc5..ff0e14f7 100644 --- a/doc/man/lttng-ust.3.txt +++ b/doc/man/lttng-ust.3.txt @@ -753,6 +753,7 @@ Only available on IA-32 and x86-64 architectures. the process namespace. +[[state-dump]] LTTng-UST state dump ~~~~~~~~~~~~~~~~~~~~ If an application that uses `liblttng-ust` becomes part of a tracing @@ -775,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 @@ -832,7 +835,53 @@ This example shows all the features documented in the previous sections. The <> method is chosen here to link the application with the tracepoint provider. -Let's start with the tracepoint provider header file (`tp.h`): +You can compile the source files and link them together statically +like this: + +[role="term"] +------------------------------------- +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 +---------------------------------------------- + +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 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +`tp.h`: ------------------------------------------------------------------------ #undef TRACEPOINT_PROVIDER @@ -953,7 +1002,10 @@ TRACEPOINT_EVENT_INSTANCE( #include ------------------------------------------------------------------------ -The tracepoint provider source file looks like this (`tp.c`): + +Tracepoint provider source file +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +`tp.c`: ------------------------------------------------------------------------ #define TRACEPOINT_CREATE_PROBES @@ -962,7 +1014,10 @@ The tracepoint provider source file looks like this (`tp.c`): #include "tp.h" ------------------------------------------------------------------------ -The included `app.h`, where the application structure resides, is: + +Application header file +~~~~~~~~~~~~~~~~~~~~~~~ +`app.h`: ------------------------------------------------------------------------ #ifndef _APP_H @@ -977,7 +1032,10 @@ struct app_struct { #endif /* _APP_H */ ------------------------------------------------------------------------ -Finally, the application itself, `app.c`, using the defined tracepoints: + +Application source file +~~~~~~~~~~~~~~~~~~~~~~~ +`app.c`: ------------------------------------------------------------------------ #include @@ -1027,15 +1085,38 @@ int main(int argc, char* argv[]) } ------------------------------------------------------------------------ -Here are the steps to compile the source files and link them together -statically: -[role="term"] -------------------------------------- -cc -c -I. tp.c -cc -c app.c -cc -o app tp.o app.o -llttng-ust -ldl -------------------------------------- +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). ++ +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_WITHOUT_BADDR_STATEDUMP`:: + Prevent `liblttng-ust` from performing a base address state dump + (see the <> section above). + +`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[]