From: Philippe Proulx Date: Tue, 24 Feb 2015 00:39:22 +0000 (-0500) Subject: Document features of LTTng 2.6 X-Git-Url: https://git.lttng.org./?a=commitdiff_plain;h=c23b8cb13f54163f5090b1e21d5b24fce6cd779f;p=lttng-docs.git Document features of LTTng 2.6 Signed-off-by: Philippe Proulx --- diff --git a/contents/understanding-lttng/core-concepts/domain.md b/contents/understanding-lttng/core-concepts/domain.md index 724af91..b0cb528 100644 --- a/contents/understanding-lttng/core-concepts/domain.md +++ b/contents/understanding-lttng/core-concepts/domain.md @@ -5,11 +5,12 @@ id: domain A tracing _domain_ is the official term the LTTng project uses to designate a tracer category. -There are currently three known domains: +There are currently four known domains: * Linux kernel * user space - * Java Util Logging (JUL) + * `java.util.logging` (JUL) + * log4j Different tracers expose common features in their own interfaces, but, from a user's perspective, you still need to target a specific type of diff --git a/contents/understanding-lttng/plumbing/lttng-consumerd.md b/contents/understanding-lttng/plumbing/lttng-consumerd.md index 3bd76fa..6d99b95 100644 --- a/contents/understanding-lttng/plumbing/lttng-consumerd.md +++ b/contents/understanding-lttng/plumbing/lttng-consumerd.md @@ -33,7 +33,7 @@ collecting kernel trace data. As new tracing domains are added to LTTng, the development community's intent is to minimize the need for additionnal consumer daemon instances -dedicated to them. For instance, the Java Util Logging (JUL) domain +dedicated to them. For instance, the `java.util.logging` (JUL) domain events are in fact mapped to the user space domain, thus tracing this particular domain is handled by existing user space domain consumer daemons. diff --git a/contents/understanding-lttng/plumbing/overview.md b/contents/understanding-lttng/plumbing/overview.md index 3a538f5..69d3101 100644 --- a/contents/understanding-lttng/plumbing/overview.md +++ b/contents/understanding-lttng/plumbing/overview.md @@ -22,8 +22,9 @@ which usable component belongs to which package: and `liblttng-ust-dl`) * user space tracepoint code generator command line tool (`lttng-gen-tp`) - * Java Util Logging tracepoint provider (`liblttng-ust-jul-jni`) - and JAR file (`liblttng-ust-jul.jar`) + * `java.util.logging`/log4j tracepoint providers + (`liblttng-ust-jul-jni` and `liblttng-ust-log4j-jni`) and JAR + file (`liblttng-ust-agent.jar`) * **LTTng-modules**: * LTTng Linux kernel tracer module * tracing ring buffer kernel modules diff --git a/contents/using-lttng/controlling-tracing/enabling-disabling-events.md b/contents/using-lttng/controlling-tracing/enabling-disabling-events.md index fd6a5cd..98828c4 100644 --- a/contents/using-lttng/controlling-tracing/enabling-disabling-events.md +++ b/contents/using-lttng/controlling-tracing/enabling-disabling-events.md @@ -12,7 +12,8 @@ in source code/binary program, logical processor and time capturing some payload) being recorded as trace data. This specific condition is composed of: - 1. A **domain** (kernel, user space or Java Util Logging) (required). + 1. A **domain** (kernel, user space, `java.util.loggin`, or log4j) + (required). 2. One or many **instrumentation points** in source code or binary program (tracepoint name, address, symbol name, function name, logger name, etc.) to be executed (required). @@ -26,10 +27,10 @@ composed of: All conditions are specified using arguments passed to the `enable-event` command of the `lttng` tool. -Condition 1 is specified using either `--kernel/-k` (kernel), -`--userspace/-u` (user space) or `--jul/-j` -(JUL). Exactly one of those -three arguments must be specified. +Condition 1 is specified using either `--kernel`/`-k` (kernel), +`--userspace`/`-u` (user space), `--jul`/`-j` +(JUL), or `--log4j`/`-l` (log4j). +Exactly one of those four arguments must be specified. Condition 2 is specified using one of: @@ -86,6 +87,21 @@ the end of the string when specifying a _tracepoint_. Make sure to use it between single quotes in your favorite shell to avoid undesired shell expansion. +System call events can be enabled individually, too: + +
+lttng enable-event -k --syscall open
+lttng enable-event -k --syscall read
+lttng enable-event -k --syscall fork,chdir,pipe
+
+ +The complete list of available system call events can be +obtained using + +
+lttng list --kernel --syscall
+
+ You can see a list of events (enabled or disabled) using 
diff --git a/contents/using-lttng/controlling-tracing/mi.md b/contents/using-lttng/controlling-tracing/mi.md
new file mode 100644
index 0000000..9557e9b
--- /dev/null
+++ b/contents/using-lttng/controlling-tracing/mi.md
@@ -0,0 +1,25 @@
+---
+id: mi
+---
+
+The `lttng` tool aims at providing a command output as human-readable as
+possible. While this output is easy to parse by a human being, machines
+will have a hard time.
+
+This is why the `lttng` tool provides the general `--mi` option, which
+must specify a machine interface output format. As of the latest
+LTTng stable release, only the `xml` format is supported. A schema
+definition (XSD) is made
+available
+to ease the integration with external tools as much as possible.
+
+The `--mi` option can be used in conjunction with all `lttng` commands.
+Here are some examples:
+
+
+lttng --mi xml create some-session
+lttng --mi xml list some-session
+lttng --mi xml list --kernel
+lttng --mi xml enable-event --kernel --syscall open
+lttng --mi xml start
+

