Mailing-List: contact commits-help@phoenix.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@phoenix.apache.org
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
Subject: svn commit: r1619499 - in /phoenix: phoenix-docs/src/main/org/h2/
 phoenix-docs/src/main/org/h2/jdbc/ phoenix-docs/src/main/org/h2/jdbcx/
 phoenix-docs/src/main/org/h2/tools/ site/publish/
 site/source/src/site/markdown/
Date: Thu, 21 Aug 2014 17:48:54 -0000
To: commits@phoenix.apache.org
From: jyates@apache.org
Message-Id: <20140821174855.475B623888D2@eris.apache.org>

Author: jyates
Date: Thu Aug 21 17:48:54 2014
New Revision: 1619499

URL: http://svn.apache.org/r1619499
Log:
Updating tracing docs after PHOENIX-1187

Modified:
    phoenix/phoenix-docs/src/main/org/h2/Driver.java
    phoenix/phoenix-docs/src/main/org/h2/jdbc/JdbcCallableStatement.java
    phoenix/phoenix-docs/src/main/org/h2/jdbc/JdbcConnection.java
    phoenix/phoenix-docs/src/main/org/h2/jdbc/JdbcDatabaseMetaData.java
    phoenix/phoenix-docs/src/main/org/h2/jdbc/JdbcResultSet.java
    phoenix/phoenix-docs/src/main/org/h2/jdbc/JdbcStatement.java
    phoenix/phoenix-docs/src/main/org/h2/jdbcx/JdbcConnectionPool.java
    phoenix/phoenix-docs/src/main/org/h2/jdbcx/JdbcDataSource.java
    phoenix/phoenix-docs/src/main/org/h2/tools/SimpleResultSet.java
    phoenix/site/publish/tracing.html
    phoenix/site/source/src/site/markdown/tracing.md

Modified: phoenix/phoenix-docs/src/main/org/h2/Driver.java
URL: http://svn.apache.org/viewvc/phoenix/phoenix-docs/src/main/org/h2/Driver.java?rev=1619499&r1=1619498&r2=1619499&view=diff
==============================================================================
--- phoenix/phoenix-docs/src/main/org/h2/Driver.java (original)
+++ phoenix/phoenix-docs/src/main/org/h2/Driver.java Thu Aug 21 17:48:54 2014
@@ -17,7 +17,7 @@ import org.h2.message.DbException;
 import org.h2.message.TraceSystem;
 import org.h2.upgrade.DbUpgrade;
 
-/*## Java 1.7 ##
+//## Java 1.7 ##
 import java.util.logging.Logger;
 //*/
 
@@ -138,7 +138,7 @@ public class Driver implements java.sql.
     /**
      * [Not supported]
      */
-/*## Java 1.7 ##
+//## Java 1.7 ##
     public Logger getParentLogger() {
         return null;
     }

Modified: phoenix/phoenix-docs/src/main/org/h2/jdbc/JdbcCallableStatement.java
URL: http://svn.apache.org/viewvc/phoenix/phoenix-docs/src/main/org/h2/jdbc/JdbcCallableStatement.java?rev=1619499&r1=1619498&r2=1619499&view=diff
==============================================================================
--- phoenix/phoenix-docs/src/main/org/h2/jdbc/JdbcCallableStatement.java (original)
+++ phoenix/phoenix-docs/src/main/org/h2/jdbc/JdbcCallableStatement.java Thu Aug 21 17:48:54 2014
@@ -1440,7 +1440,7 @@ public class JdbcCallableStatement exten
      * @param parameterIndex the parameter index (1, 2, ...)
      * @param type the class of the returned value
      */
-/*## Java 1.7 ##
+//## Java 1.7 ##
     public <T> T getObject(int parameterIndex, Class<T> type) {
         return null;
     }
@@ -1452,7 +1452,7 @@ public class JdbcCallableStatement exten
      * @param parameterName the parameter name
      * @param type the class of the returned value
      */
-/*## Java 1.7 ##
+//## Java 1.7 ##
     public <T> T getObject(String parameterName, Class<T> type) {
         return null;
     }

Modified: phoenix/phoenix-docs/src/main/org/h2/jdbc/JdbcConnection.java
URL: http://svn.apache.org/viewvc/phoenix/phoenix-docs/src/main/org/h2/jdbc/JdbcConnection.java?rev=1619499&r1=1619498&r2=1619499&view=diff
==============================================================================
--- phoenix/phoenix-docs/src/main/org/h2/jdbc/JdbcConnection.java (original)
+++ phoenix/phoenix-docs/src/main/org/h2/jdbc/JdbcConnection.java Thu Aug 21 17:48:54 2014
@@ -49,7 +49,7 @@ import java.sql.SQLXML;
 import java.sql.SQLClientInfoException;
 //*/
 
