From 3fd4924d496600daa7ac8f889e0bd6ee68759de7 Mon Sep 17 00:00:00 2001 From: Philippe Proulx Date: Fri, 4 Sep 2015 00:47:19 -0400 Subject: [PATCH] tracing-your-own-user-application: minor fixes Signed-off-by: Philippe Proulx --- .../tracing-your-own-user-application.md | 105 +++++++++++------- 1 file changed, 62 insertions(+), 43 deletions(-) diff --git a/contents/getting-started/tracing-your-own-user-application.md b/contents/getting-started/tracing-your-own-user-application.md index 9d27585..e75232e 100644 --- a/contents/getting-started/tracing-your-own-user-application.md +++ b/contents/getting-started/tracing-your-own-user-application.md @@ -6,7 +6,7 @@ The previous section helped you create a trace out of Linux kernel events. This section steps you through a simple example showing you how to trace a _Hello world_ program written in C. -Make sure LTTng-tools and LTTng-UST packages +Make sure the LTTng-tools and LTTng-UST packages [are installed](#doc-installing-lttng). Tracing is just like having `printf()` calls at specific locations of @@ -17,37 +17,40 @@ your source code, albeit LTTng is much more faster and flexible than Unlike `printf()`, though, `tracepoint()` does not use a format string to know the types of its arguments: the formats of all tracepoints must be defined before using them. So before even writing our _Hello world_ program, -we need to define the format of our tracepoint. This is done by writing a -**template file**, with a name usually ending with the `.tp` extension (for **t**race**p**oint), -which the `lttng-gen-tp` tool (shipped with LTTng-UST) uses to generate -an object file (along with a `.c` file) and a header to be included in our application source code. +we need to define the format of our tracepoint. This is done by creating a +**tracepoint provider**, which consists of a tracepoint provider header +(`.h` file) and a tracepoint provider definition (`.c` file). -Here's the whole flow: - -
- - - -
- -The template file format is a list of tracepoint definitions -and other optional definition entries which we skip for -this quickstart. Each tracepoint is defined using the +The tracepoint provider header contains some boilerplate as well as a +list of tracepoint definitions and other optional definition entries +which we skip for this quickstart. Each tracepoint is defined using the `TRACEPOINT_EVENT()` macro. For each tracepoint, you must provide: - * a **provider name**, which is the "scope" of this tracepoint (this usually - includes the company and project names) + * a **provider name**, which is the "scope" or namespace of this + tracepoint (this usually includes the company and project names) * a **tracepoint name** - * a **list of arguments** for the eventual `tracepoint()` call, each item being: + * a **list of arguments** for the eventual `tracepoint()` call, each + item being: * the argument C type * the argument name * a **list of fields**, which correspond to the actual fields of the recorded events for this tracepoint -Here's a simple tracepoint definition example with two arguments: an integer -and a string: +Here's an example of a simple tracepoint provider header with two +arguments: an integer and a string: ~~~ c +#undef TRACEPOINT_PROVIDER +#define TRACEPOINT_PROVIDER hello_world + +#undef TRACEPOINT_INCLUDE +#define TRACEPOINT_INCLUDE "./tp.h" + +#if !defined(_HELLO_TP_H) || defined(TRACEPOINT_HEADER_MULTI_READ) +#define _HELLO_TP_H + +#include + TRACEPOINT_EVENT( hello_world, my_first_tracepoint, @@ -60,26 +63,33 @@ TRACEPOINT_EVENT( ctf_integer(int, my_integer_field, my_integer_arg) ) ) + +#endif /* _HELLO_TP_H */ + +#include ~~~ The exact syntax is well explained in the -[C application](#doc-c-application) instrumenting guide of the +[C application](#doc-c-application) instrumentation guide of the [Using LTTng](#doc-using-lttng) chapter, as well as in the LTTng-UST man page. -Save the above snippet as `hello-tp.tp` and run: +Save the above snippet as `hello-tp.h`. -
-lttng-gen-tp hello-tp.tp
-
+Write the tracepoint provider definition as `hello-tp.c`: + +~~~ c +#define TRACEPOINT_CREATE_PROBES +#define TRACEPOINT_DEFINE -The following files are created next to `hello-tp.tp`: +#include "hello-tp.h" +~~~ - * `hello-tp.c` - * `hello-tp.o` - * `hello-tp.h` +Create the tracepoint provider: -`hello-tp.o` is the compiled object file of `hello-tp.c`. +
+gcc -c -I. hello-tp.c
+
Now, by including `hello-tp.h` in your own application, you may use the tracepoint defined above by properly refering to it when calling @@ -89,19 +99,21 @@ tracepoint defined above by properly refering to it when calling #include #include "hello-tp.h" -int main(int argc, char* argv[]) +int main(int argc, char *argv[]) { int x; puts("Hello, World!\nPress Enter to continue..."); - /* The following getchar() call is only placed here for the purpose + /* + * The following getchar() call is only placed here for the purpose * of this demonstration, for pausing the application in order for * you to have time to list its events. It's not needed otherwise. */ getchar(); - /* A tracepoint() call. Arguments, as defined in hello-tp.tp: + /* + * A tracepoint() call. Arguments, as defined in hello-tp.h: * * 1st: provider name (always) * 2nd: tracepoint name (always) @@ -126,19 +138,26 @@ int main(int argc, char* argv[]) } ~~~ -Save this as `hello.c`, next to `hello-tp.tp`. +Save this as `hello.c`, next to `hello-tp.c`. -Notice `hello-tp.h`, the header file generated by `lttng-gen-tp` from -our template file `hello-tp.tp`, is included by `hello.c`. +Notice `hello-tp.h`, the tracepoint provider header, is included +by `hello.c`. You are now ready to compile the application with LTTng-UST support: 
-gcc -o hello hello.c hello-tp.o -llttng-ust -ldl
+gcc -c hello.c
+gcc -o hello hello.o hello-tp.o -llttng-ust -ldl
+Here's the whole build process: + +
+User space tracing's build process +
+ If you followed the -[Tracing the Linux kernel](#doc-tracing-the-linux-kernel) section, the +[Tracing the Linux kernel](#doc-tracing-the-linux-kernel) tutorial, the following steps should look familiar. First, run the application with a few arguments: @@ -166,7 +185,7 @@ under the `./hello` process. Create a tracing session: 
-lttng create my-userspace-session
+lttng create
Enable the `hello_world:my_first_tracepoint` tracepoint: @@ -192,8 +211,8 @@ lttng stop Done! You may use `lttng view` to list the recorded events. This command starts -babeltrace -in the background, if it is installed: +babeltrace +in the background, if it's installed: 
 lttng view
@@ -215,7 +234,7 @@ destroy the generated trace files, leaving them available for further
 analysis:
 
 
-lttng destroy my-userspace-session
+lttng destroy
 

 
 The next section presents other alternatives to view and analyze your
-- 
2.34.1