Skip to content
Tutorials Center
My learning

Topics

Lesson 25 of 36 ยท Filters and Coprocessors

Coprocessors: Observers

Understand HBase observer coprocessors: RegionObserver, MasterObserver and WALObserver hooks, what they are good for, the risks, and a runnable Java hook model.

A coprocessor is code that runs inside the HBase server processes, next to the data. HBase has two kinds. Observers are like database triggers: HBase calls them before or after events such as a Put, Get or region split. Endpoints are like stored procedures: the client calls them explicitly and gets a result (Endpoint Coprocessors).

Observers let you add behavior to the server without changing HBase: audit logs, access control, secondary-index maintenance, automatic validation. They are also one of the easiest ways to hurt a cluster, because your code runs on the critical path of every request. This lesson explains the hook model and the rules for using it safely.

HBase cannot run in the live editors. Coprocessor classes are shown as read-only Java against the HBase 2.x API. The runnable programs are labelled stand-ins that model the "hook around an operation" idea in plain Java.

The observer interfaces

HBase 2.x defines these server-side observer interfaces (in org.apache.hadoop.hbase.coprocessor):

Interface Runs in Typical hooks
RegionObserver Each region of a table prePut, postPut, preGetOp, postGetOp, preDelete, preScannerOpen, postScannerNext, preFlush, postCompact
MasterObserver The HMaster preCreateTable, postDeleteTable, preModifyTable, preBalance, postMove
RegionServerObserver Each region server preRollWALWriterRequest, replication hooks
WALObserver The write-ahead log preWALWrite, postWALWrite

Since HBase 2.0 a coprocessor class implements RegionCoprocessor (or the matching one) and returns its observers from getRegionObserver(). Hooks receive an ObserverContext, which carries the environment and lets you call bypass() to skip the default action or complete() to skip remaining coprocessors.

A real observer (read-only)

This observer rejects any Put whose d:status value is not one of three allowed words, and records a count of accepted writes:

Java
public class StatusGuard implements RegionCoprocessor, RegionObserver {
    private static final Set<String> ALLOWED = Set.of("new", "ok", "error");
    private final LongAdder accepted = new LongAdder();

    @Override
    public Optional<RegionObserver> getRegionObserver() { return Optional.of(this); }

    @Override
    public void prePut(ObserverContext<RegionCoprocessorEnvironment> ctx, Put put,
                       WALEdit edit, Durability durability) throws IOException {
        List<Cell> cells = put.get(Bytes.toBytes("d"), Bytes.toBytes("status"));
        for (Cell c : cells) {
            String v = Bytes.toString(CellUtil.cloneValue(c));
            if (!ALLOWED.contains(v)) {
                throw new DoNotRetryIOException("Invalid status: " + v);   // client sees the error
            }
        }
        accepted.increment();
    }
}

Throwing a DoNotRetryIOException makes the Put fail and tells the client not to retry. Any other exception can cause retries and, if it repeats, a coprocessor being removed by the server (the default for failing coprocessors is to abort the server in older configurations; set hbase.coprocessor.abortonerror deliberately).

Loading a coprocessor

Two routes:

  • System-wide: in hbase-site.xml set hbase.coprocessor.region.classes (or master.classes) to the class name with the JAR on the server classpath. Restart needed.
  • Per table: attach the JAR from HDFS to one table's descriptor, no cluster restart:
TEXT
alter 'events', METHOD => 'table_att',
  'coprocessor' => 'hdfs:///jars/statusguard.jar|com.example.StatusGuard|1001|'

The pieces are path|class|priority|arguments. Priority orders multiple coprocessors; lower numbers run first.

Modeling the hook idea

The stand-in below wraps a "table" in an observer chain with prePut and postPut. The pre-hook may veto a write, the post-hook counts or copies it. This is exactly how an index-maintenance observer works, except real HBase puts the chain inside the region.

Java Pre and post hooks around a Put (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

The rejected write never reaches the data or the index, and the index table stays consistent with the main table because it is updated from postPut. In real HBase, the main write and the index write are still two separate operations; a crash between them can leave the index behind.

Rules for safe observers

  • Be fast. Hooks run synchronously on the request handler thread. A slow prePut slows every write to the region.
  • Never block on remote calls (another table, an external service) without strict timeouts. A stuck handler can exhaust the handler pool and make the region server unresponsive.
  • Be careful with exceptions. Throw DoNotRetryIOException for deliberate rejections; catch and log everything else if it must not break the write.
  • Be idempotent. WAL replay after a failure can call hooks again for the same data.
  • Test with a mini cluster, deploy with a canary table first.
  • Prefer something else when you can. Many teams avoid custom coprocessors: they couple your code to HBase internals and each HBase upgrade can break them. Validation in the application, a stream processor for index maintenance, or Apache Phoenix for secondary indexes are often safer.
sequenceDiagram
  participant C as Client
  participant RS as Region server
  participant O as Observer
  participant W as WAL and MemStore
  C->>RS: Put
  RS->>O: prePut
  O-->>RS: ok (or exception to veto)
  RS->>W: write
  RS->>O: postPut
  RS-->>C: result

prePut can veto; postPut runs after the data is written but before the client gets an answer.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How is an observer different from an endpoint coprocessor?

    Observers work like triggers on server events; endpoints are RPC-style methods the client invokes.
  2. 2. Which exception tells the client not to retry a rejected Put?

    DoNotRetryIOException marks a permanent failure so the client does not keep retrying.
  3. 3. Why can a slow prePut hook hurt the whole region server?

    Hooks run synchronously on handler threads; if they block, handlers run out and requests queue up.
  4. 4. What is a safe way to load a coprocessor for one table without restarting the cluster?

    A table-level coprocessor attribute with the JAR path, class and priority loads the code for that table.

Summary

  • Observers are server-side triggers: RegionObserver, MasterObserver, WALObserver and others.
  • prePut can veto; postPut can maintain side data such as indexes.
  • Hooks run on the request path: keep them fast, non-blocking and idempotent.
  • Load per table with a table attribute or cluster-wide in hbase-site.xml.
  • Treat custom coprocessors as a last resort.

Next: Endpoint Coprocessors and Aggregation