-/*## Java 1.7 ##
+//## Java 1.7 ##
 import java.util.concurrent.Executor;
 //*/
 
@@ -1678,7 +1678,7 @@ public class JdbcConnection extends Trac
      *
      * @param schema the schema
      */
-/*## Java 1.7 ##
+//## Java 1.7 ##
     public void setSchema(String schema) {
         // not supported
     }
@@ -1687,7 +1687,7 @@ public class JdbcConnection extends Trac
     /**
      * [Not supported]
      */
-/*## Java 1.7 ##
+//## Java 1.7 ##
     public String getSchema() {
         return null;
     }
@@ -1698,7 +1698,7 @@ public class JdbcConnection extends Trac
      *
      * @param executor the executor used by this method
      */
-/*## Java 1.7 ##
+//## Java 1.7 ##
     public void abort(Executor executor) {
         // not supported
     }
@@ -1710,7 +1710,7 @@ public class JdbcConnection extends Trac
      * @param executor the executor used by this method
      * @param milliseconds the TCP connection timeout
      */
-/*## Java 1.7 ##
+//## Java 1.7 ##
     public void setNetworkTimeout(Executor executor, int milliseconds) {
         // not supported
     }
@@ -1719,7 +1719,7 @@ public class JdbcConnection extends Trac
     /**
      * [Not supported]
      */
-/*## Java 1.7 ##
+//## Java 1.7 ##
     public int getNetworkTimeout() {
         return 0;
     }

Modified: phoenix/phoenix-docs/src/main/org/h2/jdbc/JdbcDatabaseMetaData.java
URL: http://svn.apache.org/viewvc/phoenix/phoenix-docs/src/main/org/h2/jdbc/JdbcDatabaseMetaData.java?rev=1619499&r1=1619498&r2=1619499&view=diff
==============================================================================
--- phoenix/phoenix-docs/src/main/org/h2/jdbc/JdbcDatabaseMetaData.java (original)
+++ phoenix/phoenix-docs/src/main/org/h2/jdbc/JdbcDatabaseMetaData.java Thu Aug 21 17:48:54 2014
@@ -2885,7 +2885,7 @@ public class JdbcDatabaseMetaData extend
     /**
      * [Not supported]
      */
-    /*## Java 1.7 ##
+    //## Java 1.7 ##
     public boolean generatedKeyAlwaysReturned() {
         return true;
     }
@@ -2902,7 +2902,7 @@ public class JdbcDatabaseMetaData extend
      * @param columnNamePattern null (to get all objects) or a column name
      *            (uppercase for unquoted names)
      */
-    /*## Java 1.7 ##
+    //## Java 1.7 ##
     public ResultSet getPseudoColumns(String catalog, String schemaPattern,
             String tableNamePattern, String columnNamePattern) {
         return null;

Modified: phoenix/phoenix-docs/src/main/org/h2/jdbc/JdbcResultSet.java
URL: http://svn.apache.org/viewvc/phoenix/phoenix-docs/src/main/org/h2/jdbc/JdbcResultSet.java?rev=1619499&r1=1619498&r2=1619499&view=diff
==============================================================================
--- phoenix/phoenix-docs/src/main/org/h2/jdbc/JdbcResultSet.java (original)
+++ phoenix/phoenix-docs/src/main/org/h2/jdbc/JdbcResultSet.java Thu Aug 21 17:48:54 2014
@@ -3431,7 +3431,7 @@ public class JdbcResultSet extends Trace
      * @param columnIndex the column index (1, 2, ...)
      * @param type the class of the returned value
      */
-/*## Java 1.7 ##
+//## Java 1.7 ##
     public <T> T getObject(int columnIndex, Class<T> type) {
         return null;
     }
@@ -3443,7 +3443,7 @@ public class JdbcResultSet extends Trace
      * @param columnName the column name
      * @param type the class of the returned value
      */
-/*## Java 1.7 ##
+//## Java 1.7 ##
     public <T> T getObject(String columnName, Class<T> type) {
         return null;
     }

Modified: phoenix/phoenix-docs/src/main/org/h2/jdbc/JdbcStatement.java
URL: http://svn.apache.org/viewvc/phoenix/phoenix-docs/src/main/org/h2/jdbc/JdbcStatement.java?rev=1619499&r1=1619498&r2=1619499&view=diff
==============================================================================
--- phoenix/phoenix-docs/src/main/org/h2/jdbc/JdbcStatement.java (original)
+++ phoenix/phoenix-docs/src/main/org/h2/jdbc/JdbcStatement.java Thu Aug 21 17:48:54 2014
@@ -876,7 +876,7 @@ public class JdbcStatement extends Trace
     /**
      * [Not supported]
      */
