ZOOKEEPER-1068. Documentation and default config suggest incorrect location for Zookeeper state (Roman Shaposhnik via phunt)

git-svn-id: https://svn.apache.org/repos/asf/zookeeper/trunk@1138100 13f79535-47bb-0310-9956-ffa450edef68

CHANGES.txt

@@ -233,6 +233,9 @@ BUGFIXES:
 
   ZOOKEEPER-1087. ForceSync VM arguement not working when set to "no" (Nate Putnam via breed)
 
+  ZOOKEEPER-1068. Documentation and default config suggest incorrect
+  location for Zookeeper state (Roman Shaposhnik via phunt)
+
 IMPROVEMENTS:
   ZOOKEEPER-724. Improve junit test integration - log harness information 
   (phunt via mahadev)

bin/zkEnv.sh

@@ -24,12 +24,7 @@
 # a sibling of this script's directory
 if [ "x$ZOOCFGDIR" = "x" ]
 then
-    if [ -d "/etc/zookeeper" ]
-    then
-        ZOOCFGDIR="/etc/zookeeper"
-    else
-        ZOOCFGDIR="$ZOOBINDIR/../conf"
-    fi
+    ZOOCFGDIR="$ZOOBINDIR/../conf"
 fi
 
 if [ "x$ZOOCFG" = "x" ]

docs/bookkeeperStarted.html

@@ -273,7 +273,7 @@ document.write("Last Published: " + document.lastModified);
 <p>
 <span class="codefrag computeroutput">
 		java -cp .:./zookeeper-&lt;version&gt;-bookkeeper.jar:./zookeeper-&lt;version&gt;.jar\
-		:../log4j/apache-log4j-1.2.15/log4j-1.2.15.jar -Dlog4j.configuration=log4j.properties\ 
+		:lib/slf4j-api-1.6.1.jar:lib/slf4j-log4j12-1.6.1.jar:lib/log4j-1.2.15.jar -Dlog4j.configuration=log4j.properties\ 
 		org.apache.bookkeeper.proto.BookieServer 3181 127.0.0.1:2181 /path_to_log_device/\
 		/path_to_ledger_device/
 		</span>

docs/zookeeperAdmin.html

@@ -487,7 +487,7 @@ document.write("Last Published: " + document.lastModified);
           
 <pre class="code">
 tickTime=2000
-dataDir=/var/zookeeper/
+dataDir=/var/lib/zookeeper/
 clientPort=2181
 initLimit=5
 syncLimit=2
@@ -528,7 +528,7 @@ server.3=zoo3:2888:3888</pre>
 
           
 <p>
-<span class="codefrag computeroutput">$ java -cp zookeeper.jar:lib/log4j-1.2.15.jar:conf \
+<span class="codefrag computeroutput">$ java -cp zookeeper.jar:lib/slf4j-api-1.6.1.jar:lib/slf4j-log4j12-1.6.1.jar:lib/log4j-1.2.15.jar:conf \
               org.apache.zookeeper.server.quorum.QuorumPeerMain zoo.cfg
           </span>
 </p>
@@ -565,7 +565,7 @@ server.3=zoo3:2888:3888</pre>
 
               
 <p>
-<span class="codefrag computeroutput">$ java -cp zookeeper.jar:src/java/lib/log4j-1.2.15.jar:conf:src/java/lib/jline-0.9.94.jar \
+<span class="codefrag computeroutput">$ java -cp zookeeper.jar:lib/slf4j-api-1.6.1.jar:lib/slf4j-log4j12-1.6.1.jar:lib/log4j-1.2.15.jar:conf:src/java/lib/jline-0.9.94.jar \
       org.apache.zookeeper.ZooKeeperMain -server 127.0.0.1:2181</span>
 </p>
             
@@ -888,7 +888,7 @@ server.3=zoo3:2888:3888</pre>
         in the unlikely event a recent log has become corrupted). This
         can be run as a cron job on the ZooKeeper server machines to
         clean up the logs daily.</p>
-<pre class="code"> java -cp zookeeper.jar:log4j.jar:conf org.apache.zookeeper.server.PurgeTxnLog &lt;dataDir&gt; &lt;snapDir&gt; -n &lt;count&gt;</pre>
+<pre class="code"> java -cp zookeeper.jar:lib/slf4j-api-1.6.1.jar:lib/slf4j-log4j12-1.6.1.jar:lib/log4j-1.2.15.jar:conf org.apache.zookeeper.server.PurgeTxnLog &lt;dataDir&gt; &lt;snapDir&gt; -n &lt;count&gt;</pre>
 <a name="N10244"></a><a name="Debug+Log+Cleanup+%28log4j%29"></a>
 <h4>Debug Log Cleanup (log4j)</h4>
 <p>See the section on <a href="#sc_logging">logging</a> in this document. It is

docs/zookeeperInternals.html

@@ -241,7 +241,7 @@ document.write("Last Published: " + document.lastModified);
 <a href="#sc_rightLevel">Logging at the Right Level</a>
 </li>
 <li>
-<a href="#sc_log4jIdioms">Use of Standard log4j Idioms</a>
+<a href="#sc_slf4jIdioms">Use of Standard slf4j Idioms</a>
 </li>
 </ul>
 </li>
@@ -677,27 +677,32 @@ hierarchy of groups.
 <h2 class="h3">Logging</h2>
 <div class="section">
 <p>
