[slf4j-dev] svn commit: r1228 - slf4j/trunk/slf4j-site/src/site/pages

ravn at slf4j.org ravn at slf4j.org
Thu Nov 13 00:11:20 CET 2008


Author: ravn
Date: Thu Nov 13 00:11:19 2008
New Revision: 1228

Modified:
   slf4j/trunk/slf4j-site/src/site/pages/extensions.html

Log:
first draft of javaagent documentation

Modified: slf4j/trunk/slf4j-site/src/site/pages/extensions.html
==============================================================================
--- slf4j/trunk/slf4j-site/src/site/pages/extensions.html	(original)
+++ slf4j/trunk/slf4j-site/src/site/pages/extensions.html	Thu Nov 13 00:11:19 2008
@@ -295,7 +295,11 @@
   </root>
 &lt;/configuration>  </p>
 
-   <h2><a name="extended_logger">Extended Logger</a></h2>
+
+
+<!-- .............................................................. -->
+
+   <h2><a name="extended_logger"></a>Extended Logger</h2>
 
    <p>The <a
    href="apidocs/org/slf4j/ext/XLogger.html"><code>XLogger</code></a>
@@ -570,19 +574,29 @@
             at org.apache.maven.surefire.booter.SurefireBooter.runSuitesInProcess(SurefireBooter.java:338)
             at org.apache.maven.surefire.booter.SurefireBooter.main(SurefireBooter.java:997)    
 </p>
-</div>
 
 <h2><a name="javaagent"></a>Adding logging with Java agent</h2>
 
 <p><b>NOTE:  BETA RELEASE, NOT PRODUCTION QUALITY</b>
 </p>
 
+<p>Quickstart for the impatient:
+<ol>
+<li>Use Java 5 or later.
+<li>Download slf4j-ext-X.Y.Z.jar and javassist.jar, and put them both in the same directory.</li>
+<li>Ensure your application is properly configured with slf4j-api-X.Y.Z.jar and a suitable backend.</li>
+<li>Instead of "java ..." use "java --javaagent:#PATH#/slf4j-ext-X.Y.Z.jar=time,verbose,level=info ..."<br/>
+ (replace #PATH# with the path to the jar)
+<li>That's it!
+</ol>
+</p>
+
 <p>
 In some applications logging is used to trace the actual execution of the
 application as opposed to log an occasional event.  One approach is using the <a href="#extended_logger">extended 
-logger</a> to add statements as appropriately, but another is to use a tool which modifies bytecode
+logger</a> to add statements as appropriately, but another is to use a tool which modifies compiled bytecode
 to add these statements!  Many exist, and the one included in slf4j-ext is not intended to compete with these, but
-merely provide a quick way to get very basic trace information from a given application.
+merely provide a quick way to get very basic trace information from a given application.  
 </p>
 
 <p>Java 5 added the Java Instrumentation mechanism, which 
@@ -591,13 +605,104 @@
 and the transformations done on the byte codes depend on the needs at launch time.
 </p>
 
+<p>Given the well-known "Hello World" example:</p>
+
+<p class="source">public class HelloWorld {
+    public static void main(String args[]) {
+        System.out.println("Hello World");
+    }
+}</p>
+
+<p>a typical transformation would be similar to: (imports omitted)</p>
+
+<p class="source">public class LoggingHelloWorld {
+    final static Logger _log = LoggerFactory.getLogger(LoggingHelloWorld.class.getName());
+
+    public static void main(String args[]) {
+        if (_log.isInfoEnabled()) {
+            _log.info("> main(args=" + Arrays.asList(args) + ")");
+        }
+        System.out.println("Hello World");
+        if (_log.isInfoEnabled()) {
+            _log.info("< main()");
+        }
+    }
+}</p>
+
+<p>which in turn produces the following result when run similar to 
+"java LoggingHelloWorld 1 2 3 4":
+</p>
+
+<p class="source">1 [main] INFO LoggingHelloWorld - > main(args=[1, 2, 3, 4])
+Hello World
+1 [main] INFO LoggingHelloWorld - < main()</p>
+
+<p>The same effect could have been had by using this command (with the
+relative path to javassist.jar and slf4j-ext-X.Y.Z.jar being ../jars):</p>
+
+<p class="source">java -javaagent:../jars/slf4j-ext-X.Y.Z.jar HelloWorld 1 2 3 4</p>
 
+<p></p>
 
 
+<h3>How to use</h3>
+<p>The javaagent may take one or more options separated by comma.  The following options
+are currently supported:</p>
+
+<p>
+<dl>
+<dt><b>level</b>=X</dt>
+<dd>The log level to use for the generated log statements. X is one of "info", "debug" or "trace".
+Default is "info".</dd>
+<dt><b>time</b></dt>
+<dd>Print out the current date at program start, and again when the program ends plus the execution time in milliseconds.</dd>
+<dt><b>verbose</b></dt>
+<dd>Print out when a class is processed as part of being loaded</dd>
+<dt><b>ignore</b>=X:Y:...</dt>
+<dd>(Advanced) Provide full list of colon separated prefixes of class names NOT to add logging to.   
+The default list is { "sun/", "java/", "javax/", "org/slf4j/",
+        "ch/qos/logback/", "org/apache/log4j/", "apple/", "com/sun/" }.
+</dd>
+</dl>
+
+<p>Note:  These are not finalized yet, and may change.</p>
+
+<h3>Locations of jar files</h3>
+<p>
+The javassist library is used for the actual byte code manipulation and must
+be available to be able to add any logging statements.  slf4j-ext-X.Y.Z has been
+configured to look for the following:
+
+<ul>
+<li>"javassist-3.4.GA.jar" relatively to slf4j-ext-X.Y.Z as would be if Maven had downloaded both from the repository and slf4j-ext-X.Y.Z.jar was referenced directly in the
+Maven repository in the "-javaagent"-argument.</li>
+<li>"javassist-3.4.GA.jar" in the same directory as slf4j-ext-X.Y.Z</li>
+<li>"javassist.jar" in the same directory as slf4j-ext-X.Y.Z</li>
+</ul>
+
+A warning message is printed if the javassist library was not found by the agent.
+</p>
+
+
+<h3>Misc notes</h3>
+
+<p>
+<ul>
+<li>A java agent does not "see" any classes already loaded by the class loader.</li>
+<li>Any exceptions in the java agent that would normally have been printed, are silently swallowed by the JVM.</li>
+<li>The javaagent does not do any logging itself, and the slf4j backend does not need to be available to the agent. 
+<li>You MUST remember to have slf4j-api-X.Y.Z.jar explicitly provided to the program to be instrumented.  If not, the one
+embedded in the slf4j-ext-X.Y.Z.jar library is used, and these classes cannot see the jars loaded later.  (Empirically determined, reference would be appreciated).
+
+</ul>
+</p>
+
+<p>
 (The agent is an adaption of the java.util.logging version described in 
 <a href="http://today.java.net/pub/a/today/2008/04/24/add-logging-at-class-load-time-with-instrumentation.html"
 >http://today.java.net/pub/a/today/2008/04/24/add-logging-at-class-load-time-with-instrumentation.html</a>)
-
+</p>
+</div>
 </body>
 </html>
 



More information about the slf4j-dev mailing list