-/*## Java 1.7 ##
+//## Java 1.7 ##
     public void closeOnCompletion() {
         // not supported
     }
@@ -885,7 +885,7 @@ public class JdbcStatement extends Trace
     /**
      * [Not supported]
      */
-/*## Java 1.7 ##
+//## Java 1.7 ##
     public boolean isCloseOnCompletion() {
         return true;
     }

Modified: phoenix/phoenix-docs/src/main/org/h2/jdbcx/JdbcConnectionPool.java
URL: http://svn.apache.org/viewvc/phoenix/phoenix-docs/src/main/org/h2/jdbcx/JdbcConnectionPool.java?rev=1619499&r1=1619498&r2=1619499&view=diff
==============================================================================
--- phoenix/phoenix-docs/src/main/org/h2/jdbcx/JdbcConnectionPool.java (original)
+++ phoenix/phoenix-docs/src/main/org/h2/jdbcx/JdbcConnectionPool.java Thu Aug 21 17:48:54 2014
@@ -35,7 +35,7 @@ import org.h2.util.New;
 import org.h2.message.DbException;
 //*/
 
-/*## Java 1.7 ##
+//## Java 1.7 ##
 import java.util.logging.Logger;
 //*/
 
@@ -330,7 +330,7 @@ public class JdbcConnectionPool implemen
     /**
      * [Not supported]
      */
-/*## Java 1.7 ##
+//## Java 1.7 ##
     public Logger getParentLogger() {
         return null;
     }

Modified: phoenix/phoenix-docs/src/main/org/h2/jdbcx/JdbcDataSource.java
URL: http://svn.apache.org/viewvc/phoenix/phoenix-docs/src/main/org/h2/jdbcx/JdbcDataSource.java?rev=1619499&r1=1619498&r2=1619499&view=diff
==============================================================================
--- phoenix/phoenix-docs/src/main/org/h2/jdbcx/JdbcDataSource.java (original)
+++ phoenix/phoenix-docs/src/main/org/h2/jdbcx/JdbcDataSource.java Thu Aug 21 17:48:54 2014
@@ -26,7 +26,7 @@ import org.h2.jdbc.JdbcConnection;
 import org.h2.message.TraceObject;
 import org.h2.util.StringUtils;
 
-/*## Java 1.7 ##
+//## Java 1.7 ##
 import java.util.logging.Logger;
 //*/
 
@@ -381,7 +381,7 @@ public class JdbcDataSource extends Trac
     /**
      * [Not supported]
      */
-/*## Java 1.7 ##
+//## Java 1.7 ##
     public Logger getParentLogger() {
         return null;
     }

Modified: phoenix/phoenix-docs/src/main/org/h2/tools/SimpleResultSet.java
URL: http://svn.apache.org/viewvc/phoenix/phoenix-docs/src/main/org/h2/tools/SimpleResultSet.java?rev=1619499&r1=1619498&r2=1619499&view=diff
==============================================================================
--- phoenix/phoenix-docs/src/main/org/h2/tools/SimpleResultSet.java (original)
+++ phoenix/phoenix-docs/src/main/org/h2/tools/SimpleResultSet.java Thu Aug 21 17:48:54 2014
@@ -853,7 +853,7 @@ public class SimpleResultSet implements 
      * @param columnIndex the column index (1, 2, ...)
      * @param type the class of the returned value
      */
-/*## Java 1.7 ##
+//## Java 1.7 ##
     public <T> T getObject(int columnIndex, Class<T> type) {
         return null;
     }
@@ -865,7 +865,7 @@ public class SimpleResultSet implements 
      * @param columnName the column name
      * @param type the class of the returned value
      */
