http://git-wip-us.apache.org/repos/asf/hbase/blob/e80b3092/src/main/docbkx/shell.xml ---------------------------------------------------------------------- diff --git a/src/main/docbkx/shell.xml b/src/main/docbkx/shell.xml deleted file mode 100644 index a400d8d..0000000 --- a/src/main/docbkx/shell.xml +++ /dev/null @@ -1,386 +0,0 @@ -<?xml version="1.0"?> -<chapter - xml:id="shell" - version="5.0" - xmlns="http://docbook.org/ns/docbook"; - xmlns:xlink="http://www.w3.org/1999/xlink"; - xmlns:xi="http://www.w3.org/2001/XInclude"; - xmlns:svg="http://www.w3.org/2000/svg"; - xmlns:m="http://www.w3.org/1998/Math/MathML"; - xmlns:html="http://www.w3.org/1999/xhtml"; - xmlns:db="http://docbook.org/ns/docbook";> - <!-- -/** - * Licensed to the Apache Software Foundation (ASF) under one - * or more contributor license agreements. See the NOTICE file - * distributed with this work for additional information - * regarding copyright ownership. The ASF licenses this file - * to you under the Apache License, Version 2.0 (the - * "License"); you may not use this file except in compliance - * with the License. You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ ---> - <title>The Apache HBase Shell</title> - - <para> The Apache HBase Shell is <link - xlink:href="http://jruby.org";>(J)Ruby</link>'s IRB with some HBase particular commands - added. Anything you can do in IRB, you should be able to do in the HBase Shell.</para> - <para>To run the HBase shell, do as follows:</para> - <programlisting>$ ./bin/hbase shell</programlisting> - <para>Type <command>help</command> and then <command><RETURN></command> to see a listing - of shell commands and options. Browse at least the paragraphs at the end of the help - emission for the gist of how variables and command arguments are entered into the HBase - shell; in particular note how table names, rows, and columns, etc., must be quoted.</para> - <para>See <xref - linkend="shell_exercises" /> for example basic shell operation. </para> - <para>Here is a nicely formatted listing of <link - xlink:href="http://learnhbase.wordpress.com/2013/03/02/hbase-shell-commands/";>all shell - commands</link> by Rajeshbabu Chintaguntla. </para> - - <section - xml:id="scripting"> - <title>Scripting with Ruby</title> - <para>For examples scripting Apache HBase, look in the HBase <filename>bin</filename> - directory. Look at the files that end in <filename>*.rb</filename>. To run one of these - files, do as follows:</para> - <programlisting>$ ./bin/hbase org.jruby.Main PATH_TO_SCRIPT</programlisting> - </section> - - <section> - <title>Running the Shell in Non-Interactive Mode</title> - <para>A new non-interactive mode has been added to the HBase Shell (<link - xlink:href="https://issues.apache.org/jira/browse/HBASE-11658";>HBASE-11658)</link>. - Non-interactive mode captures the exit status (success or failure) of HBase Shell - commands and passes that status back to the command interpreter. If you use the normal - interactive mode, the HBase Shell will only ever return its own exit status, which will - nearly always be <literal>0</literal> for success.</para> - <para>To invoke non-interactive mode, pass the <option>-n</option> or - <option>--non-interactive</option> option to HBase Shell.</para> - </section> - - <section xml:id="hbase.shell.noninteractive"> - <title>HBase Shell in OS Scripts</title> - <para>You can use the HBase shell from within operating system script interpreters like the - Bash shell which is the default command interpreter for most Linux and UNIX - distributions. The following guidelines use Bash syntax, but could be adjusted to work - with C-style shells such as csh or tcsh, and could probably be modified to work with the - Microsoft Windows script interpreter as well. Submissions are welcome.</para> - <note> - <para>Spawning HBase Shell commands in this way is slow, so keep that in mind when you - are deciding when combining HBase operations with the operating system command line - is appropriate.</para> - </note> - <example> - <title>Passing Commands to the HBase Shell</title> - <para>You can pass commands to the HBase Shell in non-interactive mode (see <xref - linkend="hbasee.shell.noninteractive"/>) using the <command>echo</command> - command and the <literal>|</literal> (pipe) operator. Be sure to escape characters - in the HBase commands which would otherwise be interpreted by the shell. Some - debug-level output has been truncated from the example below.</para> - <screen>$ <userinput>echo "describe 'test1'" | ./hbase shell -n</userinput> - <computeroutput> -Version 0.98.3-hadoop2, rd5e65a9144e315bb0a964e7730871af32f5018d5, Sat May 31 19:56:09 PDT 2014 - -describe 'test1' - -DESCRIPTION ENABLED - 'test1', {NAME => 'cf', DATA_BLOCK_ENCODING => 'NON true - E', BLOOMFILTER => 'ROW', REPLICATION_SCOPE => '0', - VERSIONS => '1', COMPRESSION => 'NONE', MIN_VERSIO - NS => '0', TTL => 'FOREVER', KEEP_DELETED_CELLS => - 'false', BLOCKSIZE => '65536', IN_MEMORY => 'false' - , BLOCKCACHE => 'true'} -1 row(s) in 3.2410 seconds - </computeroutput> - </screen> - <para>To suppress all output, echo it to <filename>/dev/null:</filename></para> - <screen>$ <userinput>echo "describe 'test'" | ./hbase shell -n > /dev/null 2>&1</userinput></screen> - </example> - <example> - <title>Checking the Result of a Scripted Command</title> - <para>Since scripts are not designed to be run interactively, you need a way to check - whether your command failed or succeeded. The HBase shell uses the standard - convention of returning a value of <literal>0</literal> for successful commands, and - some non-zero value for failed commands. Bash stores a command's return value in a - special environment variable called <varname>$?</varname>. Because that variable is - overwritten each time the shell runs any command, you should store the result in a - different, script-defined variable.</para> - <para>This is a naive script that shows one way to store the return value and make a - decision based upon it.</para> - <programlisting language="bourne"> -#!/bin/bash - -echo "describe 'test'" | ./hbase shell -n > /dev/null 2>&1 -status=$? -echo "The status was " $status -if ($status == 0); then - echo "The command succeeded" -else - echo "The command may have failed." -fi -return $status - </programlisting> - </example> - <section> - <title>Checking for Success or Failure In Scripts</title> - <para>Getting an exit code of 0 means that the command you scripted definitely - succeeded. However, getting a non-zero exit code does not necessarily mean the - command failed. The command could have succeeded, but the client lost connectivity, - or some other event obscured its success. This is because RPC commands are - stateless. The only way to be sure of the status of an operation is to check. For - instance, if your script creates a table, but returns a non-zero exit value, you - should check whether the table was actually created before trying again to create - it.</para> - </section> - </section> - - <section> - <title>Read HBase Shell Commands from a Command File</title> - <para>You can enter HBase Shell commands into a text file, one command per line, and pass - that file to the HBase Shell.</para> - <example> - <title>Example Command File</title> - <screen> -create 'test', 'cf' -list 'test' -put 'test', 'row1', 'cf:a', 'value1' -put 'test', 'row2', 'cf:b', 'value2' -put 'test', 'row3', 'cf:c', 'value3' -put 'test', 'row4', 'cf:d', 'value4' -scan 'test' -get 'test', 'row1' -disable 'test' -enable 'test' - </screen> - </example> - <example> - <title>Directing HBase Shell to Execute the Commands</title> - <para>Pass the path to the command file as the only argument to the <command>hbase - shell</command> command. Each command is executed and its output is shown. If - you do not include the <command>exit</command> command in your script, you are - returned to the HBase shell prompt. There is no way to programmatically check each - individual command for success or failure. Also, though you see the output for each - command, the commands themselves are not echoed to the screen so it can be difficult - to line up the command with its output.</para> - <screen> -$ <userinput>./hbase shell ./sample_commands.txt</userinput> -<computeroutput>0 row(s) in 3.4170 seconds - -TABLE -test -1 row(s) in 0.0590 seconds - -0 row(s) in 0.1540 seconds - -0 row(s) in 0.0080 seconds - -0 row(s) in 0.0060 seconds - -0 row(s) in 0.0060 seconds - -ROW COLUMN+CELL - row1 column=cf:a, timestamp=1407130286968, value=value1 - row2 column=cf:b, timestamp=1407130286997, value=value2 - row3 column=cf:c, timestamp=1407130287007, value=value3 - row4 column=cf:d, timestamp=1407130287015, value=value4 -4 row(s) in 0.0420 seconds - -COLUMN CELL - cf:a timestamp=1407130286968, value=value1 -1 row(s) in 0.0110 seconds - -0 row(s) in 1.5630 seconds - -0 row(s) in 0.4360 seconds</computeroutput> - </screen> - </example> - </section> - <section> - <title>Passing VM Options to the Shell</title> - <para>You can pass VM options to the HBase Shell using the <code>HBASE_SHELL_OPTS</code> - environment variable. You can set this in your environment, for instance by editing - <filename>~/.bashrc</filename>, or set it as part of the command to launch HBase - Shell. The following example sets several garbage-collection-related variables, just for - the lifetime of the VM running the HBase Shell. The command should be run all on a - single line, but is broken by the <literal>\</literal> character, for - readability.</para> - <screen language="bourne"> -$ <userinput>HBASE_SHELL_OPTS="-verbose:gc -XX:+PrintGCApplicationStoppedTime -XX:+PrintGCDateStamps \ - -XX:+PrintGCDetails -Xloggc:$HBASE_HOME/logs/gc-hbase.log" ./bin/hbase shell</userinput> - </screen> - </section> - <section - xml:id="shell_tricks"> - <title>Shell Tricks</title> - <section - xml:id="table_variables"> - <title>Table variables</title> - - <para> HBase 0.95 adds shell commands that provide a jruby-style object-oriented - references for tables. Previously all of the shell commands that act upon a table - have a procedural style that always took the name of the table as an argument. HBase - 0.95 introduces the ability to assign a table to a jruby variable. The table - reference can be used to perform data read write operations such as puts, scans, and - gets well as admin functionality such as disabling, dropping, describing tables. </para> - - <para> For example, previously you would always specify a table name:</para> - <screen> -hbase(main):000:0> create âtâ, âfâ -0 row(s) in 1.0970 seconds -hbase(main):001:0> put 't', 'rold', 'f', 'v' -0 row(s) in 0.0080 seconds - -hbase(main):002:0> scan 't' -ROW COLUMN+CELL - rold column=f:, timestamp=1378473207660, value=v -1 row(s) in 0.0130 seconds - -hbase(main):003:0> describe 't' -DESCRIPTION ENABLED - 't', {NAME => 'f', DATA_BLOCK_ENCODING => 'NONE', BLOOMFILTER => 'ROW', REPLICATION_ true - SCOPE => '0', VERSIONS => '1', COMPRESSION => 'NONE', MIN_VERSIONS => '0', TTL => '2 - 147483647', KEEP_DELETED_CELLS => 'false', BLOCKSIZE => '65536', IN_MEMORY => 'false - ', BLOCKCACHE => 'true'} -1 row(s) in 1.4430 seconds - -hbase(main):004:0> disable 't' -0 row(s) in 14.8700 seconds - -hbase(main):005:0> drop 't' -0 row(s) in 23.1670 seconds - -hbase(main):006:0> - </screen> - - <para> Now you can assign the table to a variable and use the results in jruby shell - code.</para> - <screen> -hbase(main):007 > t = create 't', 'f' -0 row(s) in 1.0970 seconds - -=> Hbase::Table - t -hbase(main):008 > t.put 'r', 'f', 'v' -0 row(s) in 0.0640 seconds -hbase(main):009 > t.scan -ROW COLUMN+CELL - r column=f:, timestamp=1331865816290, value=v -1 row(s) in 0.0110 seconds -hbase(main):010:0> t.describe -DESCRIPTION ENABLED - 't', {NAME => 'f', DATA_BLOCK_ENCODING => 'NONE', BLOOMFILTER => 'ROW', REPLICATION_ true - SCOPE => '0', VERSIONS => '1', COMPRESSION => 'NONE', MIN_VERSIONS => '0', TTL => '2 - 147483647', KEEP_DELETED_CELLS => 'false', BLOCKSIZE => '65536', IN_MEMORY => 'false - ', BLOCKCACHE => 'true'} -1 row(s) in 0.0210 seconds -hbase(main):038:0> t.disable -0 row(s) in 6.2350 seconds -hbase(main):039:0> t.drop -0 row(s) in 0.2340 seconds - </screen> - - <para> If the table has already been created, you can assign a Table to a variable by - using the get_table method:</para> - <screen> -hbase(main):011 > create 't','f' -0 row(s) in 1.2500 seconds - -=> Hbase::Table - t -hbase(main):012:0> tab = get_table 't' -0 row(s) in 0.0010 seconds - -=> Hbase::Table - t -hbase(main):013:0> tab.put âr1â ,âfâ, âvâ -0 row(s) in 0.0100 seconds -hbase(main):014:0> tab.scan -ROW COLUMN+CELL - r1 column=f:, timestamp=1378473876949, value=v -1 row(s) in 0.0240 seconds -hbase(main):015:0> - </screen> - - <para> The list functionality has also been extended so that it returns a list of table - names as strings. You can then use jruby to script table operations based on these - names. The list_snapshots command also acts similarly.</para> - <screen> -hbase(main):016 > tables = list(ât.*â) -TABLE -t -1 row(s) in 0.1040 seconds - -=> #<#<Class:0x7677ce29>:0x21d377a4> -hbase(main):017:0> tables.map { |t| disable t ; drop t} -0 row(s) in 2.2510 seconds - -=> [nil] -hbase(main):018:0> - </screen> - </section> - - <section> - <title><filename>irbrc</filename></title> - <para>Create an <filename>.irbrc</filename> file for yourself in your home directory. - Add customizations. A useful one is command history so commands are save across - Shell invocations:</para> - <screen> -$ more .irbrc -require 'irb/ext/save-history' -IRB.conf[:SAVE_HISTORY] = 100 -IRB.conf[:HISTORY_FILE] = "#{ENV['HOME']}/.irb-save-history"</screen> - <para>See the <application>ruby</application> documentation of - <filename>.irbrc</filename> to learn about other possible configurations. - </para> - </section> - <section> - <title>LOG data to timestamp</title> - <para> To convert the date '08/08/16 20:56:29' from an hbase log into a timestamp, - do:</para> - <screen> -hbase(main):021:0> import java.text.SimpleDateFormat -hbase(main):022:0> import java.text.ParsePosition -hbase(main):023:0> SimpleDateFormat.new("yy/MM/dd HH:mm:ss").parse("08/08/16 20:56:29", ParsePosition.new(0)).getTime() => 1218920189000</screen> - <para> To go the other direction:</para> - <screen> -hbase(main):021:0> import java.util.Date -hbase(main):022:0> Date.new(1218920189000).toString() => "Sat Aug 16 20:56:29 UTC 2008"</screen> - <para> To output in a format that is exactly like that of the HBase log format will take - a little messing with <link - xlink:href="http://download.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html";>SimpleDateFormat</link>. - </para> - </section> - <section> - <title>Debug</title> - <section> - <title>Shell debug switch</title> - <para>You can set a debug switch in the shell to see more output -- e.g. more of the - stack trace on exception -- when you run a command:</para> - <programlisting>hbase> debug <RETURN></programlisting> - </section> - <section> - <title>DEBUG log level</title> - <para>To enable DEBUG level logging in the shell, launch it with the - <command>-d</command> option.</para> - <programlisting>$ ./bin/hbase shell -d</programlisting> - </section> - </section> - <section> - <title>Commands</title> - <section> - <title>count</title> - <para>Count command returns the number of rows in a table. It's quite fast when - configured with the right CACHE - <programlisting>hbase> count '<tablename>', CACHE => 1000</programlisting> - The above count fetches 1000 rows at a time. Set CACHE lower if your rows are - big. Default is to fetch one row at a time. </para> - </section> - </section> - - </section> -</chapter>
http://git-wip-us.apache.org/repos/asf/hbase/blob/e80b3092/src/main/docbkx/sql.xml ---------------------------------------------------------------------- diff --git a/src/main/docbkx/sql.xml b/src/main/docbkx/sql.xml deleted file mode 100644 index 40f43d6..0000000 --- a/src/main/docbkx/sql.xml +++ /dev/null @@ -1,40 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<appendix - xml:id="sql" - version="5.0" - xmlns="http://docbook.org/ns/docbook"; - xmlns:xlink="http://www.w3.org/1999/xlink"; - xmlns:xi="http://www.w3.org/2001/XInclude"; - xmlns:svg="http://www.w3.org/2000/svg"; - xmlns:m="http://www.w3.org/1998/Math/MathML"; - xmlns:html="http://www.w3.org/1999/xhtml"; - xmlns:db="http://docbook.org/ns/docbook";> - <!--/** - * Licensed to the Apache Software Foundation (ASF) under one - * or more contributor license agreements. See the NOTICE file - * distributed with this work for additional information - * regarding copyright ownership. The ASF licenses this file - * to you under the Apache License, Version 2.0 (the - * "License"); you may not use this file except in compliance - * with the License. You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ ---> - <title>SQL over HBase</title> - <section xml:id="phoenix"> - <title>Apache Phoenix</title> - <para><link xlink:href="http://phoenix.apache.org";>Apache Phoenix</link></para> - </section> - <section xml:id="trafodion"> - <title>Trafodion</title> - <para><link xlink:href="https://wiki.trafodion.org/";>Trafodion: Transactional SQL-on-HBase</link></para> - </section> - -</appendix> http://git-wip-us.apache.org/repos/asf/hbase/blob/e80b3092/src/main/docbkx/thrift_filter_language.xml ---------------------------------------------------------------------- diff --git a/src/main/docbkx/thrift_filter_language.xml b/src/main/docbkx/thrift_filter_language.xml deleted file mode 100644 index 74da600..0000000 --- a/src/main/docbkx/thrift_filter_language.xml +++ /dev/null @@ -1,757 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<chapter version="5.0" xml:id="thrift" - xmlns="http://docbook.org/ns/docbook"; - xmlns:xlink="http://www.w3.org/1999/xlink"; - xmlns:xi="http://www.w3.org/2001/XInclude"; - xmlns:svg="http://www.w3.org/2000/svg"; - xmlns:m="http://www.w3.org/1998/Math/MathML"; - xmlns:html="http://www.w3.org/1999/xhtml"; - xmlns:db="http://docbook.org/ns/docbook";> -<!-- -/** - * Licensed to the Apache Software Foundation (ASF) under one - * or more contributor license agreements. See the NOTICE file - * distributed with this work for additional information - * regarding copyright ownership. The ASF licenses this file - * to you under the Apache License, Version 2.0 (the - * "License"); you may not use this file except in compliance - * with the License. You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ ---> - - <title>Thrift API and Filter Language</title> - <para>Apache <link xlink:href="http://thrift.apache.org/";>Thrift</link> is a cross-platform, - cross-language development framework. HBase includes a Thrift API and filter language. The - Thrift API relies on client and server processes. Documentation about the HBase Thrift API - is located at <link xlink:href="http://wiki.apache.org/hadoop/Hbase/ThriftApi"/>. </para> - <para>You can configure Thrift for secure authentication at the server and client side, by - following the procedures in <xref linkend="security.client.thrift"/> and <xref - linkend="security.gateway.thrift"/>. </para> - <para>The rest of this chapter discusses the filter language provided by the Thrift API.</para> - <section - xml:id="thrift.filter-language"> - <title>Filter Language</title> - <para - xml:id="use-case">Thrift Filter Language was introduced in APache HBase 0.92. It allows - you to perform server-side filtering when accessing HBase over Thrift or in the HBase - shell. You can find out more about shell integration by using the <code>scan help</code> - command in the shell.</para> - <para>You specify a filter as a string, which is parsed on the server to construct the - filter.</para> - - <section - xml:id="general-syntax"> - <title>General Filter String Syntax</title> - <para>A simple filter expression is expressed as a string:</para> - <screen>âFilterName (argument, argument,... , argument)â</screen> - <para>Keep the following syntax guidelines in mind.</para> - <itemizedlist> - <listitem> - <para>Specify the name of the filter followed by the comma-separated argument - list in parentheses.</para> - </listitem> - <listitem> - <para>If the argument represents a string, it should be enclosed in single - quotes (<literal>'</literal>).</para> - </listitem> - <listitem> - <para>Arguments which represent a boolean, an integer, or a comparison operator - (such as <, >, or !=), should not be enclosed in quotes</para> - </listitem> - <listitem> - <para>The filter name must be a single word. All ASCII characters are allowed - except for whitespace, single quotes and parentheses.</para> - </listitem> - <listitem> - <para>The filterâs arguments can contain any ASCII character. If single quotes - are present in the argument, they must be escaped by an additional preceding - single quote.</para> - </listitem> - </itemizedlist> - </section> - - <section - xml:id="compound-filters-and-operators"> - <title>Compound Filters and Operators</title> - <variablelist> - <title>Binary Operators</title> - <varlistentry> - <term><code>AND</code></term> - <listitem><para>If the <code>AND</code> operator is used, the key-vallue - must satisfy both the filters.</para></listitem> - </varlistentry> - <varlistentry> - <term><code>OR</code></term> - <listitem><para>If the <code>OR</code> operator is used, the key-value - must satisfy at least one of the filters.</para></listitem> - </varlistentry> - </variablelist> - - <variablelist> - <title>Unary Operators</title> - <varlistentry> - <term><code>SKIP</code></term> - <listitem><para>For a particular row, if any of the key-values fail the - filter condition, the entire row is skipped.</para></listitem> - </varlistentry> - <varlistentry> - <term><code>WHILE</code></term> - <listitem><para>For a particular row, key-values will be emitted until a - key-value is reached t hat fails the filter condition.</para></listitem> - </varlistentry> - </variablelist> - - <example> - <title>Compound Operators</title> - <para>You can combine multiple operators to create a hierarchy of filters, such as - the following example:</para> - <programlisting>(Filter1 AND Filter2) OR (Filter3 AND Filter4)</programlisting> - </example> - </section> - - <section - xml:id="order-of-evaluation"> - <title>Order of Evaluation</title> - <orderedlist> - <listitem><para>Parentheses have the highest precedence.</para></listitem> - <listitem><para>The unary operators <code>SKIP</code> and <code>WHILE</code> are next, and have the same - precedence.</para></listitem> - <listitem><para>The binary operators follow. <code>AND</code> has highest - precedence, followed by <code>OR</code>.</para></listitem> - </orderedlist> - <example> - <title>Precedence Example</title> - <programlisting><userinput>Filter1 AND Filter2 OR Filter</userinput> -is evaluated as -<userinput>(Filter1 AND Filter2) OR Filter3</userinput></programlisting> - <programlisting><userinput>Filter1 AND SKIP Filter2 OR Filter3</userinput> -is evaluated as -<userinput>(Filter1 AND (SKIP Filter2)) OR Filter3</userinput></programlisting> - - </example> - <para>You can use parentheses to explicitly control the order of evaluation.</para> - </section> - - <section - xml:id="compare-operator"> - <title>Compare Operator</title> - <para>The following compare operators are provided:</para> - <orderedlist> - <listitem> - <para>LESS (<)</para> - </listitem> - <listitem> - <para>LESS_OR_EQUAL (<=)</para> - </listitem> - <listitem> - <para>EQUAL (=)</para> - </listitem> - <listitem> - <para>NOT_EQUAL (!=)</para> - </listitem> - <listitem> - <para>GREATER_OR_EQUAL (>=)</para> - </listitem> - <listitem> - <para>GREATER (>)</para> - </listitem> - <listitem> - <para>NO_OP (no operation)</para> - </listitem> - </orderedlist> - <para>The client should use the symbols (<, <=, =, !=, >, >=) to express compare - operators.</para> - </section> - - <section - xml:id="comparator"> - <title>Comparator</title> - <para>A comparator can be any of the following:</para> - <orderedlist> - <listitem> - <para><emphasis - role="bold">BinaryComparator</emphasis> - This lexicographically - compares against the specified byte array using Bytes.compareTo(byte[], - byte[])</para> - </listitem> - <listitem> - <para><emphasis - role="bold">BinaryPrefixComparator</emphasis> - This lexicographically - compares against a specified byte array. It only compares up to the length - of this byte array.</para> - </listitem> - <listitem> - <para><emphasis - role="bold">RegexStringComparator</emphasis> - This compares against the - specified byte array using the given regular expression. Only EQUAL and - NOT_EQUAL comparisons are valid with this comparator</para> - </listitem> - <listitem> - <para><emphasis - role="bold">SubStringComparator</emphasis> - This tests if the given - substring appears in a specified byte array. The comparison is case - insensitive. Only EQUAL and NOT_EQUAL comparisons are valid with this - comparator</para> - </listitem> - </orderedlist> - <para>The general syntax of a comparator is:<code> - ComparatorType:ComparatorValue</code></para> - <para>The ComparatorType for the various comparators is as follows:</para> - <orderedlist> - <listitem> - <para><emphasis - role="bold">BinaryComparator</emphasis> - binary</para> - </listitem> - <listitem> - <para><emphasis - role="bold">BinaryPrefixComparator</emphasis> - binaryprefix</para> - </listitem> - <listitem> - <para><emphasis - role="bold">RegexStringComparator</emphasis> - regexstring</para> - </listitem> - <listitem> - <para><emphasis - role="bold">SubStringComparator</emphasis> - substring</para> - </listitem> - </orderedlist> - <para>The ComparatorValue can be any value.</para> - <example> - <title>Example 1</title> - <para><code> >, 'binary:abc' </code>will match everything that is - lexicographically greater than "abc" </para> - </example> - <example> - <title>Example 2</title> - <para><code> =, 'binaryprefix:abc' </code>will match everything whose first 3 - characters are lexicographically equal to "abc"</para> - </example> - <example> - <title>Example 3</title> - <para><code> !=, 'regexstring:ab*yz' </code>will match everything that doesn't - begin with "ab" and ends with "yz"</para> - </example> - <example> - <title>Example 4</title> - <para><code> =, 'substring:abc123' </code>will match everything that begins - with the substring "abc123"</para> - </example> - </section> - - <section - xml:id="examplePHPClientProgram"> - <title>Example PHP Client Program that uses the Filter Language</title> - <programlisting language="PHP" role="PHP"><![CDATA[ -<? $_SERVER['PHP_ROOT'] = realpath(dirname(__FILE__).'/..'); - require_once $_SERVER['PHP_ROOT'].'/flib/__flib.php'; - flib_init(FLIB_CONTEXT_SCRIPT); - require_module('storage/hbase'); - $hbase = new HBase('<server_name_running_thrift_server>', <port on which thrift server is running>); - $hbase->open(); - $client = $hbase->getClient(); - $result = $client->scannerOpenWithFilterString('table_name', "(PrefixFilter ('row2') AND (QualifierFilter (>=, 'binary:xyz'))) AND (TimestampsFilter ( 123, 456))"); - $to_print = $client->scannerGetList($result,1); - while ($to_print) { - print_r($to_print); - $to_print = $client->scannerGetList($result,1); - } - $client->scannerClose($result); -?> - ]]></programlisting> - </section> - - <section - xml:id="example-filter-strings"> - <title>Example Filter Strings</title> - <para> - <itemizedlist> - <listitem> - <para><code>âPrefixFilter (âRowâ) AND PageFilter (1) AND FirstKeyOnlyFilter - ()â</code> will return all key-value pairs that match the following - conditions:</para> - <orderedlist> - <listitem> - <para>The row containing the key-value should have prefix âRowâ - </para> - </listitem> - <listitem> - <para>The key-value must be located in the first row of the table - </para> - </listitem> - <listitem> - <para>The key-value pair must be the first key-value in the row - </para> - </listitem> - </orderedlist> - </listitem> - </itemizedlist> - </para> - - <orderedlist> - <listitem> - <itemizedlist> - <listitem> - <para><code>â(RowFilter (=, âbinary:Row 1â) AND TimeStampsFilter (74689, - 89734)) OR ColumnRangeFilter (âabcâ, true, âxyzâ, - false))â</code> will return all key-value pairs that match both - the following conditions:</para> - <itemizedlist> - <listitem> - <para>The key-value is in a row having row key âRow 1â </para> - </listitem> - <listitem> - <para>The key-value must have a timestamp of either 74689 or - 89734.</para> - </listitem> - <listitem> - <para>Or it must match the following condition:</para> - <itemizedlist> - <listitem> - <para>The key-value pair must be in a column that is - lexicographically >= abc and < xyz </para> - </listitem> - </itemizedlist> - </listitem> - </itemizedlist> - </listitem> - </itemizedlist> - </listitem> - </orderedlist> - - <para> - <itemizedlist> - <listitem> - <para><code>âSKIP ValueFilter (0)â</code> will skip the entire row if any of - the values in the row is not 0</para> - </listitem> - </itemizedlist> - </para> - </section> - - <section - xml:id="IndividualFilterSyntax"> - <title>Individual Filter Syntax</title> - <variablelist> - <varlistentry> - <term>KeyOnlyFilter</term> - <listitem> - <para>This filter doesnât take any arguments. It returns only the key - component of each key-value.</para> - <itemizedlist> - <title>Syntax</title> - <listitem> - <programlisting language="java">KeyOnlyFilter ()</programlisting> - </listitem> - </itemizedlist> - <itemizedlist> - <title>Example</title> - <listitem> - <programlisting language="java">KeyOnlyFilter ()"</programlisting> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - <varlistentry> - <term>FirstKeyOnlyFilter</term> - <listitem> - <para>This filter doesnât take any arguments. It returns only the first - key-value from each row.</para> - - <itemizedlist> - <title>Syntax</title> - <listitem> - <programlisting language="java">FirstKeyOnlyFilter ()</programlisting> - </listitem> - </itemizedlist> - <itemizedlist> - <title>Example</title> - <listitem> - <programlisting language="java">FirstKeyOnlyFilter ()</programlisting> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - <varlistentry> - <term>PrefixFilter</term> - <listitem> - <para>This filter takes one argument â a prefix of a row key. It returns - only those key-values present in a row that starts with the specified - row prefix</para> - <itemizedlist> - <title>Syntax</title> - <listitem> - <programlisting language="java">PrefixFilter (â<row_prefix>â)</programlisting> - </listitem> - </itemizedlist> - <itemizedlist> - <title>Example</title> - <listitem> - <programlisting language="java">PrefixFilter (âRowâ)</programlisting> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - <varlistentry> - <term>ColumnPrefixFilter</term> - <listitem> - <para>This filter takes one argument â a column prefix. It returns only - those key-values present in a column that starts with the specified - column prefix. The column prefix must be of the form: - <code>âqualifierâ</code>.</para> - <itemizedlist> - <title>Syntax</title> - <listitem> - <programlisting language="java">ColumnPrefixFilter(â<column_prefix>â)</programlisting> - </listitem> - </itemizedlist> - <itemizedlist> - <title>Example</title> - <listitem> - <programlisting language="java">ColumnPrefixFilter(âColâ)</programlisting> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - <varlistentry> - <term>MultipleColumnPrefixFilter</term> - <listitem> - <para>This filter takes a list of column prefixes. It returns key-values - that are present in a column that starts with any of the specified - column prefixes. Each of the column prefixes must be of the form: - <code>âqualifierâ</code>.</para> - <itemizedlist> - <title>Syntax</title> - <listitem> - <programlisting language="java">MultipleColumnPrefixFilter(â<column_prefix>â, â<column_prefix>â, â¦, â<column_prefix>â)</programlisting> - </listitem> - </itemizedlist> - <itemizedlist> - <title>Example</title> - <listitem> - <programlisting language="java">MultipleColumnPrefixFilter(âCol1â, âCol2â)</programlisting> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - <varlistentry> - <term>ColumnCountGetFilter</term> - <listitem> - <para>This filter takes one argument â a limit. It returns the first limit - number of columns in the table.</para> - <itemizedlist> - <title>Syntax</title> - <listitem> - <programlisting language="java">ColumnCountGetFilter - (â<limit>â)</programlisting> - </listitem> - </itemizedlist> - <itemizedlist> - <title>Example</title> - <listitem> - <programlisting language="java">ColumnCountGetFilter (4)</programlisting> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - <varlistentry> - <term>PageFilter</term> - <listitem> - <para>This filter takes one argument â a page size. It returns page size - number of rows from the table.</para> - <itemizedlist> - <title>Syntax</title> - <listitem> - <programlisting language="java">PageFilter (â<page_size>â)</programlisting> - </listitem> - </itemizedlist> - <itemizedlist> - <title>Example</title> - <listitem> - <programlisting language="java">PageFilter (2)</programlisting> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - <varlistentry> - <term>ColumnPaginationFilter</term> - <listitem> - <para>This filter takes two arguments â a limit and offset. It returns limit - number of columns after offset number of columns. It does this for all - the rows.</para> - <itemizedlist> - <title>Syntax</title> - <listitem> - <programlisting language="java">ColumnPaginationFilter(â<limit>â, â<offset>â)</programlisting> - </listitem> - </itemizedlist> - <itemizedlist> - <title>Example</title> - <listitem> - <programlisting language="java">ColumnPaginationFilter (3, 5)</programlisting> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - <varlistentry> - <term>InclusiveStopFilter</term> - <listitem> - <para>This filter takes one argument â a row key on which to stop scanning. - It returns all key-values present in rows up to and including the - specified row.</para> - <itemizedlist> - <title>Syntax</title> - <listitem> - <programlisting language="java">InclusiveStopFilter(â<stop_row_key>â)</programlisting> - </listitem> - </itemizedlist> - <itemizedlist> - <title>Example</title> - <listitem> - <programlisting language="java">InclusiveStopFilter ('Row2')</programlisting> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - <varlistentry> - <term>TimeStampsFilter</term> - <listitem> - <para>This filter takes a list of timestamps. It returns those key-values - whose timestamps matches any of the specified timestamps.</para> - <itemizedlist> - <title>Syntax</title> - <listitem> - <programlisting language="java">TimeStampsFilter (<timestamp>, <timestamp>, ... ,<timestamp>)</programlisting> - </listitem> - </itemizedlist> - <itemizedlist> - <title>Example</title> - <listitem> - <programlisting language="java">TimeStampsFilter (5985489, 48895495, 58489845945)</programlisting> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - <varlistentry> - <term>RowFilter</term> - <listitem> - <para>This filter takes a compare operator and a comparator. It compares - each row key with the comparator using the compare operator and if the - comparison returns true, it returns all the key-values in that - row.</para> - <itemizedlist> - <title>Syntax</title> - <listitem> - <programlisting language="java">RowFilter (<compareOp>, â<row_comparator>â)</programlisting> - </listitem> - </itemizedlist> - <itemizedlist> - <title>Example</title> - <listitem> - <programlisting language="java">RowFilter (<=, âxyz)</programlisting> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - <varlistentry> - <term>Family Filter</term> - <listitem> - <para>This filter takes a compare operator and a comparator. It compares - each qualifier name with the comparator using the compare operator and - if the comparison returns true, it returns all the key-values in that - column.</para> - <itemizedlist> - <title>Syntax</title> - <listitem> - <programlisting language="java">QualifierFilter (<compareOp>, â<qualifier_comparator>â)</programlisting> - </listitem> - </itemizedlist> - <itemizedlist> - <title>Example</title> - <listitem> - <programlisting language="java">QualifierFilter (=, âColumn1â)</programlisting> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - <varlistentry> - <term>QualifierFilter</term> - <listitem> - <para>This filter takes a compare operator and a comparator. It compares - each qualifier name with the comparator using the compare operator and - if the comparison returns true, it returns all the key-values in that - column.</para> - <itemizedlist> - <title>Syntax</title> - <listitem> - <programlisting language="java">QualifierFilter (<compareOp>,â<qualifier_comparator>â)</programlisting> - </listitem> - </itemizedlist> - <itemizedlist> - <title>Example</title> - <listitem> - <programlisting language="java">QualifierFilter (=,âColumn1â)</programlisting> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - <varlistentry> - <term>ValueFilter</term> - <listitem> - <para>This filter takes a compare operator and a comparator. It compares - each value with the comparator using the compare operator and if the - comparison returns true, it returns that key-value.</para> - <itemizedlist> - <title>Syntax</title> - <listitem> - <programlisting language="java">ValueFilter (<compareOp>,â<value_comparator>â) </programlisting> - </listitem> - </itemizedlist> - <itemizedlist> - <title>Example</title> - <listitem> - <programlisting language="java">ValueFilter (!=, âValueâ)</programlisting> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - <varlistentry> - <term>DependentColumnFilter</term> - <listitem> - <para>This filter takes two arguments â a family and a qualifier. It tries - to locate this column in each row and returns all key-values in that row - that have the same timestamp. If the row doesnât contain the specified - column â none of the key-values in that row will be returned.</para> - <para>The filter can also take an optional boolean argument â - dropDependentColumn. If set to true, the column we were depending on - doesnât get returned.</para> - <para>The filter can also take two more additional optional arguments â a - compare operator and a value comparator, which are further checks in - addition to the family and qualifier. If the dependent column is found, - its value should also pass the value check and then only is its - timestamp taken into consideration.</para> - <itemizedlist> - <title>Syntax</title> - <listitem> - <programlisting language="java"><![CDATA[DependentColumnFilter (â<family>â,â<qualifier>â, <boolean>, <compare operator>, â<value - comparatorâ)]]></programlisting> - </listitem> - <listitem> - <programlisting language="java"><![CDATA[DependentColumnFilter (â<family>â,â<qualifier>â, <boolean>)]]></programlisting> - </listitem> - <listitem> - <programlisting language="java">DependentColumnFilter (â<family>â,â<qualifier>â)</programlisting> - </listitem> - </itemizedlist> - <itemizedlist> - <title>Example</title> - <listitem> - <programlisting language="java">DependentColumnFilter (âconfâ, âblacklistâ, false, >=, âzebraâ)</programlisting> - </listitem> - <listitem> - <programlisting language="java">DependentColumnFilter (âconfâ, 'blacklist', true)</programlisting> - </listitem> - <listitem> - <programlisting language="java">DependentColumnFilter (âconfâ, 'blacklist')</programlisting> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - <varlistentry> - <term>SingleColumnValueFilter</term> - <listitem> - <para>This filter takes a column family, a qualifier, a compare operator and - a comparator. If the specified column is not found â all the columns of - that row will be emitted. If the column is found and the comparison with - the comparator returns true, all the columns of the row will be emitted. - If the condition fails, the row will not be emitted. </para> - <para>This filter also takes two additional optional boolean arguments â - filterIfColumnMissing and setLatestVersionOnly</para> - <para>If the filterIfColumnMissing flag is set to true the columns of the - row will not be emitted if the specified column to check is not found in - the row. The default value is false.</para> - <para>If the setLatestVersionOnly flag is set to false, it will test - previous versions (timestamps) too. The default value is true.</para> - <para>These flags are optional and if you must set neither or both.</para> - <itemizedlist> - <title>Syntax</title> - <listitem> - <programlisting language="java">SingleColumnValueFilter(â<family>â,â<qualifier>â, <compare operator>, â<comparator>â, <filterIfColumnMissing_boolean>, <latest_version_boolean>)</programlisting> - </listitem> - <listitem> - <programlisting language="java">SingleColumnValueFilter(â<family>â, â<qualifier>, <compare operator>, â<comparator>â)</programlisting> - </listitem> - </itemizedlist> - <itemizedlist> - <title>Example</title> - <listitem> - <programlisting language="java">SingleColumnValueFilter (âFamilyAâ, âColumn1â, <=, âabcâ, true, false)</programlisting> - </listitem> - <listitem> - <programlisting>SingleColumnValueFilter (âFamilyAâ, âColumn1â, <=, âabcâ)</programlisting> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - <varlistentry> - <term>SingleColumnValueExcludeFilter</term> - <listitem> - <para>This filter takes the same arguments and behaves same as - SingleColumnValueFilter â however, if the column is found and the - condition passes, all the columns of the row will be emitted except for - the tested column value.</para> - <itemizedlist> - <title>Syntax</title> - <listitem> - <programlisting language="java">SingleColumnValueExcludeFilter('<family>', '<qualifier>', <compare operator>, '<comparator>', <latest_version_boolean>, <filterIfColumnMissing_boolean>)</programlisting> - </listitem> - <listitem> - <programlisting language="java">SingleColumnValueExcludeFilter('<family>', '<qualifier>', <compare operator>, '<comparator>')</programlisting> - </listitem> - </itemizedlist> - <itemizedlist> - <title>Example</title> - <listitem> - <programlisting language="java">SingleColumnValueExcludeFilter (âFamilyAâ, âColumn1â, â<=â, âabcâ, âfalseâ, âtrueâ)</programlisting> - </listitem> - <listitem> - <programlisting language="java">SingleColumnValueExcludeFilter (âFamilyAâ, âColumn1â, â<=â, âabcâ)</programlisting> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - <varlistentry> - <term>ColumnRangeFilter</term> - <listitem> - <para>This filter is used for selecting only those keys with columns that - are between minColumn and maxColumn. It also takes two boolean variables - to indicate whether to include the minColumn and maxColumn or - not.</para> - <para>If you donât want to set the minColumn or the maxColumn â you can pass - in an empty argument.</para> - <itemizedlist> - <title>Syntax</title> - <listitem> - <programlisting language="java">ColumnRangeFilter (â<minColumn>â, <minColumnInclusive_bool>, â<maxColumn>â, <maxColumnInclusive_bool>)</programlisting> - </listitem> - </itemizedlist> - <itemizedlist> - <title>Example</title> - <listitem> - <programlisting language="java">ColumnRangeFilter (âabcâ, true, âxyzâ, false)</programlisting> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - </variablelist> - </section> - </section> -</chapter> - http://git-wip-us.apache.org/repos/asf/hbase/blob/e80b3092/src/main/docbkx/tracing.xml ---------------------------------------------------------------------- diff --git a/src/main/docbkx/tracing.xml b/src/main/docbkx/tracing.xml deleted file mode 100644 index b5dfd35..0000000 --- a/src/main/docbkx/tracing.xml +++ /dev/null @@ -1,187 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<appendix - xml:id="tracing" - version="5.0" - xmlns="http://docbook.org/ns/docbook"; - xmlns:xlink="http://www.w3.org/1999/xlink"; - xmlns:xi="http://www.w3.org/2001/XInclude"; - xmlns:svg="http://www.w3.org/2000/svg"; - xmlns:m="http://www.w3.org/1998/Math/MathML"; - xmlns:html="http://www.w3.org/1999/xhtml"; - xmlns:db="http://docbook.org/ns/docbook";> - <!--/** - * Licensed to the Apache Software Foundation (ASF) under one - * or more contributor license agreements. See the NOTICE file - * distributed with this work for additional information - * regarding copyright ownership. The ASF licenses this file - * to you under the Apache License, Version 2.0 (the - * "License"); you may not use this file except in compliance - * with the License. You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ ---> - <title>Enabling Dapper-like Tracing in HBase</title> - - <para> - <link - xlink:href="https://issues.apache.org/jira/browse/HBASE-6449";>HBASE-6449</link> added support - for tracing requests through HBase, using the open source tracing library, <link - xlink:href="http://github.com/cloudera/htrace";>HTrace</link>. Setting up tracing is quite - simple, however it currently requires some very minor changes to your client code (it would not - be very difficult to remove this requirement). </para> - - <section - xml:id="tracing.spanreceivers"> - <title>SpanReceivers</title> - <para> The tracing system works by collecting information in structs called 'Spans'. It is up to - you to choose how you want to receive this information by implementing the - <classname>SpanReceiver</classname> interface, which defines one method: </para> - <programlisting><![CDATA[ -public void receiveSpan(Span span); -]]></programlisting> - <para>This method serves as a callback whenever a span is completed. HTrace allows you to use as - many SpanReceivers as you want so you can easily send trace information to multiple - destinations. </para> - - <para> Configure what SpanReceivers you'd like to us by putting a comma separated list of the - fully-qualified class name of classes implementing <classname>SpanReceiver</classname> in - <filename>hbase-site.xml</filename> property: - <varname>hbase.trace.spanreceiver.classes</varname>. </para> - - <para> HTrace includes a <classname>LocalFileSpanReceiver</classname> that writes all span - information to local files in a JSON-based format. The - <classname>LocalFileSpanReceiver</classname> looks in <filename>hbase-site.xml</filename> - for a <varname>hbase.local-file-span-receiver.path</varname> property with a value describing - the name of the file to which nodes should write their span information. </para> - <programlisting><![CDATA[ -<property> - <name>hbase.trace.spanreceiver.classes</name> - <value>org.htrace.impl.LocalFileSpanReceiver</value> -</property> -<property> - <name>hbase.local-file-span-receiver.path</name> - <value>/var/log/hbase/htrace.out</value> -</property> -]]></programlisting> - - <para> HTrace also provides <classname>ZipkinSpanReceiver</classname> which converts spans to <link - xlink:href="http://github.com/twitter/zipkin";>Zipkin</link> span format and send them to - Zipkin server. In order to use this span receiver, you need to install the jar of - htrace-zipkin to your HBase's classpath on all of the nodes in your cluster. </para> - <para> - <filename>htrace-zipkin</filename> is published to the maven central repository. You could get - the latest version from there or just build it locally and then copy it out to all nodes, - change your config to use zipkin receiver, distribute the new configuration and then (rolling) - restart. </para> - <para> Here is the example of manual setup procedure. </para> - <screen language="bourne"><![CDATA[ -$ git clone https://github.com/cloudera/htrace -$ cd htrace/htrace-zipkin -$ mvn compile assembly:single -$ cp target/htrace-zipkin-*-jar-with-dependencies.jar $HBASE_HOME/lib/ - # copy jar to all nodes... -]]></screen> - <para>The <classname>ZipkinSpanReceiver</classname> looks in <filename>hbase-site.xml</filename> - for a <varname>hbase.zipkin.collector-hostname</varname> and - <varname>hbase.zipkin.collector-port</varname> property with a value describing the Zipkin - collector server to which span information are sent. </para> - <programlisting language="xml"><![CDATA[ -<property> - <name>hbase.trace.spanreceiver.classes</name> - <value>org.htrace.impl.ZipkinSpanReceiver</value> -</property> -<property> - <name>hbase.zipkin.collector-hostname</name> - <value>localhost</value> -</property> -<property> - <name>hbase.zipkin.collector-port</name> - <value>9410</value> -</property> -]]></programlisting> - - <para> If you do not want to use the included span receivers, you are encouraged to write your - own receiver (take a look at <classname>LocalFileSpanReceiver</classname> for an example). If - you think others would benefit from your receiver, file a JIRA or send a pull request to <link - xlink:href="http://github.com/cloudera/htrace";>HTrace</link>. </para> - </section> - - <section - xml:id="tracing.client.modifications"> - <title>Client Modifications</title> - <para> In order to turn on tracing in your client code, you must initialize the module sending - spans to receiver once per client process. </para> - <programlisting language="java"><![CDATA[ -private SpanReceiverHost spanReceiverHost; - -... - - Configuration conf = HBaseConfiguration.create(); - SpanReceiverHost spanReceiverHost = SpanReceiverHost.getInstance(conf); -]]></programlisting> - <para>Then you simply start tracing span before requests you think are interesting, and close it - when the request is done. For example, if you wanted to trace all of your get operations, you - change this: </para> - <programlisting language="java"><![CDATA[ -HTable table = new HTable(conf, "t1"); -Get get = new Get(Bytes.toBytes("r1")); -Result res = table.get(get); -]]></programlisting> - <para>into: </para> - <programlisting language="java"><![CDATA[ -TraceScope ts = Trace.startSpan("Gets", Sampler.ALWAYS); -try { - HTable table = new HTable(conf, "t1"); - Get get = new Get(Bytes.toBytes("r1")); - Result res = table.get(get); -} finally { - ts.close(); -} -]]></programlisting> - <para>If you wanted to trace half of your 'get' operations, you would pass in: </para> - <programlisting language="java"><![CDATA[ -new ProbabilitySampler(0.5) -]]></programlisting> - <para>in lieu of <varname>Sampler.ALWAYS</varname> to <classname>Trace.startSpan()</classname>. - See the HTrace <filename>README</filename> for more information on Samplers. </para> - </section> - - <section - xml:id="tracing.client.shell"> - <title>Tracing from HBase Shell</title> - <para> You can use <command>trace</command> command for tracing requests from HBase Shell. - <command>trace 'start'</command> command turns on tracing and <command>trace - 'stop'</command> command turns off tracing. </para> - <programlisting><![CDATA[ -hbase(main):001:0> trace 'start' -hbase(main):002:0> put 'test', 'row1', 'f:', 'val1' # traced commands -hbase(main):003:0> trace 'stop' -]]></programlisting> - <para> - <command>trace 'start'</command> and <command>trace 'stop'</command> always returns boolean - value representing if or not there is ongoing tracing. As a result, <command>trace - 'stop'</command> returns false on suceess. <command>trace 'status'</command> just returns if - or not tracing is turned on. </para> - <programlisting><![CDATA[ -hbase(main):001:0> trace 'start' -=> true - -hbase(main):002:0> trace 'status' -=> true - -hbase(main):003:0> trace 'stop' -=> false - -hbase(main):004:0> trace 'status' -=> false -]]></programlisting> - </section> - -</appendix>
