From c23b8cb13f54163f5090b1e21d5b24fce6cd779f Mon Sep 17 00:00:00 2001 From: Philippe Proulx Date: Mon, 23 Feb 2015 19:39:22 -0500 Subject: [PATCH] Document features of LTTng 2.6 Signed-off-by: Philippe Proulx --- .../core-concepts/domain.md | 5 +- .../plumbing/lttng-consumerd.md | 2 +- .../understanding-lttng/plumbing/overview.md | 5 +- .../enabling-disabling-events.md | 26 +++++- .../using-lttng/controlling-tracing/mi.md | 25 +++++ .../instrumenting/java-application.md | 86 ++++++++++++++---- images/export/plumbing.svg | 63 ++++++------- images/src/plumbing | Bin 3634 -> 3661 bytes toc/docs.yml | 2 + 9 files changed, 155 insertions(+), 59 deletions(-) create mode 100644 contents/using-lttng/controlling-tracing/mi.md 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 d693c9ec15c8863a7d0bcd922165c143484df0c1..9252361b3f31c9c57ebc87c0c27309344d38618c 100644
GIT binary patch
delta 3647
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

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:
-- 
2.34.1