-ZooKeeper uses 
-<a href="http://logging.apache.org/log4j">log4j</a>
-version 1.2 as its logging infrastructure. For information on configuring log4j for
+Zookeeper uses 
+<a href="http://www.slf4j.org/index.html">slf4j</a> as an abstraction layer for logging. 
+<a href="http://logging.apache.org/log4j">log4j</a> in version 1.2 is chosen as the final logging implementation for now.
+For better embedding support, it is planned in the future to leave the decision of choosing the final logging implementation to the end user.
+Therefore, always use the slf4j api to write log statements in the code, but configure log4j for how to log at runtime.
+Note that slf4j has no FATAL level, former messages at FATAL level have been moved to ERROR level. 
+For information on configuring log4j for
 ZooKeeper, see the <a href="zookeeperAdmin.html#sc_logging">Logging</a> section 
 of the <a href="zookeeperAdmin.html">ZooKeeper Administrator's Guide.</a>
 
+
 </p>
-<a name="N1015C"></a><a name="sc_developerGuidelines"></a>
+<a name="N10160"></a><a name="sc_developerGuidelines"></a>
 <h3 class="h4">Developer Guidelines</h3>
-<p>Please follow these guidelines when submitting code. Patch reviewers will look for the following:</p>
-<a name="N10164"></a><a name="sc_rightLevel"></a>
+<p>Please follow the  
+<a href="http://www.slf4j.org/manual.html">slf4j manual</a> when creating log statements within code.
+Also read the
+<a href="http://www.slf4j.org/faq.html#logging_performance">FAQ on performance</a>
+, when creating log statements. Patch reviewers will look for the following:</p>
+<a name="N10170"></a><a name="sc_rightLevel"></a>
 <h4>Logging at the Right Level</h4>
 <p>
-There are <a href="http://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/Level.html#FATAL">6 levels of logging in log4j</a>. 
+There are several levels of logging in slf4j. 
 It's important to pick the right one. In order of higher to lower severity:</p>
 <ol>
    
-<li>
-<p> FATAL level designates very severe error events that will presumably lead the application to abort</p>
-</li>
-   
 <li>
 <p>ERROR level designates error events that might still allow the application to continue running.</p>
 </li>
@@ -711,7 +716,7 @@ It's important to pick the right one. In order of higher to lower severity:</p>
 </li>
    
 <li>
-<p>EBUG Level designates fine-grained informational events that are most useful to debug an application.</p>
+<p>DEBUG Level designates fine-grained informational events that are most useful to debug an application.</p>
 </li>
    
 <li>
@@ -722,34 +727,29 @@ It's important to pick the right one. In order of higher to lower severity:</p>
 <p>
 ZooKeeper is typically run in production such that log messages of INFO level 
 severity and higher (more severe) are output to the log.</p>
-<a name="N1018F"></a><a name="sc_log4jIdioms"></a>
-<h4>Use of Standard log4j Idioms</h4>
+<a name="N10193"></a><a name="sc_slf4jIdioms"></a>
+<h4>Use of Standard slf4j Idioms</h4>
 <p>
 <em>Static Message Logging</em>
 </p>
 <pre class="code">
 LOG.debug("process completed successfully!");
 </pre>
-<p>However when creating a message from a number of components (string 
-concatenation), the log call should be wrapped with a "isXEnabled()" call. this 
-eliminates the string concatenation overhead when debug level logging is not enabled.
+<p>
+However when creating parameterized messages are required, use formatting anchors.
 </p>
 <pre class="code">
-if (LOG.isDebugEnabled()) {
-    LOG.debug("got " + count + " messages in " + time + " minutes");
-}
+LOG.debug("got {} messages in {} minutes",new Object[]{count,time});    
 </pre>
 <p>
 <em>Naming</em>
 </p>
 <p>
-Loggers should be named after the class in which they are used. (See the 
-<a href="http://logging.apache.org/log4j/1.2/faq.html#2.4">log4j faq</a> 
-for reasons why this is a good idea.)
+Loggers should be named after the class in which they are used.
 </p>
 <pre class="code">
 public class Foo {
-    private static final Logger LOG = Logger.getLogger(Foo.class);
+    private static final Logger LOG = LoggerFactory.getLogger(Foo.class);
     ....
     public Foo() {
        LOG.info("constructing Foo");

docs/zookeeperStarted.html

@@ -276,7 +276,7 @@ document.write("Last Published: " + document.lastModified);
       create it in <strong>conf/zoo.cfg</strong>:</p>
 <pre class="code">
 tickTime=2000
-dataDir=/var/zookeeper
+dataDir=/var/lib/zookeeper
 clientPort=2181
 </pre>
 <p>This file can be called anything, but for the sake of this
@@ -535,7 +535,7 @@ numChildren = 0
       few differences. Here is an example:</p>
 <pre class="code">
 tickTime=2000
-dataDir=/var/zookeeper
+dataDir=/var/lib/zookeeper
 clientPort=2181
 initLimit=5
 syncLimit=2

src/docs/src/documentation/content/xdocs/zookeeperAdmin.xml

@@ -164,7 +164,7 @@
 
           <programlisting>
 tickTime=2000
-dataDir=/var/zookeeper/
+dataDir=/var/lib/zookeeper/
 clientPort=2181
 initLimit=5
 syncLimit=2

src/docs/src/documentation/content/xdocs/zookeeperStarted.xml

@@ -89,7 +89,7 @@
 
 <programlisting>
 tickTime=2000
-dataDir=/var/zookeeper
+dataDir=/var/lib/zookeeper
 clientPort=2181
 </programlisting>
 
@@ -346,7 +346,7 @@ numChildren = 0
 
 <programlisting>
 tickTime=2000
-dataDir=/var/zookeeper
+dataDir=/var/lib/zookeeper
 clientPort=2181
 initLimit=5
 syncLimit=2