-/*## Java 1.7 ##
+//## Java 1.7 ##
     public <T> T getObject(String columnName, Class<T> type) {
         return null;
     }

Modified: phoenix/site/publish/tracing.html
URL: http://svn.apache.org/viewvc/phoenix/site/publish/tracing.html?rev=1619499&r1=1619498&r2=1619499&view=diff
==============================================================================
--- phoenix/site/publish/tracing.html (original)
+++ phoenix/site/publish/tracing.html Thu Aug 21 17:48:54 2014
@@ -1,7 +1,7 @@
 
 <!DOCTYPE html>
 <!--
- Generated by Apache Maven Doxia at 2014-08-18
+ Generated by Apache Maven Doxia at 2014-08-21
  Rendered using Reflow Maven Skin 1.1.0 (http://andriusvelykis.github.io/reflow-maven-skin)
 -->
 <html  xml:lang="en" lang="en">
@@ -128,11 +128,37 @@
 <p>We leverage Clouderaâs <a class="externalLink" href="https://github.com/cloudera/htrace">HTrace</a> library to seamlessly integrate with HBaseâs tracing utilities. We then take it a step further by then depositing these metrics into a Hadoop metrics2 sink that writes them into a phoenix table.</p> 
 <p><b>Writing traces to a phoenix table is not supported on Hadoop1</b></p> 
 <div class="section"> 
+ <h2 id="Configuration">Configuration</h2> 
+ <p>In the Phoenix release tarball (phoenix-XXXX.tar.gz) for Hadoop2 there are two files in the bin/ directory:</p> 
+ <ul> 
+  <li>hadoop-metrics2-phoenix.properties</li> 
+  <li>hadoop-metrics2-hbase.properties</li> 
+ </ul> 
+ <p>They contain the properties you need to set on the client and server, respectively, as well as information on how the metrics2 system uses the configuation files.</p> 
+ <p>Put these filse on their respective classpaths and restart the process to pick-up the new configurations.</p> 
+ <div class="section"> 
+  <h3 id="hadoop-metrics2-phoenix.properties">hadoop-metrics2-phoenix.properties</h3> 
+  <p>This file will configure the <a class="externalLink" href="http://hadoop.apache.org/docs/current/api/index.html?org/apache/hadoop/metrics2/package-summary.html">Hadoop Metrics2</a> system for <i>Phoenix clients</i>. By placing the file as-is on the classpath you will use the standard Phoenix metrics sink (which collects the trace information) and writer (which writes the traces to the Phoenix SYSTEM.TRACING_STATS table).</p> 
+  <p>See the properties file for more information on setting your own sinks and writer.</p> 
+ </div> 
+ <div class="section"> 
+  <h3 id="hadoop-metrics2-hbase.properties">hadoop-metrics2-hbase.properties</h3> 
+  <p>HBase already comes with a metrics2 configuration, so the metrics2 configuration included in the phoenix distribution can either replace the existing file (if you donât have any special configurations) or the properties can be copied to your exisiting metrics2 configuration file.</p> 
+  <p>They are essentially the same properties as in the hadoop-metrics2-phoenix.properties but prefixed by âhbaseâ rather than âphoenixâ so they are loaded in the HBase metrics system.</p> 
+ </div> 
+ <div class="section"> 
+  <h3 id="Disabling_Tracing">Disabling Tracing</h3> 
+  <p>======================</p> 
+  <p>You can disable tracing client requests merely by creating a new Connection that doesnât have the tracing property enabled (see below).</p> 
+  <p>However, on the server-side once the metrics sink has been enabled you cannot turn of trace collection and writing unless you <b>remove the Phoenix metrics2 confgiuration and bounce the regionserver</b>. This is enforced by the metrics2 framework as its assumed that you will always want to collect information about the server you are running on.</p> 
+ </div> 
+</div> 
+<div class="section"> 
  <h2 id="Usage">Usage</h2> 
  <p>There are only a couple small things you need to do to enable tracing a given request with Phoenix.</p> 
  <div class="section"> 
   <h3 id="Client_Property">Client Property</h3> 
-  <p>The frequency of tracing is determined by the following client-side HBase configuration property:</p> 
+  <p>The frequency of tracing is determined by the following client-side Phoenix property:</p> 
   <div class="source"> 
    <pre>phoenix.trace.frequency
 </pre> 
@@ -167,16 +193,18 @@ props.setProperty(&quot;phoenix.trace.pr
 Connection conn = DriverManager.getConnection(&quot;jdbc:phoenix:localhost&quot;, props);
 </pre> 
   </div> 
- </div> 
- <div class="section"> 
-  <h3 id="Enabling_TracingMetrics2_Sink">Enabling Tracing/Metrics2 Sink</h3> 
-  <p>This is where the traces are taken from the tracing framework and then deposited into a Phoenix table. Because the traces are transported through the Hadoop metrics2 framework, you need to add the following configs to your hadoop-metrics2.properties (or hadoop-metrics2-phoenix.properties) file on the classpath of both the * phoenix client* and <i>HBase regionservers</i>, and then restart all necessary processes to get them to pick up the configs.</p> 
-  <div class="source"> 
-   <pre># Hadoop2 metrics sink
-phoenix.sink.*.class=org.apache.phoenix.trace.PhoenixMetricsWriter
-# Writer that generically writes to phoenix tables
-phoenix.sink.writer-class=org.apache.phoenix.trace.PhoenixTableMetricsWriter
+  <div class="section"> 
+   <h4 id="hbase-site.xml">hbase-site.xml</h4> 
+   <p>You can also enable tracing via hbase-site.xml. However, only âalwaysâ and âneverâ are currently supported.</p> 
+   <div class="source"> 
+    <pre>&lt;configuration&gt;
+  &lt;property&gt;
+	&lt;name&gt;phoenix.trace.frequency&lt;/name&gt;
+    &lt;value&gt;always&lt;/value&gt;
+  &lt;/property&gt;
+&lt;/configuration&gt;
 </pre> 
+   </div> 
   </div> 
  </div> 
 </div> 

Modified: phoenix/site/source/src/site/markdown/tracing.md
URL: http://svn.apache.org/viewvc/phoenix/site/source/src/site/markdown/tracing.md?rev=1619499&r1=1619498&r2=1619499&view=diff
==============================================================================
--- phoenix/site/source/src/site/markdown/tracing.md (original)
+++ phoenix/site/source/src/site/markdown/tracing.md Thu Aug 21 17:48:54 2014
@@ -6,13 +6,44 @@ We leverage Cloudera's [HTrace](https://
 
 **Writing traces to a phoenix table is not supported on Hadoop1**
 
+## Configuration
+
+In the Phoenix release tarball (phoenix-XXXX.tar.gz) for Hadoop2 there are two files in the bin/ directory:
+
+  * hadoop-metrics2-phoenix.properties
+  * hadoop-metrics2-hbase.properties
+
+They contain the properties you need to set on the client and server, respectively, as well as information on how the metrics2 system uses the configuation files.
+
+Put these filse on their respective classpaths and restart the process to pick-up the new configurations.
+
+### hadoop-metrics2-phoenix.properties
+
+This file will configure the [Hadoop Metrics2](http://hadoop.apache.org/docs/current/api/index.html?org/apache/hadoop/metrics2/package-summary.html) system for *Phoenix clients*. By placing the file as-is on the classpath you will use the standard Phoenix metrics sink (which collects the trace information) and writer (which writes the traces to the Phoenix SYSTEM.TRACING_STATS table).
+
+See the properties file for more information on setting your own sinks and writer.
+
+### hadoop-metrics2-hbase.properties
+
+HBase already comes with a metrics2 configuration, so the metrics2 configuration included in the phoenix distribution can either replace the existing file (if you don't have any special configurations) or the properties can be copied to your exisiting metrics2 configuration file.
+
+They are essentially the same properties as in the hadoop-metrics2-phoenix.properties but prefixed by "hbase" rather than "phoenix" so they are loaded in the HBase metrics system.
+
+### Disabling Tracing
+======================
+
+You can disable tracing client requests merely by creating a new Connection that doesn't have the tracing property enabled (see below).
+
+However, on the server-side once the metrics sink has been enabled you cannot turn of trace collection and writing unless you **remove the Phoenix metrics2 confgiuration and bounce the regionserver**. This is enforced by the metrics2 framework as its assumed that you will always want to collect information about the server you are running on.
+
+
 ## Usage
 
 There are only a couple small things you need to do to enable tracing a given request with Phoenix.
 
 ### Client Property
 
-The frequency of tracing is determined by the following client-side HBase configuration property:
+The frequency of tracing is determined by the following client-side Phoenix property:
 
 ```
 phoenix.trace.frequency
@@ -45,15 +76,17 @@ props.setProperty("phoenix.trace.probabi
 Connection conn = DriverManager.getConnection("jdbc:phoenix:localhost", props);
 ```
 
-### Enabling Tracing/Metrics2 Sink
+#### hbase-site.xml
 
-This is where the traces are taken from the tracing framework and then deposited into a Phoenix table. Because the traces are transported through the Hadoop metrics2 framework, you need to add the following configs to your hadoop-metrics2.properties (or hadoop-metrics2-phoenix.properties) file on the classpath of both the * phoenix client* and *HBase regionservers*, and then restart all necessary processes to get them to pick up the configs.
+You can also enable tracing via hbase-site.xml. However, only "always" and "never" are currently supported.
 
 ```
-# Hadoop2 metrics sink
-phoenix.sink.*.class=org.apache.phoenix.trace.PhoenixMetricsWriter
-# Writer that generically writes to phoenix tables
-phoenix.sink.writer-class=org.apache.phoenix.trace.PhoenixTableMetricsWriter
+<configuration>
+  <property>
+	<name>phoenix.trace.frequency</name>
+    <value>always</value>
+  </property>
+</configuration>
 ```
 
 ## Reading Traces