From 3bd3ea939b58cb1cd32fcd6b974b29311359160d 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 | 60 ++++++++++++++++++++++++++++++++++++- 1 file changed, 59 insertions(+), 1 deletion(-) diff --git a/src/main/asciidoc/_chapters/cp.adoc b/src/main/asciidoc/_chapters/cp.adoc index a99e903..44b2c2c 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,67 @@ 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. You can also set a dynamic path in + `hbase-site.xml` using the `hbase.dynamic.jars.dir` property in `hbase-site.xml`, + and place the JAR or dependencies into this directory. +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. Alternately, you can include the coprocessor version in its + classname. This way you can unload the old coprocessor and load the new one, + without restarting the RegionServer. However, the old version will remain in memory, + so this solution is a temporary one, and restarting will eventually be necessary. +Coprocessor Logging:: + The Coprocessor framework does not provide an API for logging beyond standard Java + logging. You can log to the location specified in the system property `HBASE_LOG_DIR`, + which is set in the RegionServer's `hbase-env.sh` file. +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); +---- + == 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 +272,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)