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


Reply via email to