From: David Goulet <dgoulet@efficios.com>
Date: Wed, 5 Feb 2014 16:44:16 +0000 (-0500)
Subject: Man: add JUL DOMAIN section to lttng.1
X-Git-Tag: v2.5.0-rc1~222
X-Git-Url: https://git.lttng.org/?p=lttng-tools.git;a=commitdiff_plain;h=acf476273ab7b7ed368c7dca079b6ade68eaee1a

Man: add JUL DOMAIN section to lttng.1

Signed-off-by: David Goulet <dgoulet@efficios.com>
---

diff --git a/doc/man/lttng.1 b/doc/man/lttng.1
index b85a2f8d8..06337c03a 100644
--- a/doc/man/lttng.1
+++ b/doc/man/lttng.1
@@ -1,4 +1,4 @@
-.TH "LTTNG" "1" "July 18th, 2013" "" ""
+.TH "LTTNG" "1" "February 05th, 2014" "" ""
 
 .SH "NAME"
 lttng \(em LTTng 2.x tracer control command line tool
@@ -27,10 +27,10 @@ kernel and/or instrumented applications (lttng-ust(3)). Aggregating and reading
 those traces is done using the babeltrace(1) text viewer.
 
 We introduce the notion of \fBtracing domains\fP which is essentially a type of
-tracer (kernel or user space for now). In the future, we could see a third
-tracer being for instance an hypervisor. For some commands, you'll need to
-specify on which domain the command operates (-u or -k). For instance, the
-kernel domain must be specified when enabling a kernel event.
+tracer (kernel, user space or JUL for now). In the future, we could see more
+tracer like for instance an hypervisor. For some commands, you'll need to
+specify on which domain the command operates (\-u, \-k or \-j). For instance,
+the kernel domain must be specified when enabling a kernel event.
 
 In order to trace the kernel, the session daemon needs to be running as root.
 LTTng provides the use of a \fBtracing group\fP (default: tracing). Whomever is
@@ -903,6 +903,46 @@ arguments
 .RE
 .PP
 
+.SH "JUL DOMAIN"
+This section explains the JUL domain (\-j, \-\-jul) where JUL stands for Java
+Util Logging. You can use that feature by using the \fBliblttng-ust-jul.so\fP
+from the lttng-ust(3) project.
+
+The LTTng Java Agent uses JNI to link the UST tracer to the Java application
+that uses the agent. Thus, it behaves similarly to the UST domain (\-u). When
+enabling events with the JUL domain, you enable a Logger name that will then be
+mapped to a default UST tracepoint called \fBlttng_jul:jul_event\fP in the
+\fBlttng_jul_channel\fP. Using the lttng-ctl API, any JUL events must use the
+tracepoint event type (same as \-\-tracepoint).
+
+Because of the default immutable channel (\fBlttng_jul_channel\fP), the
+\fBenable-channel\fP command CAN NOT be used with the JUL domain thus not
+having any \-j option.
+
+For JUL event, loglevels are supported with the JUL ABI values. Use \fBlttng
+enable-event \-h\fP to list them. Wildcards are NOT supported except the "*"
+meaning all events (same as \-a).
+
+Exactly like the UST domain, if the Java application has the same UID as you,
+you can trace it. Same goes for the tracing group accessing root applications.
+
+Finally, you can list every Logger name that are available from JUL registered
+applications to the session daemon by using \fBlttng list \-j\fP.
+
+Here is an example on how to use this domain.
+
+.nf
+$ lttng list -j
+[...]
+$ lttng create aSession
+$ lttng enable-event -s aSession -j MyCustomLoggerName
+$ lttng start
+.fi
+
+More information can be found in the lttng-ust documentation, see
+java-util-logging.txt
+.PP
+
 .SH "EXIT VALUES"
 .PP
 On success 0 is returned and a positive value on error. Value of 1 means a command