Added: websites/staging/blur/trunk/content/blur/docs/0.2.4/cluster-setup.base.html ============================================================================== --- websites/staging/blur/trunk/content/blur/docs/0.2.4/cluster-setup.base.html (added) +++ websites/staging/blur/trunk/content/blur/docs/0.2.4/cluster-setup.base.html Thu Jan 1 17:22:30 2015 @@ -0,0 +1,354 @@ +<!DOCTYPE html> +<!-- + 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. +--> +<html> + <head> + <title>Cluster Setup - Apache Blur (Incubator) Documentation</title> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <!-- Bootstrap --> + <link href="resources/css/bootstrap.min.css" rel="stylesheet" media="screen"> + <link href="resources/css/bs-docs.css" rel="stylesheet" media="screen"> + </head> + <body> + <div class="navbar navbar-inverse navbar-fixed-top"> + <div class="container"> + <div class="navbar-header"> + <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse"> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + </button> + <a class="navbar-brand" href="http://incubator.apache.org/blur";>Apache Blur (Incubator)</a> + </div> + <div class="collapse navbar-collapse"> + <ul class="nav navbar-nav"> + <li><a href="index.html">Main</a></li> + <li><a href="getting-started.html">Getting Started</a></li> + <li><a href="platform.html">Platform</a></li> + <li><a href="data-model.html">Data Model</a></li> + <li class="active"><a href="cluster-setup.html">Cluster Setup</a></li> + <li><a href="using-blur.html">Using Blur</a></li> + <li><a href="Blur.html">Blur API</a></li> + <li><a href="console.html">Console</a></li> + </ul> + </div> + </div> + </div> + <div class="container bs-docs-container"> + <div class="row"> + <div class="col-md-3"> + <div class="bs-sidebar hidden-print affix" role="complementary"> + <ul class="nav bs-sidenav"> + <li> + <a href="#general">General Configuration</a> + <ul class="nav"> + <li><a href="#general-blur-site">blur-site.properties</a></li> + <li><a href="#general-hadoop">Hadoop</a></li> + </ul> + </li> + <li> + <a href="#controller">Controller Server Configuration</a> + <ul class="nav"> + <li><a href="#controller-blur-site">blur-site.properties</a></li> + <li><a href="#controller-blur-env">blur-env.sh</a></li> + </ul> + </li> + <li> + <a href="#shard">Shard Server Configuration</a> + <ul class="nav"> + <li><a href="#shard-blur-site">blur-site.properties</a></li> + <li><a href="#shard-blur-env">blur-env.sh</a></li> + <li><a href="#block-cache">Block Cache</a> + <ul class="nav"> + <li><a href="#block-cache-v2"> V2 Block Cache Configuration</a></li> + <li><a href="#block-cache-v1"> V1 Block Cache Configuration</a></li> + </ul> + </li> + </ul> + </li> + <li> + <a href="#metrics">Metrics</a> + <ul class="nav"> + <li><a href="#shard-mbean">Shard Server - MBean</a></li> + <li><a href="#reporters">Other Reporters</a></li> + </ul> + </li> + </ul> + </div> + </div> + <div class="col-md-9" role="main"> + <section> + <div class="page-header"> + <h1 id="general">General Configuration</h1> + </div> +<p> +The basic cluster setup involves editing the blur-site.properties and the blur-env.sh +files in the $BLUR_HOME/conf directory. It is recommended that a standalone ZooKeeper +be setup. Also a modern version of Hadoop with append support is required for proper data +management (the write ahead log requires the sync operation). + +<div class="bs-callout bs-callout-warning"><h4>Caution</h4>If you setup a standalone ZooKeeper +you will need to configure Blur to NOT manage the ZooKeeper. You will need to edit blur-env.sh +file: +<pre><code class="bash">export BLUR_MANAGE_ZK=false</code></pre> +</div> +</p> + <h3 id="general-blur-site">blur-site.properties</h3> + <p> + +<pre> +<code class="bash"># The ZooKeeper connection string, consider adding a root path to the string, it +# can help when upgrading Blur. +# Example: zknode1:2181,zknode2:2181,zknode3:2181/blur-0.2.4 +# +# NOTE: If you provide the root path "/blur-0.2.4", that will have to be manually +# created before Blur will start. + +blur.zookeeper.connection=127.0.0.1 + +# If you are only going to run a single shard cluster then leave this as default. + +blur.cluster.name=default + +# Sets the default table location in hdfs. If left null or omitted the table uri property in +# the table descriptor will be required for all tables. + +blur.cluster.default.table.uri=hdfs://namenode/blur/tables</code> +</pre></p> + <h4>Default Properties</h4> + <table class="table-bordered table-striped table-condensed"> + <tr><td>Property</td><td>Description</td></tr> +|||General-Server-Properties||| + </table> + <h3 id="general-hadoop">Hadoop</h3> +<p> +The current version of Blur has Hadoop 1.2.1 embedded in the "apache-blur-*/lib/hadoop-1.2.1" path. However if +you are using a different version of Hadoop or want Blur to use the Hadoop configuration in your installed +version you will need to set the "HADOOP_HOME" environment variable in the +"blur-env.sh" script found in "apache-blur-*/conf/". +<pre> +<code class="bash"># Edit the blur-env.sh +export HADOOP_HOME=<path to your Hadoop install directory></code> +</pre> +</p> + </section> + <section> + <div class="page-header"> + <h1 id="controller">Controller Server Configuration</h1> + </div> + <h3 id="controller-blur-site">blur-site.properties</h3> + <p> + These are the default settings for the shard server that can be overridden in the blur-site.properties file. Consider increasing the various thread pool counts (*.thread.count). The blur.controller.server.remote.thread.count is very important to increase for larger clusters, basically one thread is used per shard server per query. Some production clusters have set this thread pool to 2000 or more threads. + </p> +<h4>Default Properties</h4> +<table class="table-bordered table-striped table-condensed"> +<tr><td>Property</td><td>Description</td></tr> +|||Controller-Server-Properties||| +</table> + <h3 id="controller-blur-env">blur-env.sh</h3> + <pre><code class="bash"># JAVA JVM OPTIONS for the controller servers, jvm tuning parameters are placed here. +# Consider adding the -XX:OnOutOfMemoryError="kill -9 %p" option to kill jvms that are failing due to memory issues. +export BLUR_CONTROLLER_JVM_OPTIONS="-Xmx1024m -Djava.net.preferIPv4Stack=true " + +# Time to sleep between controller server commands. +export BLUR_CONTROLLER_SLEEP=0.1 + +# The of controller servers to spawn per machine. +export BLUR_NUMBER_OF_CONTROLLER_SERVER_INSTANCES_PER_MACHINE=1</code></pre> + </section> + <section> + <div class="page-header"> + <h1 id="shard">Shard Server Configuration</h1> + </div> +<h3>Minimum Settings to Configure</h3> +<p> +It is highly recommended that the ulimits are increase on the server specifically: +<ul> +<li>open files</li> +<li>max user processes</li> +</ul> +<br/> +In Hadoop the dfs.datanode.max.xcievers should be increased to at least 4096 if not more. +<pre> +<code class="bash"><property> + <name>dfs.datanode.max.xcievers</name> + <value>4096</value> +</property></code></pre> +<br/> +In blur-env.sh set the cache memory for the shard processes. DO NOT over allocate this will +likely crash your server. +<pre><code class="bash">-XX:MaxDirectMemorySize=13g</code></pre> +<div class="bs-callout bs-callout-warning"><h4>Caution</h4> +Swap can kill java perform, you may want to consider disabling swap.</div> + +</p> + <h3 id="shard-blur-site">blur-site.properties</h3> + <p> + These are the default settings for the shard server that can be overridden in the blur-site.properties file. Consider increasing the various thread pool counts (*.thread.count). Also the blur.max.clause.count sets the BooleanQuery max clause count for Lucene queries. + </p> + + <h4>Default Properties</h4> + <table class="table-bordered table-striped table-condensed"> + <tr><td>Property</td><td>Description</td></tr> +|||Shard-Server-Properties||| + </table> + + <h3 id="shard-blur-env">blur-env.sh</h3> + <pre><code class="bash"># JAVA JVM OPTIONS for the shard servers, jvm tuning parameters are placed here. +export BLUR_SHARD_JVM_OPTIONS="-Xmx1024m -Djava.net.preferIPv4Stack=true -XX:MaxDirectMemorySize=256m " + +# Time to sleep between shard server commands. +export BLUR_SHARD_SLEEP=0.1 + +# The of shard servers to spawn per machine. +export BLUR_NUMBER_OF_SHARD_SERVER_INSTANCES_PER_MACHINE=1</code></pre> + +<h3 id="block-cache">Block Cache</h3> +<h4>Why</h4> +<p>HDFS is a great filesystem for streaming large amounts data across large scale clusters. However the random access latency is typically the same performance you would get in reading from a local drive if the data you are trying to access is not in the operating systems file cache. In other words every access to HDFS is similar to a local read with a cache miss. There have been great performance boosts in HDFS over the past few years but it still can't perform at the level that a search engine needs.</p> +<p>Now you might be thinking that Lucene reads from the local hard drive and performs great, so why wouldn't HDFS perform fairly well on it's own? However most of time the Lucene index files are cached by the operating system's file system cache. So Blur has it's own file system cache allows it to perform low latency data look-ups against HDFS.</p> + +<h3 id="block-cache-v2">V2 Block Cache Configuration</h3> +<h4>How</h4> +<p>The Google <a href="http://code.google.com/p/concurrentlinkedhashmap/";>concurrentlinkedhashmap</a> library is at the center of the block cache in the shard servers. In version 2, which is enabled by default, the slab allocation is no longer used. <a href="http://mail-archives.apache.org/mod_mbox/incubator-blur-dev/201310.mbox/%3CCAB6tTr0Nr2aDLc4kkHoeqiO-utwzBAhb=Ru==gmhqry4axp...@mail.gmail.com%3E";>Here</a> is a discussion of the motivations behind the rewrite.</p> + +<p>Below are the properties related to V2 of the block cache.</p> + +<table class="table-bordered table-striped table-condensed"> +<tr><td nowrap="1">blur.shard.block.cache.total.size</td><td> +<p>This is used to limit the amount of off heap cache size. By default the cache is 64MB less than the -XX:MaxDirectMemorySize, +so if you want the block cache to use less than that amount then set this value.</p></td></tr> + +<tr><td nowrap="1">blur.shard.block.cache.v2.fileBufferSize</td><td> +<p>This is the size of the buffer when accessing hdfs, by default it is set to 8K. However in most systems this should probably be increased to something closer to 64K. Use the "fstune" command in the shell to help figure out what the best buffer size should be in your system.</p></td></tr> + +<tr><td nowrap="1">blur.shard.block.cache.v2.cacheBlockSize</td><td> +<p>This is the size of the cache entry for any file that is NOT explicitly defined. Most of the time you are going to want this value to equal the "blur.shard.block.cache.v2.fileBufferSize" value.</p></td></tr> + +<tr><td nowrap="1">blur.shard.block.cache.v2.cacheBlockSize.<ext></td><td> +<p>This is the size of the cache entry for any file that has the given extension. By default "filter" is the only file that has a none default cache block size, it's current value is 32MB. This means that unless file is larger than 32MB in size, it will be stored as a single value in the cache. For cached filters this is required for performance during the transversal of the logical bitset stored in the file.</p></td></tr> + +<tr><td nowrap="1">blur.shard.block.cache.v2.store</td><td> +<p>This property defines how the cache will be stored, by default it's off heap. This means that it is not accounted for in the used heap section that you can find in jconsole or visualvm. However you can track it's size through the "top" command in the shell, MBeans in jconsole, or the metrics call via the Blur thrift API.<br/><br/>Unless you are using a specialized JVM or are debugging problem this should remain off heap, however if you would like to use the cache as on heap allocated blocks change this value to ON_HEAP.</p></td></tr> + +blur.shard.block.cache.v2.write.cache.ext= +blur.shard.block.cache.v2.write.nocache.ext=fdt + +<tr><td nowrap="1">blur.shard.block.cache.v2.read.default</td><td> +<p>This property defines the default action to cache or not to cache the data during a read operation. By default this is true. This will be the action taken if the file extension is not found in either the "blur.shard.block.cache.v2.read.cache.ext" property or the "blur.shard.block.cache.v2.read.nocache.ext" property.</p></td></tr> + +<tr><td nowrap="1">blur.shard.block.cache.v2.read.cache.ext</td><td> +<p>This property defines a comma separated list of file extensions that are to be cached during a read operations.</p></td></tr> + +<tr><td nowrap="1">blur.shard.block.cache.v2.read.nocache.ext</td><td> +<p>This property defines a comma separated list of file extensions that are NOT to be cached during a read operations. If the file extension is in the "blur.shard.block.cache.v2.read.cache.ext" property, it will have no effect in this list.</p></td></tr> + +<tr><td nowrap="1">blur.shard.block.cache.v2.write.default</td><td> +<p>This property defines the default action to cache or not to cache the data during a write operation. By default this is true. This will be the action taken if the file extension is not found in either the "blur.shard.block.cache.v2.write.cache.ext" property or the "blur.shard.block.cache.v2.write.nocache.ext" property.</p></td></tr> + +<tr><td nowrap="1">blur.shard.block.cache.v2.write.cache.ext</td><td> +<p>This property defines a comma separated list of file extensions that are to be cached during a write operations.</p></td></tr> + +<tr><td nowrap="1">blur.shard.block.cache.v2.write.nocache.ext</td><td> +<p>This property defines a comma separated list of file extensions that are NOT to be cached during a write operations. If the file extension is in the "blur.shard.block.cache.v2.write.cache.ext" property, it will have no effect in this list.</p></td></tr> + +</table> + + <h3 id="block-cache-v1">V1 Block Cache Configuration</h3> + <h4>How</h4> + <p>On shard server start-up Blur creates 1 or more block cache slabs blur.shard.blockcache.slab.count that are each 128 MB in size. These slabs can be allocated on or off the heap blur.shard.blockcache.direct.memory.allocation. Each slab is broken up into 16,384 blocks with each block size being 8K. Then on the heap there is a concurrent LRU cache that tracks what blocks of what files are in which slab(s) at what offset. So the more slabs of cache you create the more entries there will be in the LRU thus more heap.</p> + <h4>Configuration</h4> + <p>Scenario: + + Say the shard server(s) that you are planning to run Blur on have 32G of ram. These machines are probably also running HDFS data nodes as well with very high xcievers (dfs.datanode.max.xcievers in hdfs-site.xml) say 8K. If the data nodes are configured with 1G of heap then they may consume up to 4G of memory due to the high thread count because of the xcievers. Next let's say you configure Blur to 4G of heap as well, and you want to use 12G of off heap cache.</p> + <h5>Auto Configuration</h5> + <p>In the blur-env.sh file you would need to change BLUR_SHARD_JVM_OPTIONS to include "-XX:MaxDirectMemorySize=12g" and possibly "-XX:+UseLargePages" depending on your Linux setup. If you leave the blur.shard.blockcache.slab.count to the default -1 the shard startup will automatically detect the -XX:MaxDirectMemorySize size and automatically use almost all of the memory. By default the JVM has 64m in reserve for direct memory so by default Blur leaves at least that amount available to the JVM.</p> + <h5>Custom Configuration</h5> + <p>Again in the blur-env.sh file you would need to change BLUR_SHARD_JVM_OPTIONS to include "-XX:MaxDirectMemorySize=13g" and possibly "-XX:+UseLargePages" depending on your Linux setup. I set the MaxDirectMemorySize to more than 12G to make sure we don't hit the maximum limit and cause a OOM exception, this does not reserve 13G it's a control to not allow more than that. Below is a working example, it also contains GC logging and GC configuration:</p> + <pre><code class="bash">export BLUR_SHARD_JVM_OPTIONS="-XX:MaxDirectMemorySize=13g \ + -XX:+UseLargePages \ + -Xms4g \ + -Xmx4g \ + -Xmn512m \ + -XX:+UseCompressedOops \ + -XX:+UseConcMarkSweepGC \ + -XX:+CMSIncrementalMode \ + -XX:CMSIncrementalDutyCycleMin=10 \ + -XX:CMSIncrementalDutyCycle=50 \ + -XX:ParallelGCThreads=8 \ + -XX:+UseParNewGC \ + -XX:MaxGCPauseMillis=200 \ + -XX:GCTimeRatio=10 \ + -XX:+DisableExplicitGC \ + -verbose:gc \ + -XX:+PrintGCDetails \ + -XX:+PrintGCDateStamps \ + -Xloggc:$BLUR_HOME/logs/gc-blur-shard-server_`date +%Y%m%d_%H%M%S`.log"</code></pre> + <p>Next you will need to setup blur-site.properties by changing blur.shard.blockcache.slab.count to 96. This is telling blur to allocate 96 128MB slabs of memory at shard server start-up. Note, that the first time you do this that the shard servers may take long time to allocate the memory. This is because the OS could be using most of that memory for it's own filesystem caching and it will need to unload it which may cause some IO due the cache synching to disk.</p> + <p>Also the blur.shard.blockcache.direct.memory.allocation is set to true by default, this will tell the JVM to try and allocate the memory off heap. If you want to run the slabs in the heap (which is not recommended) set this value to false.</p> + </section> + <section> + <div class="page-header"> + <h1 id="metrics">Metrics</h1> + </div> + <p class="lead">Internally Blur uses the Metrics library from Coda Hale (<a href="http://metrics.codahale.com/";>http://metrics.codahale.com/</a>). So by default all metrics are available through JMX here is a screenshot of what is available in the Shard server.</p> + <h3 id="shard-mbean">Shard Server - MBean Screenshot</h3> + <img src="resources/img/BlurShardServer.png" style="max-width:1000px"/> + <h3 id="reporters">Configuring Other Reporters</h3> + <p class="lead">New reporters can be added configured in the blur-site.properties. Multiple reporters can be configured.</p> + <h4>Example</h4> + <pre><code class="bash">blur.metrics.reporters=GangliaReporter +blur.metrics.reporter.ganglia.period=3 +blur.metrics.reporter.ganglia.unit=SECONDS +blur.metrics.reporter.ganglia.host=ganglia1 +blur.metrics.reporter.ganglia.port=8649</code></pre> + <h4>Reporters to Enable</h4> + <pre><code class="bash">blur.metrics.reporters=[ConsoleReporter,CsvReporter,GangliaReporter,GraphiteReporter]</code></pre> + <h4>ConsoleReporter</h4> + <pre><code class="bash">blur.metrics.reporter.console.period=[5] +blur.metrics.reporter.console.unit=[NANOSECONDS,MICROSECONDS,MILLISECONDS,SECONDS,MINUTES,HOURS,DAYS]</code></pre> + <h4>CsvReporter</h4> + <pre><code class="bash">blur.metrics.reporter.csv.period=[5] +blur.metrics.reporter.csv.unit=[NANOSECONDS,MICROSECONDS,MILLISECONDS,SECONDS,MINUTES,HOURS,DAYS] +blur.metrics.reporter.csv.outputDir=[.]</code></pre> + <h4>GangliaReporter</h4> + <pre><code class="bash">blur.metrics.reporter.ganglia.period=[5] +blur.metrics.reporter.ganglia.unit=[NANOSECONDS,MICROSECONDS,MILLISECONDS,SECONDS,MINUTES,HOURS,DAYS] +blur.metrics.reporter.ganglia.host=[localhost] +blur.metrics.reporter.ganglia.port=[-1] +blur.metrics.reporter.ganglia.prefix=[""] +blur.metrics.reporter.ganglia.compressPackageNames=[false]</code></pre> + <h4>GraphiteReporter</h4> + <pre><code class="bash">blur.metrics.reporter.graphite.period=[5] +blur.metrics.reporter.graphite.unit=[NANOSECONDS,MICROSECONDS,MILLISECONDS,SECONDS,MINUTES,HOURS,DAYS] +blur.metrics.reporter.graphite.host=[localhost] +blur.metrics.reporter.graphite.port=[-1] +blur.metrics.reporter.graphite.prefix=[""]</code></pre> + </section> + </div> + </div> + </div> + + <!-- jQuery (necessary for Bootstrap's JavaScript plugins) --> + <script src="resources/js/jquery-2.0.3.min.js"></script> + <!-- Include all compiled plugins (below), or include individual files as needed --> + <script src="resources/js/bootstrap.min.js"></script> + <!-- Enable responsive features in IE8 with Respond.js (https://github.com/scottjehl/Respond) --> + <script src="resources/js/respond.min.js"></script> + <script src="resources/js/docs.js"></script> + </body> +</html>
Added: websites/staging/blur/trunk/content/blur/docs/0.2.4/cluster-setup.html ============================================================================== --- websites/staging/blur/trunk/content/blur/docs/0.2.4/cluster-setup.html (added) +++ websites/staging/blur/trunk/content/blur/docs/0.2.4/cluster-setup.html Thu Jan 1 17:22:30 2015 @@ -0,0 +1,354 @@ +<!DOCTYPE html> +<!-- + 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. +--> +<html> + <head> + <title>Cluster Setup - Apache Blur (Incubator) Documentation</title> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <!-- Bootstrap --> + <link href="resources/css/bootstrap.min.css" rel="stylesheet" media="screen"> + <link href="resources/css/bs-docs.css" rel="stylesheet" media="screen"> + </head> + <body> + <div class="navbar navbar-inverse navbar-fixed-top"> + <div class="container"> + <div class="navbar-header"> + <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse"> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + </button> + <a class="navbar-brand" href="http://incubator.apache.org/blur";>Apache Blur (Incubator)</a> + </div> + <div class="collapse navbar-collapse"> + <ul class="nav navbar-nav"> + <li><a href="index.html">Main</a></li> + <li><a href="getting-started.html">Getting Started</a></li> + <li><a href="platform.html">Platform</a></li> + <li><a href="data-model.html">Data Model</a></li> + <li class="active"><a href="cluster-setup.html">Cluster Setup</a></li> + <li><a href="using-blur.html">Using Blur</a></li> + <li><a href="Blur.html">Blur API</a></li> + <li><a href="console.html">Console</a></li> + </ul> + </div> + </div> + </div> + <div class="container bs-docs-container"> + <div class="row"> + <div class="col-md-3"> + <div class="bs-sidebar hidden-print affix" role="complementary"> + <ul class="nav bs-sidenav"> + <li> + <a href="#general">General Configuration</a> + <ul class="nav"> + <li><a href="#general-blur-site">blur-site.properties</a></li> + <li><a href="#general-hadoop">Hadoop</a></li> + </ul> + </li> + <li> + <a href="#controller">Controller Server Configuration</a> + <ul class="nav"> + <li><a href="#controller-blur-site">blur-site.properties</a></li> + <li><a href="#controller-blur-env">blur-env.sh</a></li> + </ul> + </li> + <li> + <a href="#shard">Shard Server Configuration</a> + <ul class="nav"> + <li><a href="#shard-blur-site">blur-site.properties</a></li> + <li><a href="#shard-blur-env">blur-env.sh</a></li> + <li><a href="#block-cache">Block Cache</a> + <ul class="nav"> + <li><a href="#block-cache-v2"> V2 Block Cache Configuration</a></li> + <li><a href="#block-cache-v1"> V1 Block Cache Configuration</a></li> + </ul> + </li> + </ul> + </li> + <li> + <a href="#metrics">Metrics</a> + <ul class="nav"> + <li><a href="#shard-mbean">Shard Server - MBean</a></li> + <li><a href="#reporters">Other Reporters</a></li> + </ul> + </li> + </ul> + </div> + </div> + <div class="col-md-9" role="main"> + <section> + <div class="page-header"> + <h1 id="general">General Configuration</h1> + </div> +<p> +The basic cluster setup involves editing the blur-site.properties and the blur-env.sh +files in the $BLUR_HOME/conf directory. It is recommended that a standalone ZooKeeper +be setup. Also a modern version of Hadoop with append support is required for proper data +management (the write ahead log requires the sync operation). + +<div class="bs-callout bs-callout-warning"><h4>Caution</h4>If you setup a standalone ZooKeeper +you will need to configure Blur to NOT manage the ZooKeeper. You will need to edit blur-env.sh +file: +<pre><code class="bash">export BLUR_MANAGE_ZK=false</code></pre> +</div> +</p> + <h3 id="general-blur-site">blur-site.properties</h3> + <p> + +<pre> +<code class="bash"># The ZooKeeper connection string, consider adding a root path to the string, it +# can help when upgrading Blur. +# Example: zknode1:2181,zknode2:2181,zknode3:2181/blur-0.2.4 +# +# NOTE: If you provide the root path "/blur-0.2.4", that will have to be manually +# created before Blur will start. + +blur.zookeeper.connection=127.0.0.1 + +# If you are only going to run a single shard cluster then leave this as default. + +blur.cluster.name=default + +# Sets the default table location in hdfs. If left null or omitted the table uri property in +# the table descriptor will be required for all tables. + +blur.cluster.default.table.uri=hdfs://namenode/blur/tables</code> +</pre></p> + <h4>Default Properties</h4> + <table class="table-bordered table-striped table-condensed"> + <tr><td>Property</td><td>Description</td></tr> +<tr><td>blur.zookeeper.timeout (90000)</td><td>The zookeeper session timeout</td></tr><tr><td>blur.hdfs.trace.path</td><td>The path in HDFS where the distributed traces will be stored, if blank trace output will be written to the log or the ZooKeeper store.</td></tr><tr><td>blur.clientpool.client.max.connections.per.host (64)</td><td>Max number of connections per host.</td></tr><tr><td>blur.clientpool.client.stale.threshold (30)</td><td>Number of seconds between use that a connection will be marked as stale.</td></tr><tr><td>blur.clientpool.client.clean.frequency (10)</td><td>Number of seconds between checking connections.</td></tr><tr><td>blur.query.max.results.fetch (1000)</td><td>The maximum number of results that can be fetched in a single request</td></tr><tr><td>blur.query.max.row.fetch (100)</td><td>The maximum number of rows that can be fetched in a single request</td></tr><tr><td>blur.query.max.record.fetch (1000)</td><td>The maximum number of records that can be fetched in a single request</td></tr><tr><td>blur.metrics.reporters</td><td>Setup metric reporter</td></tr><tr><td>blur.thrift.max.frame.size (16384000)</td><td>Thrift max frame size</td></tr> + </table> + <h3 id="general-hadoop">Hadoop</h3> +<p> +The current version of Blur has Hadoop 1.2.1 embedded in the "apache-blur-*/lib/hadoop-1.2.1" path. However if +you are using a different version of Hadoop or want Blur to use the Hadoop configuration in your installed +version you will need to set the "HADOOP_HOME" environment variable in the +"blur-env.sh" script found in "apache-blur-*/conf/". +<pre> +<code class="bash"># Edit the blur-env.sh +export HADOOP_HOME=<path to your Hadoop install directory></code> +</pre> +</p> + </section> + <section> + <div class="page-header"> + <h1 id="controller">Controller Server Configuration</h1> + </div> + <h3 id="controller-blur-site">blur-site.properties</h3> + <p> + These are the default settings for the shard server that can be overridden in the blur-site.properties file. Consider increasing the various thread pool counts (*.thread.count). The blur.controller.server.remote.thread.count is very important to increase for larger clusters, basically one thread is used per shard server per query. Some production clusters have set this thread pool to 2000 or more threads. + </p> +<h4>Default Properties</h4> +<table class="table-bordered table-striped table-condensed"> +<tr><td>Property</td><td>Description</td></tr> +<tr><td>blur.controller.hostname</td><td>Sets the hostname for the controller, if blank the hostname is automatically detected</td></tr><tr><td>blur.controller.bind.address (0.0.0.0)</td><td>The binding address of the controller</td></tr><tr><td>blur.controller.bind.port (40010)</td><td>The default binding port of the controller server, 0 for random</td></tr><tr><td>blur.controller.shard.connection.timeout (60000)</td><td>The connection timeout, NOTE: this will be the maximum amount of time you can wait for a query.</td></tr><tr><td>blur.controller.command.driver.threads (16)</td><td>The number of command driver threads.</td></tr><tr><td>blur.controller.command.worker.threads (16)</td><td>The number of command worker threads.</td></tr><tr><td>blur.controller.server.thrift.thread.count (32)</td><td>The number of threads used for thrift requests</td></tr><tr><td>blur.controller.server.remote.thread.count (64)</td><td>The number of threads used for remote thrift requests to the shards server. This should be a large number.</td></tr><tr><td>blur.controller.thrift.selector.threads (2)</td><td>The number of threads used for selector processing inside the thrift server.</td></tr><tr><td>blur.controller.thrift.max.read.buffer.bytes (9223372036854775807)</td><td>The maximum number of bytes used for reading requests in the thrift server.</td></tr><tr><td>blur.controller.thrift.accept.queue.size.per.thread (4)</td><td>The size of the blocking queue per selector thread for passing accepted connections to the selector thread.</td></tr><tr><td>blur.controller.remote.fetch.count (150)</td><td>The number of hits to fetch per request to the shard servers</td></tr><tr><td>blur.controller.retry.max.fetch.retries (3)</td><td>The max number of retries to the shard server when there is an error during fetch</td></tr><tr><td>blur.controller.retry.max.mutate.retries (3)</td><td>The max number of retries to the shard server when there is an error during mutate</td></tr><tr><td>blur.c ontroller.retry.max.default.retries (3)</td><td>The max number of retries to the shard server when there is an error during all other request</td></tr><tr><td>blur.controller.retry.fetch.delay (500)</td><td>The starting backoff delay for the first retry for a fetch errors</td></tr><tr><td>blur.controller.retry.mutate.delay (500)</td><td>The starting backoff delay for the first retry for a mutate errors</td></tr><tr><td>blur.controller.retry.default.delay (500)</td><td>The starting backoff delay for the first retry for a all other request errors</td></tr><tr><td>blur.controller.retry.max.fetch.delay (2000)</td><td>The ending backoff delay for the last retry for a fetch errors</td></tr><tr><td>blur.controller.retry.max.mutate.delay (2000)</td><td>The ending backoff delay for the last retry for a mutate errors</td></tr><tr><td>blur.controller.retry.max.default.delay (2000)</td><td>The ending backoff delay for the last retry for a all other request errors</td></tr><tr><td>blur.gui.contr oller.port (40080)</td><td>The http status page port for the controller server, 0 for random</td></tr><tr><td>blur.controller.filtered.server.class</td><td>To intercept the calls made to the controller server and perform server side changes to the calls extend org.apache.blur.server.FilteredBlurServer.</td></tr> +</table> + <h3 id="controller-blur-env">blur-env.sh</h3> + <pre><code class="bash"># JAVA JVM OPTIONS for the controller servers, jvm tuning parameters are placed here. +# Consider adding the -XX:OnOutOfMemoryError="kill -9 %p" option to kill jvms that are failing due to memory issues. +export BLUR_CONTROLLER_JVM_OPTIONS="-Xmx1024m -Djava.net.preferIPv4Stack=true " + +# Time to sleep between controller server commands. +export BLUR_CONTROLLER_SLEEP=0.1 + +# The of controller servers to spawn per machine. +export BLUR_NUMBER_OF_CONTROLLER_SERVER_INSTANCES_PER_MACHINE=1</code></pre> + </section> + <section> + <div class="page-header"> + <h1 id="shard">Shard Server Configuration</h1> + </div> +<h3>Minimum Settings to Configure</h3> +<p> +It is highly recommended that the ulimits are increase on the server specifically: +<ul> +<li>open files</li> +<li>max user processes</li> +</ul> +<br/> +In Hadoop the dfs.datanode.max.xcievers should be increased to at least 4096 if not more. +<pre> +<code class="bash"><property> + <name>dfs.datanode.max.xcievers</name> + <value>4096</value> +</property></code></pre> +<br/> +In blur-env.sh set the cache memory for the shard processes. DO NOT over allocate this will +likely crash your server. +<pre><code class="bash">-XX:MaxDirectMemorySize=13g</code></pre> +<div class="bs-callout bs-callout-warning"><h4>Caution</h4> +Swap can kill java perform, you may want to consider disabling swap.</div> + +</p> + <h3 id="shard-blur-site">blur-site.properties</h3> + <p> + These are the default settings for the shard server that can be overridden in the blur-site.properties file. Consider increasing the various thread pool counts (*.thread.count). Also the blur.max.clause.count sets the BooleanQuery max clause count for Lucene queries. + </p> + + <h4>Default Properties</h4> + <table class="table-bordered table-striped table-condensed"> + <tr><td>Property</td><td>Description</td></tr> +<tr><td>blur.shard.hostname</td><td>The hostname for the shard, if blank the hostname is automatically detected</td></tr><tr><td>blur.shard.bind.address (0.0.0.0)</td><td>The binding address of the shard</td></tr><tr><td>blur.shard.bind.port (40020)</td><td>The default binding port of the shard server, 0 for random</td></tr><tr><td>blur.shard.command.driver.threads (16)</td><td>The number of command driver threads.</td></tr><tr><td>blur.shard.command.worker.threads (16)</td><td>The number of command worker threads.</td></tr><tr><td>blur.shard.internal.search.thread.count (16)</td><td>The number of internal lucene worker threads used to make the search call more parallel.</td></tr><tr><td>blur.shard.data.fetch.thread.count (8)</td><td>The number of fetcher threads</td></tr><tr><td>blur.shard.server.thrift.thread.count (8)</td><td>The number of the thrift threads</td></tr><tr><td>blur.shard.thrift.selector.threads (2)</td><td>The number of threads used for selector processing inside t he thrift server.</td></tr><tr><td>blur.shard.thrift.max.read.buffer.bytes (9223372036854775807)</td><td>The maximum number of bytes used for reading requests in the thrift server.</td></tr><tr><td>blur.shard.thrift.accept.queue.size.per.thread (4)</td><td>The size of the blocking queue per selector thread for passing accepted connections to the selector thread.</td></tr><tr><td>blur.shard.opener.thread.count (8)</td><td>The number of threads that are used for opening indexes</td></tr><tr><td>blur.shard.cache.max.querycache.elements (128)</td><td>The number of cached queries</td></tr><tr><td>blur.shard.cache.max.timetolive (60000)</td><td>The time to live for the cache query</td></tr><tr><td>blur.shard.filter.cache.class (org.apache.blur.manager.DefaultBlurFilterCache)</td><td>Default implementation of the blur cache filter, which is a pass through filter that does nothing</td></tr><tr><td>blur.shard.block.cache.version (v2)</td><td>By default the v2 version of the block cache is en abled</td></tr><tr><td>blur.shard.block.cache.total.size</td><td>By default the total amount of memory block cache will use is -XX:MaxDirectMemorySize - 64 MiB</td></tr><tr><td>blur.shard.blockcache.direct.memory.allocation (true)</td><td>v1 version of block cache only. By default the block cache using off heap memory</td></tr><tr><td>blur.shard.blockcache.slab.count (-1)</td><td>v1 version of block cache only. The slabs in the blockcache are automatically configured by default (-1) otherwise 1 slab equals 128MB. The auto config is detected through the MaxDirectoryMemorySize provided to the JVM</td></tr><tr><td>blur.shard.block.cache.v2.fileBufferSize (8192)</td><td>v2 version of block cache only. File buffer size, this is the buffer size used to read and write to data to HDFS. For production this will likely be increased.</td></tr><tr><td>blur.shard.block.cache.v2.cacheBlockSize (8192)</td><td>v2 version of block cache only. The is the size of the blocks in the off heap cache, it is good practice to have this match 'blur.shard.block.cache.v2.fileBufferSize'. For production this will likely be increased.</td></tr><tr><td>blur.shard.block.cache.v2.cacheBlockSize.filter (33554432)</td><td>blur.shard.block.cache.v2.cacheBlockSize.<ext>=</td></tr><tr><td>blur.shard.block.cache.v2.store (OFF_HEAP)</td><td>v2 version of block cache only. This is used to control if the block are created on or off heap. Values are OFF_HEAP | ON_HEAP</td></tr><tr><td>blur.shard.block.cache.v2.read.cache.ext</td><td>v2 version of block cache only. This specifies what file types should be cached during reads. Comma delimited list.</td></tr><tr><td>blur.shard.block.cache.v2.read.nocache.ext (fdt)</td><td>v2 version of block cache only. This specifies what file types should NOT be cached during reads. Comma delimited list.</td></tr><tr><td>blur.shard.block.cache.v2.read.default (true)</td><td>v2 version of block cache only. This specifies the default behavior if a file type is not sp ecified in the cache or nocache lists during reads. Values true | false</td></tr><tr><td>blur.shard.block.cache.v2.write.cache.ext</td><td>v2 version of block cache only. This specifies what file types should be cached during writes. Comma delimited list.</td></tr><tr><td>blur.shard.block.cache.v2.write.nocache.ext (fdt)</td><td>v2 version of block cache only. This specifies what file types should NOT be cached during writes. Comma delimited list.</td></tr><tr><td>blur.shard.block.cache.v2.write.default (true)</td><td>v2 version of block cache only. This specifies the default behavior if a file type is not specified in the cache or nocache lists during writes. Values true | false</td></tr><tr><td>blur.shard.index.compressionmode (FAST)</td><td>Sets the compression of used in the storing of the fields. Valid entries are FAST FAST_DECOMPRESSION HIGH_COMPRESSION</td></tr><tr><td>blur.shard.index.chunksize (16384)</td><td>Sets the chunksize of the compression in the storing of the f ields. Larger values may produce smaller fdt files at the small cost of fetch performance.</td></tr><tr><td>blur.shard.buffercache.8192 (67108864)</td><td>The amount of memory to be used by 8K byte buffers. Note if you change the "blur.shard.block.cache.v2.cacheBlockSize" or "blur.shard.block.cache.v2.fileBufferSize" you should adjust the buffer sizes as well as the total memory allocated. For example if you increased the "blur.shard.block.cache.v2.fileBufferSize" to 64K (65536) then this property should to "blur.shard.buffercache.65536". You can also define as many of these properties as needed.</td></tr><tr><td>blur.shard.buffercache.1024 (8388608)</td><td>The amount of memory to be used by 1K byte buffers. Note if you change the "blur.shard.block.cache.v2.cacheBlockSize" or "blur.shard.block.cache.v2.fileBufferSize" you should adjust the buffer sizes as well as the total memory allocated.</td></tr><tr><td>blur.shard.safemodedelay (5000)</td><td>The number of milliseconds to w ait for the cluster to settle once changes have ceased.</td></tr><tr><td>blur.shard.server.minimum.before.safemode.exit (0)</td><td>The number of shard servers in a cluster that have to be registered before the cluster will exit safemode.</td></tr><tr><td>blur.shard.time.between.commits (30000)</td><td>The default time between index commits.</td></tr><tr><td>blur.shard.time.between.refreshs (3000)</td><td>The default time between index refreshs.</td></tr><tr><td>blur.shard.merge.thread.count (8)</td><td>The max number of threads used during index merges.</td></tr><tr><td>blur.shard.small.merge.threshold (128000000)</td><td>The threshold for a small merge in bytes.</td></tr><tr><td>blur.max.clause.count (1024)</td><td>The maximum number of clauses in a BooleanQuery</td></tr><tr><td>blur.indexmanager.search.thread.count (8)</td><td>The number of thread used for parallel searching in the index manager</td></tr><tr><td>blur.indexmanager.mutate.thread.count (8)</td><td>The number of thre ad used for parallel mutating in the index manager</td></tr><tr><td>blur.indexmanager.facet.thread.count (8)</td><td>The number of thread used for parallel faceting in the index manager</td></tr><tr><td>blur.shard.fetchcount (110)</td><td>The fetch count per Lucene search, this fetches pointers to hits</td></tr><tr><td>blur.max.heap.per.row.fetch (10000000)</td><td>Heap limit on row fetch, once this limit has been reached the request will return</td></tr><tr><td>blur.max.records.per.row.fetch.request (1000)</td><td>The maximum number of records in a single row fetch</td></tr><tr><td>blur.gui.shard.port (40090)</td><td>The http status page port for the shard server, 0 for random</td></tr><tr><td>blur.shard.filtered.server.class</td><td>To intercept the calls made to the shard server and perform server side changes to the calls extend org.apache.blur.server.FilteredBlurServer.</td></tr><tr><td>blur.shard.blurindex.class</td><td>Defines the blur index class to be used to handle index r equests. This class has to extend org.apache.blur.manager.writer.BlurIndex. This can be defined globally as well as per table.</td></tr><tr><td>blur.shard.read.interceptor</td><td>Defines the blur read interceptor class that can mask data from query results as well as data fetches.</td></tr><tr><td>blur.lucene.fst.bytearray.factory</td><td>Defines the byte array factory class that blur will use to manage the FST trees in Lucene (extends org.apache.blur.lucene.fst.ByteArrayFactory).</td></tr><tr><td>blur.shard.queue.max.pause.time.when.empty (1000)</td><td>The maximum amount of time to pause before checking the queue for RowMutations.</td></tr><tr><td>blur.shard.queue.max.writer.lock.time (5000)</td><td>The maximum amount of time that the queue can lock the writer before committing. NOTE: Any other writer event will cause the queue to release it's lock on the writer.</td></tr><tr><td>blur.shard.queue.max.queue.batch.size (100)</td><td>The maximum number of RowMutations the writer can drain from the queue at a time.</td></tr><tr><td>blur.shard.queue.max.inmemory.length (100)</td><td>The maximum number of RowMutations that can exist in the inmemory block queue any point in time. NOTE: This is PER SHARD.</td></tr><tr><td>blur.shard.deep.paging.cache.size (1000)</td><td>The number of deep paging cache entries kept in memory for faster deep paging.</td></tr><tr><td>blur.shard.distributed.layout.factory.class</td><td>Defines the blur layout factor class to use for managing how shards are layed out across the cluster.</td></tr> + </table> + + <h3 id="shard-blur-env">blur-env.sh</h3> + <pre><code class="bash"># JAVA JVM OPTIONS for the shard servers, jvm tuning parameters are placed here. +export BLUR_SHARD_JVM_OPTIONS="-Xmx1024m -Djava.net.preferIPv4Stack=true -XX:MaxDirectMemorySize=256m " + +# Time to sleep between shard server commands. +export BLUR_SHARD_SLEEP=0.1 + +# The of shard servers to spawn per machine. +export BLUR_NUMBER_OF_SHARD_SERVER_INSTANCES_PER_MACHINE=1</code></pre> + +<h3 id="block-cache">Block Cache</h3> +<h4>Why</h4> +<p>HDFS is a great filesystem for streaming large amounts data across large scale clusters. However the random access latency is typically the same performance you would get in reading from a local drive if the data you are trying to access is not in the operating systems file cache. In other words every access to HDFS is similar to a local read with a cache miss. There have been great performance boosts in HDFS over the past few years but it still can't perform at the level that a search engine needs.</p> +<p>Now you might be thinking that Lucene reads from the local hard drive and performs great, so why wouldn't HDFS perform fairly well on it's own? However most of time the Lucene index files are cached by the operating system's file system cache. So Blur has it's own file system cache allows it to perform low latency data look-ups against HDFS.</p> + +<h3 id="block-cache-v2">V2 Block Cache Configuration</h3> +<h4>How</h4> +<p>The Google <a href="http://code.google.com/p/concurrentlinkedhashmap/";>concurrentlinkedhashmap</a> library is at the center of the block cache in the shard servers. In version 2, which is enabled by default, the slab allocation is no longer used. <a href="http://mail-archives.apache.org/mod_mbox/incubator-blur-dev/201310.mbox/%3CCAB6tTr0Nr2aDLc4kkHoeqiO-utwzBAhb=Ru==gmhqry4axp...@mail.gmail.com%3E";>Here</a> is a discussion of the motivations behind the rewrite.</p> + +<p>Below are the properties related to V2 of the block cache.</p> + +<table class="table-bordered table-striped table-condensed"> +<tr><td nowrap="1">blur.shard.block.cache.total.size</td><td> +<p>This is used to limit the amount of off heap cache size. By default the cache is 64MB less than the -XX:MaxDirectMemorySize, +so if you want the block cache to use less than that amount then set this value.</p></td></tr> + +<tr><td nowrap="1">blur.shard.block.cache.v2.fileBufferSize</td><td> +<p>This is the size of the buffer when accessing hdfs, by default it is set to 8K. However in most systems this should probably be increased to something closer to 64K. Use the "fstune" command in the shell to help figure out what the best buffer size should be in your system.</p></td></tr> + +<tr><td nowrap="1">blur.shard.block.cache.v2.cacheBlockSize</td><td> +<p>This is the size of the cache entry for any file that is NOT explicitly defined. Most of the time you are going to want this value to equal the "blur.shard.block.cache.v2.fileBufferSize" value.</p></td></tr> + +<tr><td nowrap="1">blur.shard.block.cache.v2.cacheBlockSize.<ext></td><td> +<p>This is the size of the cache entry for any file that has the given extension. By default "filter" is the only file that has a none default cache block size, it's current value is 32MB. This means that unless file is larger than 32MB in size, it will be stored as a single value in the cache. For cached filters this is required for performance during the transversal of the logical bitset stored in the file.</p></td></tr> + +<tr><td nowrap="1">blur.shard.block.cache.v2.store</td><td> +<p>This property defines how the cache will be stored, by default it's off heap. This means that it is not accounted for in the used heap section that you can find in jconsole or visualvm. However you can track it's size through the "top" command in the shell, MBeans in jconsole, or the metrics call via the Blur thrift API.<br/><br/>Unless you are using a specialized JVM or are debugging problem this should remain off heap, however if you would like to use the cache as on heap allocated blocks change this value to ON_HEAP.</p></td></tr> + +blur.shard.block.cache.v2.write.cache.ext= +blur.shard.block.cache.v2.write.nocache.ext=fdt + +<tr><td nowrap="1">blur.shard.block.cache.v2.read.default</td><td> +<p>This property defines the default action to cache or not to cache the data during a read operation. By default this is true. This will be the action taken if the file extension is not found in either the "blur.shard.block.cache.v2.read.cache.ext" property or the "blur.shard.block.cache.v2.read.nocache.ext" property.</p></td></tr> + +<tr><td nowrap="1">blur.shard.block.cache.v2.read.cache.ext</td><td> +<p>This property defines a comma separated list of file extensions that are to be cached during a read operations.</p></td></tr> + +<tr><td nowrap="1">blur.shard.block.cache.v2.read.nocache.ext</td><td> +<p>This property defines a comma separated list of file extensions that are NOT to be cached during a read operations. If the file extension is in the "blur.shard.block.cache.v2.read.cache.ext" property, it will have no effect in this list.</p></td></tr> + +<tr><td nowrap="1">blur.shard.block.cache.v2.write.default</td><td> +<p>This property defines the default action to cache or not to cache the data during a write operation. By default this is true. This will be the action taken if the file extension is not found in either the "blur.shard.block.cache.v2.write.cache.ext" property or the "blur.shard.block.cache.v2.write.nocache.ext" property.</p></td></tr> + +<tr><td nowrap="1">blur.shard.block.cache.v2.write.cache.ext</td><td> +<p>This property defines a comma separated list of file extensions that are to be cached during a write operations.</p></td></tr> + +<tr><td nowrap="1">blur.shard.block.cache.v2.write.nocache.ext</td><td> +<p>This property defines a comma separated list of file extensions that are NOT to be cached during a write operations. If the file extension is in the "blur.shard.block.cache.v2.write.cache.ext" property, it will have no effect in this list.</p></td></tr> + +</table> + + <h3 id="block-cache-v1">V1 Block Cache Configuration</h3> + <h4>How</h4> + <p>On shard server start-up Blur creates 1 or more block cache slabs blur.shard.blockcache.slab.count that are each 128 MB in size. These slabs can be allocated on or off the heap blur.shard.blockcache.direct.memory.allocation. Each slab is broken up into 16,384 blocks with each block size being 8K. Then on the heap there is a concurrent LRU cache that tracks what blocks of what files are in which slab(s) at what offset. So the more slabs of cache you create the more entries there will be in the LRU thus more heap.</p> + <h4>Configuration</h4> + <p>Scenario: + + Say the shard server(s) that you are planning to run Blur on have 32G of ram. These machines are probably also running HDFS data nodes as well with very high xcievers (dfs.datanode.max.xcievers in hdfs-site.xml) say 8K. If the data nodes are configured with 1G of heap then they may consume up to 4G of memory due to the high thread count because of the xcievers. Next let's say you configure Blur to 4G of heap as well, and you want to use 12G of off heap cache.</p> + <h5>Auto Configuration</h5> + <p>In the blur-env.sh file you would need to change BLUR_SHARD_JVM_OPTIONS to include "-XX:MaxDirectMemorySize=12g" and possibly "-XX:+UseLargePages" depending on your Linux setup. If you leave the blur.shard.blockcache.slab.count to the default -1 the shard startup will automatically detect the -XX:MaxDirectMemorySize size and automatically use almost all of the memory. By default the JVM has 64m in reserve for direct memory so by default Blur leaves at least that amount available to the JVM.</p> + <h5>Custom Configuration</h5> + <p>Again in the blur-env.sh file you would need to change BLUR_SHARD_JVM_OPTIONS to include "-XX:MaxDirectMemorySize=13g" and possibly "-XX:+UseLargePages" depending on your Linux setup. I set the MaxDirectMemorySize to more than 12G to make sure we don't hit the maximum limit and cause a OOM exception, this does not reserve 13G it's a control to not allow more than that. Below is a working example, it also contains GC logging and GC configuration:</p> + <pre><code class="bash">export BLUR_SHARD_JVM_OPTIONS="-XX:MaxDirectMemorySize=13g \ + -XX:+UseLargePages \ + -Xms4g \ + -Xmx4g \ + -Xmn512m \ + -XX:+UseCompressedOops \ + -XX:+UseConcMarkSweepGC \ + -XX:+CMSIncrementalMode \ + -XX:CMSIncrementalDutyCycleMin=10 \ + -XX:CMSIncrementalDutyCycle=50 \ + -XX:ParallelGCThreads=8 \ + -XX:+UseParNewGC \ + -XX:MaxGCPauseMillis=200 \ + -XX:GCTimeRatio=10 \ + -XX:+DisableExplicitGC \ + -verbose:gc \ + -XX:+PrintGCDetails \ + -XX:+PrintGCDateStamps \ + -Xloggc:$BLUR_HOME/logs/gc-blur-shard-server_`date +%Y%m%d_%H%M%S`.log"</code></pre> + <p>Next you will need to setup blur-site.properties by changing blur.shard.blockcache.slab.count to 96. This is telling blur to allocate 96 128MB slabs of memory at shard server start-up. Note, that the first time you do this that the shard servers may take long time to allocate the memory. This is because the OS could be using most of that memory for it's own filesystem caching and it will need to unload it which may cause some IO due the cache synching to disk.</p> + <p>Also the blur.shard.blockcache.direct.memory.allocation is set to true by default, this will tell the JVM to try and allocate the memory off heap. If you want to run the slabs in the heap (which is not recommended) set this value to false.</p> + </section> + <section> + <div class="page-header"> + <h1 id="metrics">Metrics</h1> + </div> + <p class="lead">Internally Blur uses the Metrics library from Coda Hale (<a href="http://metrics.codahale.com/";>http://metrics.codahale.com/</a>). So by default all metrics are available through JMX here is a screenshot of what is available in the Shard server.</p> + <h3 id="shard-mbean">Shard Server - MBean Screenshot</h3> + <img src="resources/img/BlurShardServer.png" style="max-width:1000px"/> + <h3 id="reporters">Configuring Other Reporters</h3> + <p class="lead">New reporters can be added configured in the blur-site.properties. Multiple reporters can be configured.</p> + <h4>Example</h4> + <pre><code class="bash">blur.metrics.reporters=GangliaReporter +blur.metrics.reporter.ganglia.period=3 +blur.metrics.reporter.ganglia.unit=SECONDS +blur.metrics.reporter.ganglia.host=ganglia1 +blur.metrics.reporter.ganglia.port=8649</code></pre> + <h4>Reporters to Enable</h4> + <pre><code class="bash">blur.metrics.reporters=[ConsoleReporter,CsvReporter,GangliaReporter,GraphiteReporter]</code></pre> + <h4>ConsoleReporter</h4> + <pre><code class="bash">blur.metrics.reporter.console.period=[5] +blur.metrics.reporter.console.unit=[NANOSECONDS,MICROSECONDS,MILLISECONDS,SECONDS,MINUTES,HOURS,DAYS]</code></pre> + <h4>CsvReporter</h4> + <pre><code class="bash">blur.metrics.reporter.csv.period=[5] +blur.metrics.reporter.csv.unit=[NANOSECONDS,MICROSECONDS,MILLISECONDS,SECONDS,MINUTES,HOURS,DAYS] +blur.metrics.reporter.csv.outputDir=[.]</code></pre> + <h4>GangliaReporter</h4> + <pre><code class="bash">blur.metrics.reporter.ganglia.period=[5] +blur.metrics.reporter.ganglia.unit=[NANOSECONDS,MICROSECONDS,MILLISECONDS,SECONDS,MINUTES,HOURS,DAYS] +blur.metrics.reporter.ganglia.host=[localhost] +blur.metrics.reporter.ganglia.port=[-1] +blur.metrics.reporter.ganglia.prefix=[""] +blur.metrics.reporter.ganglia.compressPackageNames=[false]</code></pre> + <h4>GraphiteReporter</h4> + <pre><code class="bash">blur.metrics.reporter.graphite.period=[5] +blur.metrics.reporter.graphite.unit=[NANOSECONDS,MICROSECONDS,MILLISECONDS,SECONDS,MINUTES,HOURS,DAYS] +blur.metrics.reporter.graphite.host=[localhost] +blur.metrics.reporter.graphite.port=[-1] +blur.metrics.reporter.graphite.prefix=[""]</code></pre> + </section> + </div> + </div> + </div> + + <!-- jQuery (necessary for Bootstrap's JavaScript plugins) --> + <script src="resources/js/jquery-2.0.3.min.js"></script> + <!-- Include all compiled plugins (below), or include individual files as needed --> + <script src="resources/js/bootstrap.min.js"></script> + <!-- Enable responsive features in IE8 with Respond.js (https://github.com/scottjehl/Respond) --> + <script src="resources/js/respond.min.js"></script> + <script src="resources/js/docs.js"></script> + </body> +</html> Added: websites/staging/blur/trunk/content/blur/docs/0.2.4/console.html ============================================================================== --- websites/staging/blur/trunk/content/blur/docs/0.2.4/console.html (added) +++ websites/staging/blur/trunk/content/blur/docs/0.2.4/console.html Thu Jan 1 17:22:30 2015 @@ -0,0 +1,291 @@ +<!DOCTYPE html> +<!-- + 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. +--> +<html> + <head> + <title>Apache Blur (Incubator) Documentation</title> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <!-- Bootstrap --> + <link href="resources/css/bootstrap.min.css" rel="stylesheet" media="screen"> + <link href="resources/css/bs-docs.css" rel="stylesheet" media="screen"> + </head> + <body> + <div class="navbar navbar-inverse navbar-fixed-top"> + <div class="container"> + <div class="navbar-header"> + <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse"> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + </button> + <a class="navbar-brand" href="http://incubator.apache.org/blur";>Apache Blur (Incubator)</a> + </div> + <div class="collapse navbar-collapse"> + <ul class="nav navbar-nav"> + <li><a href="index.html">Main</a></li> + <li><a href="getting-started.html">Getting Started</a></li> + <li><a href="platform.html">Platform</a></li> + <li><a href="data-model.html">Data Model</a></li> + <li><a href="cluster-setup.html">Cluster Setup</a></li> + <li><a href="using-blur.html">Using Blur</a></li> + <li><a href="Blur.html">Blur API</a></li> + <li class="active"><a href="console.html">Console</a></li> + </ul> + </div> + </div> + </div> + <div class="container bs-docs-container"> + <div class="row"> + <div class="col-md-3"> + <div class="bs-sidebar hidden-print affix" role="complementary"> + <ul class="nav bs-sidenav"> + <li><a href="#configuration">Configuration</a></li> + <li><a href="#security">Security</a></li> + <li><a href="#dev">Dev Mode</a></li> + </ul> + </div> + </div> + <div class="col-md-9" role="main"> + <section> + <div class="page-header"> + <h1 id="configuration">Configuration</h1> + </div> + <p class="lead"> + Below you will find a list of available options and their appropriate defaults for the Blur Console component. All options can be set in the blur-site.properties file. + </p> + <h3>Base Settings</h3> + <table class="table table-bordered table-striped table-condensed"> + <thead> + <tr> + <th>Property</th> + <th>Default</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td>blur.console.port</td> + <td>8080</td> + <td>The port that the embedded Jetty server will run on when started.</td> + </tr> + <tr> + <td>blur.console.authentication.provider</td> + <td>org.apache.blur.console.providers.AllAuthenticated</td> + <td>The class name that will implement the IAuthenticationProvider interface and provide security to the tool.</td> + </tr> + <tr> + <td>blur.console.authorization.provider</td> + <td>org.apache.blur.console.providers.EmptyAuthorization</td> + <td>The class name that will implement the IAuthorizationProvider interface and provide authorization to the data.</td> + </tr> + <tr> + <td>blur.console.authentication.roles.admin</td> + <td>admin</td> + <td>Used to aide in the mapping of custom provider roles to console roles. This maps the administrator role.</td> + </tr> + <tr> + <td>blur.console.authentication.roles.searcher</td> + <td>searcher</td> + <td>Used to aide in the mapping of custom provider roles to console roles. This maps the searcher role.</td> + </tr> + <tr> + <td>blur.console.authentication.roles.manager</td> + <td>manager</td> + <td>Used to aide in the mapping of custom provider roles to console roles. This maps the manager role.</td> + </tr> + <tr> + <td>blur.console.refreshtime</td> + <td>5000</td> + <td>Time to indicate how long calls to Blur should be cached (in milliseconds).</td> + </tr> + <tr> + <td>blur.console.ssl.enabled</td> + <td>false</td> + <td>Whether to enable ssl directly in the console.</td> + </tr> + <tr> + <td>blur.console.ssl.hostname.match</td> + <td>true</td> + <td>Indicates if the hostname should match an incoming certificate.</td> + </tr> + <tr> + <td>blur.console.ssl.keystore.path</td> + <td></td> + <td>The path to a keystore for ssl.</td> + </tr> + <tr> + <td>blur.console.ssl.keystore.password</td> + <td></td> + <td>The password to the keystore (used with blur.console.ssl.keystore.path).</td> + </tr> + <tr> + <td>blur.console.ssl.truststore.path</td> + <td></td> + <td>The path to a truststore for ssl.</td> + </tr> + <tr> + <td>blur.console.ssl.truststore.password</td> + <td></td> + <td>The password to the truststore (used with blur.console.ssl.truststore.path).</td> + </tr> + </tbody> + </table> + <h3>Included Security Provider Settings</h3> + <table class="table table-bordered table-striped table-condensed"> + <thead> + <tr> + <th>Provider</th> + <th>Property</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td>org.apache.blur.console.providers.TomcatUsers</td> + <td>blur.console.authentication.provider.tomcat.usersfile</td> + <td>The location of the file containing the users, passwords, and roles.</td> + </tr> + <tr> + <td>org.apache.blur.console.providers.GlobalJsonAuthorization</td> + <td>blur.console.authorization.provider.globaljson.file</td> + <td>The location of the file containing the access control to the data for various "users" that can be used during searching.</td> + </tr> + </tbody> + </table> + </section> + <section> + <div class="page-header"> + <h1 id="security">Security</h1> + </div> + <p class="lead"> + Blur Console itself provides some hooks and default implementations to allow for authentication and authorization to both the tool as well as the data. + </p> + <h3>Authentication Provider</h3> + <p> + The Authentication Provider (interface org.apache.blur.console.providers.IAuthenticationProvider) provides the ability to lock down the console tool to privileged users. The interface + allows for logging in, retrieving a User, and providing roles for that user that give access to functionality within the tool. + </p> + <h3>Authorization Provider</h3> + <p> + The Authorization Provider (interface org.apache.blur.console.providers.IAuthorizationProvider) provides the ability to apply Blur level access control to the users of the console. + </p> + <h3>Roles</h3> + <table class="table table-bordered table-striped table-condensed"> + <thead> + <tr> + <th>Role</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td>admin</td> + <td>Grants permission to ALL functionality of the console.</td> + </tr> + <tr> + <td>manager</td> + <td>Grants permission to Read, Search, and perform destructive actions (i.e. Disable/Delete tables).</td> + </tr> + <tr> + <td>searcher</td> + <td>Grants permission to Read and Search</td> + </tr> + </tbody> + </table> + + <h3>Available Implementations</h3> + <table class="table table-bordered table-condensed table-striped"> + <thead> + <tr> + <th>Provider</th> + <th>Interface</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td>org.apache.blur.console.providers.AllAuthenticated</td> + <td>IAuthenticationProvider</td> + <td>Allows anyone to access all functionality of the console. Bypasses user login.</td> + </tr> + <tr> + <td>org.apache.blur.console.providers.EmptyAuthorization</td> + <td>IAuthorizationProvider</td> + <td>This provider does not set up any attributes for Blur security for the users of the console.</td> + </tr> + <tr> + <td>org.apache.blur.console.providers.GlobalJsonAuthorization</td> + <td>IAuthorizationProvider</td> + <td> + Provides a list of users and their security attributes defined in a JSON file. These users can be selected from the search screen and will have their access applied during searching. + <br/> + <code> + "user1":{ + <br/> + "attribute1":"foo,bar,baz", + <br/> + "attribute2":"zzzzz" + <br/> + }, + <br/> + "user2":{ + <br/> + "attribute1":"foo", + <br/> + "attribute2":"12345" + <br/> + } + </code> + </td> + </tr> + <tr> + <td>org.apache.blur.console.providers.TomcatUsers</td> + <td>IAuthenticationProvider</td> + <td>Provides a list of users, roles, and passwords in an xml file. The format of this file is identical to a tomcat-users file.</td> + </tr> + </tbody> + </table> + <div class="alert alert-info"> + <strong>Note:</strong> + Custom Providers can be created by implementing the interfaces, placing the jar in the runtime blur lib directory, and adding the classnames to the config file. + </div> + <div class="alert alert-info"> + <strong>Note:</strong> + Configuring the same class for authentication and authorization providers will reuse the same instance for both. + </div> + </section> + <section> + <div class="page-header"> + <h1 id="dev">Dev Mode</h1> + </div> + <p class="lead"> + To try the console without having a full Blur Cluster setup you can add --dev to the arguments when starting the console. This will run a MiniCluster in the + process and attach to it. In order to access the running MiniCluster you will need to grab the controller uri from the Dashboard and access through the shell. + </p> + </section> + </div> + </div> + + <!-- jQuery (necessary for Bootstrap's JavaScript plugins) --> + <script src="resources/js/jquery-2.0.3.min.js"></script> + <!-- Include all compiled plugins (below), or include individual files as needed --> + <script src="resources/js/bootstrap.min.js"></script> + <!-- Enable responsive features in IE8 with Respond.js (https://github.com/scottjehl/Respond) --> + <script src="resources/js/respond.min.js"></script> + <script src="resources/js/docs.js"></script> + </body> +</html>