diff --git a/contents/using-lttng/instrumenting/java-application.md b/contents/using-lttng/instrumenting/java-application.md
index 5180980..af51664 100644
--- a/contents/using-lttng/instrumenting/java-application.md
+++ b/contents/using-lttng/instrumenting/java-application.md
@@ -3,29 +3,42 @@ id: java-application
 ---
 
 LTTng-UST provides a _logging_ back-end for Java applications using
-Java Util Logging (JUL). This back-end is called the _LTTng-UST JUL agent_ and is
-responsible for communications with an LTTng session daemon.
+either
+java.util.logging
+(JUL), or
+Apache log4j 1.2.
+This back-end is called the _LTTng-UST Java agent_, and is responsible
+for communications with an LTTng session daemon.
 
-From the user's point of view, once the LTTng-UST JUL agent has been
-initialized, JUL loggers may be created and used as usual. The agent
-adds its own handler to the _root logger_, so that all loggers may
-generate LTTng events with no effort.
+

+

+    Note:The latest stable version of LTTng
+    does not support Log4j 2.
+

+

 
-Common JUL features are supported using the `lttng` tool
+From the user's point of view, once the LTTng-UST Java agent has been
+initialized, JUL and log4j loggers may be created and used as usual.
+The agent adds its own handler to the _root logger_, so that all
+loggers may generate LTTng events with no effort.
+
+Common JUL/log4j features are supported using the `lttng` tool
 (see [Controlling tracing](#doc-controlling-tracing)):
 
   * listing all logger names
   * enabling/disabling events per logger name
-  * JUL log levels
+  * JUL/log4j log levels
 
-Here's an example:
+Here's an example using **`java.util.logging`**:
 
 ~~~ java
 import java.util.logging.Logger;
-import org.lttng.ust.jul.LTTngAgent;
+import org.lttng.ust.agent.LTTngAgent;
 
 public class Test
 {
+    private static final int answer = 42;
+
     public static void main(String[] argv) throws Exception
     {
         // create a logger
@@ -38,7 +51,7 @@ public class Test
         logger.info("some info");
         logger.warning("some warning");
         Thread.sleep(500);
-        logger.finer("finer information...");
+        logger.finer("finer information; the answer is " + answer);
         Thread.sleep(123);
         logger.severe("error!");
 
@@ -48,26 +61,63 @@ public class Test
 }
 ~~~
 
-The LTTng-UST JUL agent Java classes are packaged in a JAR file named
-`liblttng-ust-jul.jar`. It is typically located in
-`/usr/lib/lttng/java`. To compile the snippet above
+Here's the same example, this time using **log4j**:
+
+~~~ java
+import org.apache.log4j.Logger;
+import org.apache.log4j.BasicConfigurator;
+import org.lttng.ust.agent.LTTngAgent;
+
+public class Test
+{
+    private static final int answer = 42;
+
+    public static void main(String[] argv) throws Exception
+    {
+        // create and configure a logger
+        Logger logger = Logger.getLogger(Test.class);
+        BasicConfigurator.configure();
+
+        // call this as soon as possible (before logging)
+        LTTngAgent lttngAgent = LTTngAgent.getLTTngAgent();
+
+        // log at will!
+        logger.info("some info");
+        logger.warn("some warning");
+        Thread.sleep(500);
+        logger.debug("debug information; the answer is " + answer);
+        Thread.sleep(123);
+        logger.error("error!");
+        logger.fatal("fatal error!");
+
+        // not mandatory, but cleaner
+        lttngAgent.dispose();
+    }
+}
+~~~
+
+The LTTng-UST Java agent classes are packaged in a JAR file named
+`liblttng-ust-agent.jar`. It is typically located in
+`/usr/lib/lttng/java`. To compile the snippets above
 (saved as `Test.java`), do:
 
 
-javac -cp /usr/lib/lttng/java/liblttng-ust-jul.jar Test.java
+javac -cp /usr/lib/lttng/java/liblttng-ust-agent.jar:$LOG4JCP Test.java
 

 
-You can run the resulting compiled class:
+where `$LOG4JCP` is the log4j 1.2 JAR file path, if you're using log4j.
+
+You can run the resulting compiled class like this:
 
 
-java -cp /usr/lib/lttng/java/liblttng-ust-jul.jar:. Test
+java -cp /usr/lib/lttng/java/liblttng-ust-agent.jar:$LOG4JCP:. Test
 

 
 

 

     Note:OpenJDK 7
     is used for development and continuous integration, thus this
-    version is directly supported. However, the LTTng-UST JUL agent has
+    version is directly supported. However, the LTTng-UST Java agent has
     also been tested with OpenJDK 6.
 

 

diff --git a/images/export/plumbing.svg b/images/export/plumbing.svg
index f8cca32..85c3c22 100644
--- a/images/export/plumbing.svg
+++ b/images/export/plumbing.svg
@@ -16,7 +16,7 @@
     
     
     
-    
+    
       
     
   
@@ -35,7 +35,7 @@
     
     
     
-    
+    
       
     
   
@@ -54,7 +54,7 @@
     
     
     
-    
+    
       
     
   
@@ -73,12 +73,12 @@
     
     
     
-    
+    
       TP
     
   
-  
-    C/C++ application
+  
+    C/C++ application
   
   
     
@@ -95,7 +95,7 @@
     
     
     
-    
+    
       liblttng-ust
     
   
@@ -115,7 +115,7 @@
     
     
     
-    
+    
       Java application
     
   
@@ -134,7 +134,7 @@
     
     
     
-    
+    
       liblttng-ust
     
   
@@ -154,8 +154,9 @@
     
     
     
-    
-      liblttng-ust-jul-jni
+    
+      liblttng-ust-jul-jni
+      liblttng-ust-log4j-jni
     
   
   
@@ -173,8 +174,8 @@
     
     
     
-    
-      liblttng-ust-jul.jar
+    
+      liblttng-ust-agent.jar
     
   
   
@@ -194,11 +195,11 @@
     
     
     
-    
+    
       
     
   
-  
+  
     Linux kernel
   
   
@@ -216,7 +217,7 @@
     
     
     
-    
+    
       LTTng modules
     
   
@@ -235,7 +236,7 @@
     
     
     
-    
+    
       lttng-sessiond
     
   
@@ -275,7 +276,7 @@
     
     
     
-    
+    
       lttng-consumerd
     
   
@@ -316,7 +317,7 @@
     
     
     
-    
+    
       lttng (CLI)
     
   
@@ -335,7 +336,7 @@
     
     
     
-    
+    
       liblttng-ctl
     
   
@@ -354,10 +355,10 @@
     
     
   
-  
-    Target (monitored) system
+  
+    Target (monitored) system
   
-  
+  
     Remote system
   
   
@@ -375,7 +376,7 @@
     
     
     
-    
+    
       lttng-relayd
     
   
@@ -388,7 +389,7 @@
     
     
     
-    
+    
       CTF
       traces
     
@@ -402,12 +403,12 @@
     
     
     
-    
+    
       CTF
       traces
     
   
-  
+  
     (may be local as well)
   
   
@@ -431,17 +432,17 @@
   
   
     
-    
+    
       TCP
     
   
   
     
-    
+    
       TCP
     
   
-  
+  
     Control
   
   
@@ -449,7 +450,7 @@
     
     
   
-  
+  
     Trace data
   
 
diff --git a/images/src/plumbing b/images/src/plumbing
index d693c9e..9252361 100644
Binary files a/images/src/plumbing and b/images/src/plumbing differ
diff --git a/toc/docs.yml b/toc/docs.yml
index e4193ab..b7c505c 100644
--- a/toc/docs.yml
+++ b/toc/docs.yml
@@ -190,6 +190,8 @@ cats:
             title: Viewing events as they arrive
           - id: taking-a-snapshot
             title: Taking a snapshot
+          - id: mi
+            title: Machine interface
   - id: reference
     title: Reference
     cats: