From b23ecad223ece1f099068e2f3297bccc7b121496 Mon Sep 17 00:00:00 2001
From: Philippe Proulx <eeppeliteloop@gmail.com>
Date: Fri, 4 Sep 2015 17:48:27 -0400
Subject: [PATCH] Document tracelog() facility

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
---
 .../instrumenting/c-application/tracelog.md   | 61 +++++++++++++++++++
 toc/docs.yml                                  |  2 +
 2 files changed, 63 insertions(+)
 create mode 100644 contents/using-lttng/instrumenting/c-application/tracelog.md

diff --git a/contents/using-lttng/instrumenting/c-application/tracelog.md b/contents/using-lttng/instrumenting/c-application/tracelog.md
new file mode 100644
index 0000000..c99b31b
--- /dev/null
+++ b/contents/using-lttng/instrumenting/c-application/tracelog.md
@@ -0,0 +1,61 @@
+---
+id: tracelog
+since: 2.7
+---
+
+The `tracelog()` API is very similar to [`tracef()`](#doc-tracef). The
+only difference is that it accepts an additional log level parameter.
+
+The goal of `tracelog()` is to ease the migration from logging to
+tracing.
+
+Here's an example:
+
+~~~ c
+#include <lttng/tracelog.h>
+
+void my_function(int my_integer) {
+    /* ... */
+
+    tracelog(TRACE_INFO, "my message, my integer: %d", my_integer);
+
+    /* ... */
+}
+~~~
+
+See [LTTng-UST library reference](#doc-liblttng-ust-tracepoint-loglevel)
+for the list of available log level names.
+
+Link your application with `liblttng-ust`:
+
+<pre class="term">
+gcc -o app app.c <strong>-llttng-ust</strong>
+</pre>
+
+Execute the application as usual:
+
+<pre class="term">
+./app
+</pre>
+
+The events produced by `tracelog()` calls are prefixed with
+`lttng_ust_tracelog:`. To enable `tracelog()` events matching a range
+of log levels, do:
+
+<pre class="term">
+lttng enable-event --userspace 'lttng_ust_tracelog:*' \
+                   --loglevel TRACE_INFO
+</pre>
+
+This enables all `tracelog()` events with a log level at least as important
+as `TRACE_INFO`.
+
+To enable `tracelog()` events matching a specific log level, do:
+
+<pre class="term">
+lttng enable-event --userspace 'lttng_ust_tracelog:*' \
+                   --loglevel-only TRACE_WARNING
+</pre>
+
+See [Enabling and disabling events](#doc-enabling-disabling-events) for
+more options.
diff --git a/toc/docs.yml b/toc/docs.yml
index 39b13c7..291cc97 100644
--- a/toc/docs.yml
+++ b/toc/docs.yml
@@ -124,6 +124,8 @@ cats:
                     title: <span class="reset-text-transform">pkg-config</span>
               - id: tracef
                 title: Using <code>tracef()</code>
+              - id: tracelog
+                title: Using <code>tracelog()</code>
               - id: lttng-ust-environment-variables-compiler-flags
                 title: <span class="reset-text-transform">LTTng</span>-UST environment variables and special compilation flags
           - id: cxx-application
-- 
2.34.1