You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@hbase.apache.org by bu...@apache.org on 2015/07/14 04:49:29 UTC
[04/15] hbase git commit: HBASE-14066 clean out old docbook docs from
branch-1.
http://git-wip-us.apache.org/repos/asf/hbase/blob/fdd2692f/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/fdd2692f/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/fdd2692f/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>