From a1fedecaed90b7c5aa1132dfd4c7d4f15f862aa2 Mon Sep 17 00:00:00 2001 From: Misty Stanley-Jones Date: Tue, 16 Jun 2015 14:13:00 +1000 Subject: [PATCH] HBASE-13907 Document how to deploy a coprocessor --- src/main/asciidoc/_chapters/cp.adoc | 59 ++++++++++++++++++++++++++++++++++++- 1 file changed, 58 insertions(+), 1 deletion(-) diff --git a/src/main/asciidoc/_chapters/cp.adoc b/src/main/asciidoc/_chapters/cp.adoc index a99e903..aa99bc5 100644 --- a/src/main/asciidoc/_chapters/cp.adoc +++ b/src/main/asciidoc/_chapters/cp.adoc @@ -118,6 +118,7 @@ Ties are broken arbitrarily. You can load a coprocessor on a specific table via a table attribute. The following example will load the `FooRegionObserver` observer when table `t1` is read or re-read. +[[load_coprocessor_using_shell]] .Load a Coprocessor On a Table Using HBase Shell ==== ---- @@ -187,12 +188,66 @@ DESCRIPTION ENABLED WARNING: There is no guarantee that the framework will load a given coprocessor successfully. For example, the shell command neither guarantees a jar file exists at a particular location nor verifies whether the given class is actually contained in the jar file. +== Guidelines For Deploying A Coprocessor + +Bundling Coprocessors:: + You can bundle all classes for a coprocessor into a + single JAR on the RegionServer's classpath, for easy deployment. Otherwise, + place all dependencies on the RegionServer's classpath so that they can be + loaded during RegionServer start-up. The classpath for a RegionServer is set + in the RegionServer's `hbase-env.sh` file. +Automating Deployment:: + You can use a tool such as Puppet, Chef, or + Ansible to ship the JAR for the coprocessor to the required location on your + RegionServers' filesystems and restart each RegionServer, to automate + coprocessor deployment. Details for such set-ups are out of scope of this + document. +Updating a Coprocessor:: + Deploying a new version of a given coprocessor is not as simple as disabling it, + replacing the JAR, and re-enabling the coprocessor. This is because you cannot + reload a class in a JVM unless you delete all the current references to it. + Since the current JVM has reference to the existing coprocessor, you must restart + the JVM, by restarting the RegionServer, in order to replace it. This behavior + is not expected to change. +Coprocessor Logging:: + The Coprocessor framework does not provide an API for logging beyond standard Java + logging. +Coprocessor Configuration:: + If you do not want to load coprocessors from the HBase Shell, you can add their configuration + properties to `hbase-site.xml`. In <>, two arguments are + set: `arg1=1,arg2=2`. These could have been added to `hbase-site.xml` as follows: +[source,xml] +---- + + arg1 + 1 + + + arg2 + 2 + +---- +Then you can read the configuration using code like the following: +[source,java] +---- +RegionCoprocessorEnvironment env = (RegionCoprocessorEnvironment) e; +Configuration conf = env.getConfiguration(); +String arg1 = conf.get("arg1"); // no default provided +this.arg1 = Bytes.toBytes(arg1); +String arg2 = conf.get("arg1", "3"); // defaults to 3 if not set in hbase-site.xml +this.arg2 = Bytes.toBytes(arg2); +---- + +If you load a coprocessor from `hbase-site.xml` and then load the same coprocessor +again using HBase Shell, it will be loaded a second time. The same class will +exist twice, and the second instance will have a higher ID (and thus a lower priority). +The effect is that the duplicate coprocessor is effectively ignored. + == Check the Status of a Coprocessor To check the status of a coprocessor after it has been configured, use the `status` HBase Shell command. ---- - hbase(main):020:0> status 'detailed' version 0.92-tm-6 0 regionsInTransition @@ -216,6 +271,8 @@ coprocessors=[AggregateImplementation] 0 dead servers ---- + + == Monitor Time Spent in Coprocessors HBase 0.98.5 introduced the ability to monitor some statistics relating to the amount of time spent executing a given coprocessor. -- 2.3.2 (Apple Git-55)