Commit | Line | Data |
---|---|---|
5e0cbfb0 PP |
1 | --- |
2 | id: tracef | |
86384750 | 3 | since: 2.5 |
5e0cbfb0 PP |
4 | --- |
5 | ||
6 | `tracef()` is a small LTTng-UST API to avoid defining your own | |
7 | tracepoints and tracepoint providers. The signature of `tracef()` is | |
8 | the same as `printf()`'s. | |
9 | ||
10 | The `tracef()` utility function was developed to make user space tracing | |
11 | super simple, albeit with notable disadvantages compared to custom, | |
12 | full-fledged tracepoint providers: | |
13 | ||
14 | * All generated events have the same provider/event names, respectively | |
15 | `lttng-ust-tracef` and `event`. | |
16 | * There's no static type checking. | |
17 | * The only event field you actually get, named `msg`, is a string | |
18 | potentially containing the values you passed to the function | |
19 | using your own format. This also means that you cannot use filtering | |
20 | using a custom expression at runtime because there are no isolated | |
21 | fields. | |
22 | * Since `tracef()` uses C standard library's `vasprintf()` function | |
23 | in the background to format the strings at runtime, its | |
24 | expected performance is lower than using custom tracepoint providers | |
25 | with typed fields, which do not require a conversion to a string. | |
26 | ||
27 | Thus, `tracef()` is useful for quick prototyping and debugging, but | |
28 | should not be considered for any permanent/serious application | |
29 | instrumentation. | |
30 | ||
31 | To use `tracef()`, first include `<lttng/tracef.h>` in the C source file | |
32 | where you need to insert probes: | |
33 | ||
34 | ~~~ c | |
35 | #include <lttng/tracef.h> | |
36 | ~~~ | |
37 | ||
4d46e8c0 PP |
38 | Use `tracef()` like you would use `printf()` in your source code, for |
39 | example: | |
5e0cbfb0 PP |
40 | |
41 | ~~~ c | |
42 | /* ... */ | |
43 | ||
44 | tracef("my message, my integer: %d", my_integer); | |
45 | ||
46 | /* ... */ | |
47 | ~~~ | |
48 | ||
49 | Link your application with `liblttng-ust`: | |
50 | ||
51 | <pre class="term"> | |
52 | gcc -o app app.c <strong>-llttng-ust</strong> | |
53 | </pre> | |
54 | ||
55 | Execute the application as usual: | |
56 | ||
57 | <pre class="term"> | |
58 | ./app | |
59 | </pre> | |
60 | ||
61 | VoilĂ ! Use the `lttng` command line tool to | |
62 | [control tracing](#doc-controlling-tracing). |