http://git-wip-us.apache.org/repos/asf/hbase/blob/cb77a925/src/main/asciidoc/_chapters/thrift_filter_language.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/_chapters/thrift_filter_language.adoc b/src/main/asciidoc/_chapters/thrift_filter_language.adoc new file mode 100644 index 0000000..46f816a --- /dev/null +++ b/src/main/asciidoc/_chapters/thrift_filter_language.adoc @@ -0,0 +1,289 @@ +//// +/** + * + * 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. + */ +//// + +[[thrift]] += Thrift API and Filter Language +:doctype: book +:numbered: +:toc: left +:icons: font +:experimental: + + +Apache link:http://thrift.apache.org/[Thrift] 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:http://wiki.apache.org/hadoop/Hbase/ThriftApi. + +You can configure Thrift for secure authentication at the server and client side, by following the procedures in <<security.client.thrift,security.client.thrift>> and <<security.gateway.thrift,security.gateway.thrift>>. + +The rest of this chapter discusses the filter language provided by the Thrift API. + +[[thrift.filter_language]] +== Filter Language + +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 `scan help` command in the shell. + +You specify a filter as a string, which is parsed on the server to construct the filter. + +[[general_syntax]] +=== General Filter String Syntax + +A simple filter expression is expressed as a string: + +---- +âFilterName (argument, argument,... , argument)â +---- + +Keep the following syntax guidelines in mind. + +* Specify the name of the filter followed by the comma-separated argument list in parentheses. +* If the argument represents a string, it should be enclosed in single quotes (`'`). +* Arguments which represent a boolean, an integer, or a comparison operator (such as <, >, or !=), should not be enclosed in quotes +* The filter name must be a single word. + All ASCII characters are allowed except for whitespace, single quotes and parentheses. +* 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. + +=== Compound Filters and Operators + +.Binary Operators +`AND`:: + If the `AND` operator is used, the key-vallue must satisfy both the filters. + +`OR`:: + If the `OR` operator is used, the key-value must satisfy at least one of the filters. + +.Unary Operators +`SKIP`:: + For a particular row, if any of the key-values fail the filter condition, the entire row is skipped. + +`WHILE`:: + For a particular row, key-values will be emitted until a key-value is reached t hat fails the filter condition. + +.Compound Operators +==== +You can combine multiple operators to create a hierarchy of filters, such as the following example: +[source] +---- +(Filter1 AND Filter2) OR (Filter3 AND Filter4) +---- +==== + +=== Order of Evaluation + +. Parentheses have the highest precedence. +. The unary operators `SKIP` and `WHILE` are next, and have the same precedence. +. The binary operators follow. `AND` has highest precedence, followed by `OR`. + +.Precedence Example +==== +[source] +---- +Filter1 AND Filter2 OR Filter +is evaluated as +(Filter1 AND Filter2) OR Filter3 +---- + +[source] +---- +Filter1 AND SKIP Filter2 OR Filter3 +is evaluated as +(Filter1 AND (SKIP Filter2)) OR Filter3 +---- +==== + +You can use parentheses to explicitly control the order of evaluation. + +=== Compare Operator + +The following compare operators are provided: + +. LESS (<) +. LESS_OR_EQUAL (<=) +. EQUAL (=) +. NOT_EQUAL (!=) +. GREATER_OR_EQUAL (>=) +. GREATER (>) +. NO_OP (no operation) + +The client should use the symbols (<, <=, =, !=, >, >=) to express compare operators. + +=== Comparator + +A comparator can be any of the following: + +. _BinaryComparator_ - This lexicographically compares against the specified byte array using Bytes.compareTo(byte[], byte[]) +. _BinaryPrefixComparator_ - This lexicographically compares against a specified byte array. + It only compares up to the length of this byte array. +. _RegexStringComparator_ - This compares against the specified byte array using the given regular expression. + Only EQUAL and NOT_EQUAL comparisons are valid with this comparator +. _SubStringComparator_ - 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 + +The general syntax of a comparator is:` + ComparatorType:ComparatorValue` + +The ComparatorType for the various comparators is as follows: + +. _BinaryComparator_ - binary +. _BinaryPrefixComparator_ - binaryprefix +. _RegexStringComparator_ - regexstring +. _SubStringComparator_ - substring + +The ComparatorValue can be any value. + +.Example ComparatorValues +. `binary:abc` will match everything that is lexicographically greater than "abc" +. `binaryprefix:abc` will match everything whose first 3 characters are lexicographically equal to "abc" +. `regexstring:ab*yz` will match everything that doesn't begin with "ab" and ends with "yz" +. `substring:abc123` will match everything that begins with the substring "abc123" + +[[examplephpclientprogram]] +=== Example PHP Client Program that uses the Filter Language + +[source,php] +---- +<? $_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); +?> +---- + +=== Example Filter Strings + +* `âPrefixFilter (âRowâ) AND PageFilter (1) AND FirstKeyOnlyFilter + ()â` will return all key-value pairs that match the following conditions: ++ +. The row containing the key-value should have prefix ``Row'' +. The key-value must be located in the first row of the table +. The key-value pair must be the first key-value in the row + + + +* `â(RowFilter (=, âbinary:Row 1â) AND TimeStampsFilter (74689, + 89734)) OR ColumnRangeFilter (âabcâ, true, âxyzâ, + false))â` will return all key-value pairs that match both the following conditions: ++ +* The key-value is in a row having row key ``Row 1'' +* The key-value must have a timestamp of either 74689 or 89734. +* Or it must match the following condition: ++ +* The key-value pair must be in a column that is lexicographically >= abc and < xyz + + + + +* `âSKIP ValueFilter (0)â` will skip the entire row if any of the values in the row is not 0 + +[[individualfiltersyntax]] +=== Individual Filter Syntax + +KeyOnlyFilter:: + This filter doesn't take any arguments. + It returns only the key component of each key-value. + +FirstKeyOnlyFilter:: + This filter doesn't take any arguments. + It returns only the first key-value from each row. + +PrefixFilter:: + 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 + +ColumnPrefixFilter:: + 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: `âqualifierâ`. + +MultipleColumnPrefixFilter:: + 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: `âqualifierâ`. + +ColumnCountGetFilter:: + This filter takes one argument â a limit. + It returns the first limit number of columns in the table. + +PageFilter:: + This filter takes one argument â a page size. + It returns page size number of rows from the table. + +ColumnPaginationFilter:: + 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. + +InclusiveStopFilter:: + 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. + +TimeStampsFilter:: + This filter takes a list of timestamps. + It returns those key-values whose timestamps matches any of the specified timestamps. + +RowFilter:: + 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. + +Family Filter:: + 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. + +QualifierFilter:: + 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. + +ValueFilter:: + 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. + +DependentColumnFilter:: + 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. + +SingleColumnValueFilter:: + 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. + +SingleColumnValueExcludeFilter:: + 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. + +ColumnRangeFilter:: + 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.
http://git-wip-us.apache.org/repos/asf/hbase/blob/cb77a925/src/main/asciidoc/_chapters/tracing.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/_chapters/tracing.adoc b/src/main/asciidoc/_chapters/tracing.adoc new file mode 100644 index 0000000..9a4a811 --- /dev/null +++ b/src/main/asciidoc/_chapters/tracing.adoc @@ -0,0 +1,193 @@ +//// +/** + * + * 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. + */ +//// + + +[appendix] +[[tracing]] +== Enabling Dapper-like Tracing in HBase + +:doctype: book +:numbered: +:toc: left +:icons: font +:experimental: + +link:https://issues.apache.org/jira/browse/HBASE-6449[HBASE-6449] added support for tracing requests through HBase, using the open source tracing library, link:http://github.com/cloudera/htrace[HTrace]. +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). + +[[tracing.spanreceivers]] +=== SpanReceivers + +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 `SpanReceiver` interface, which defines one method: + +[source] +---- + +public void receiveSpan(Span span); +---- + +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. + +Configure what SpanReceivers you'd like to us by putting a comma separated list of the fully-qualified class name of classes implementing `SpanReceiver` in _hbase-site.xml_ property: `hbase.trace.spanreceiver.classes`. + +HTrace includes a `LocalFileSpanReceiver` that writes all span information to local files in a JSON-based format. +The `LocalFileSpanReceiver` looks in _hbase-site.xml_ for a `hbase.local-file-span-receiver.path` property with a value describing the name of the file to which nodes should write their span information. + +[source] +---- + +<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> +---- + +HTrace also provides `ZipkinSpanReceiver` which converts spans to link:http://github.com/twitter/zipkin[Zipkin] 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. + +_htrace-zipkin_ 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. + +Here is the example of manual setup procedure. + +---- + +$ 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... +---- + +The `ZipkinSpanReceiver` looks in _hbase-site.xml_ for a `hbase.zipkin.collector-hostname` and `hbase.zipkin.collector-port` property with a value describing the Zipkin collector server to which span information are sent. + +[source,xml] +---- + +<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> +---- + +If you do not want to use the included span receivers, you are encouraged to write your own receiver (take a look at `LocalFileSpanReceiver` for an example). If you think others would benefit from your receiver, file a JIRA or send a pull request to link:http://github.com/cloudera/htrace[HTrace]. + +[[tracing.client.modifications]] +== Client Modifications + +In order to turn on tracing in your client code, you must initialize the module sending spans to receiver once per client process. + +[source,java] +---- + +private SpanReceiverHost spanReceiverHost; + +... + + Configuration conf = HBaseConfiguration.create(); + SpanReceiverHost spanReceiverHost = SpanReceiverHost.getInstance(conf); +---- + +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: + +[source,java] +---- + +HTable table = new HTable(conf, "t1"); +Get get = new Get(Bytes.toBytes("r1")); +Result res = table.get(get); +---- + +into: + +[source,java] +---- + +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(); +} +---- + +If you wanted to trace half of your 'get' operations, you would pass in: + +[source,java] +---- + +new ProbabilitySampler(0.5) +---- + +in lieu of `Sampler.ALWAYS` to `Trace.startSpan()`. +See the HTrace _README_ for more information on Samplers. + +[[tracing.client.shell]] +== Tracing from HBase Shell + +You can use +trace+ command for tracing requests from HBase Shell. +trace 'start'+ command turns on tracing and +trace + 'stop'+ command turns off tracing. + +[source] +---- + +hbase(main):001:0> trace 'start' +hbase(main):002:0> put 'test', 'row1', 'f:', 'val1' # traced commands +hbase(main):003:0> trace 'stop' +---- + ++trace 'start'+ and +trace 'stop'+ always returns boolean value representing if or not there is ongoing tracing. +As a result, +trace + 'stop'+ returns false on suceess. +trace 'status'+ just returns if or not tracing is turned on. + +[source] +---- + +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 +---- + +:numbered:
