DESCRIPTION
-----------
-The LTTng-UST `tracelog()` and `vtracelog()` API allows you to trace
-your application with the help of simple man:printf(3)-like and
-man:vprintf(3)-like macros, with an additional parameter for the desired
-log level.
+The `tracelog()` and `vtracelog()` macros are part of version{nbsp}0 of
+the LTTng-UST API (see the ``Compatibility with previous APIs'' section
+of man:lttng-ust(3)).
-The 'fmt' argument is passed directly as the 'fmt' parameter of
-man:vasprintf(3), as well as:
-
-For `tracelog()`::
- The optional parameters following 'fmt'.
-
-For `vtracelog()`::
- The 'ap' parameter as the 'ap' parameter of man:vasprintf(3)
- (`va_list` type).
-
-The purpose of `tracelog()` and `vtracelog()` is to ease the migration
-from logging to tracing.
-
-The available values for the 'level' parameter are:
-
-include::log-levels.txt[]
-
-To use `tracelog()` or `vtracelog()`, include `<lttng/tracelog.h>` where
-you need it, and link your application with `liblttng-ust`. See the
-<<example,EXAMPLE>> section below for a complete usage example.
-
-Once your application is instrumented with `tracelog()` and/or
-`vtracelog()` calls and ready to run, use man:lttng-enable-event(1) to
-enable the `lttng_ust_tracelog:*` event. You can isolate specific log
-levels with the nloption:--loglevel and nloption:--loglevel-only options
-of this command.
-
-The `tracelog()` and `vtracelog()` events contain the following fields:
-
-[options="header"]
-|===
-|Field name |Description
-
-|`line`
-|Line in source file where `tracelog()` was called.
-
-|`file`
-|Source file from which `tracelog()` was called.
-
-|`func`
-|Function name from which `tracelog()` was called.
-
-|`msg`
-|Formatted string output.
-|===
-
-If you do not need to attach a specific log level to a
-`tracelog()`/`vtracelog()` call, use man:tracef(3) instead.
-
-See also the <<limitations,LIMITATIONS>> section below for important
-limitations to consider when using `tracelog()` or `vtracelog()`.
-
-
-[[example]]
-EXAMPLE
--------
-Here's a usage example of `tracelog()`:
-
--------------------------------------------------------------------
-#include <stdlib.h>
-#include <lttng/tracelog.h>
-
-int main(int argc, char *argv[])
-{
- int i;
-
- if (argc < 2) {
- tracelog(TRACE_CRIT, "Not enough arguments: %d", argc);
- return EXIT_FAILURE;
- }
-
- tracelog(TRACE_INFO, "Starting app with %d arguments", argc);
-
- for (i = 0; i < argc; i++) {
- tracelog(TRACE_DEBUG, "Argument %d: %s", i, argv[i]);
- }
-
- tracelog(TRACE_INFO, "Exiting app");
-
- return EXIT_SUCCESS;
-}
--------------------------------------------------------------------
-
-This C source file, saved as `app.c`, can be compiled into a program
-like this:
-
-[role="term"]
-----
-$ cc -o app app.c -llttng-ust -llttng-ust-common
-----
-
-You can create an LTTng tracing session, enable all the `tracelog()`
-events, and start the created tracing session like this:
-
-[role="term"]
-----
-$ lttng create my-session
-$ lttng enable-event --userspace 'lttng_ust_tracelog:*'
-$ lttng start
-----
-
-Or you can enable `tracelog()` events matching a log level at least
-as severe as a given log level:
-
-[role="term"]
-----
-$ lttng enable-event --userspace 'lttng_ust_tracelog:*' \
- --loglevel=TRACE_INFO
-----
-
-Next, start the program to be traced:
-
-[role="term"]
-----
-$ ./app a few arguments passed to this application
-----
-
-Finally, stop the tracing session, and inspect the recorded events:
-
-[role="term"]
-----
-$ lttng stop
-$ lttng view
-----
-
-
-[[limitations]]
-LIMITATIONS
------------
-:macro-name: tracelog
-
-include::tracef-tracelog-limitations.txt[]
+Prefer using man:lttng_ust_tracelog(3) and man:lttng_ust_vtracelog(3)
+which are part of version{nbsp}1 of the API and have the `lttng_ust_`
+namespace.
include::common-footer.txt[]
SEE ALSO
--------
-man:tracef(3),
-man:vtracef(3),
-man:lttng-ust(3),
-man:lttng(1),
-man:printf(3)
+man:lttng_ust_tracelog(3),
+man:lttng_ust_vtracelog(3)
projects / lttng-ust.git / blobdiff