hbase-metrics-api/README.txt

   1 Overview
   2 ========
   3 hbase-metrics and hbase-metrics-api are two modules that define and implement the "new" metric
   4 system used internally within HBase. These two modules (and some other code in hbase-hadoop2-compat)
   5 module are referred as "HBase metrics framework".
   6
   7 HBase-metrics-api Module
   8 ========================
   9 HBase Metrics API (hbase-metrics-api) contains the interface
  10 that HBase exposes internally and to third party code (including coprocessors). It is a thin
  11 abstraction over the actual implementation for backwards compatibility guarantees. The source
  12 / binary and other compatibility guarantees are for "LimitedPrivate API" (see [1] for an
  13 explanation).
  14
  15 The metrics API in this hbase-metrics-api module is inspired by the Dropwizard metrics 3.1 API
  16 (See [2]). It is a subset of the API only containing metrics collection. However, the implementation
  17 is HBase-specific and provided in hbase-metrics module. All of the classes in this module is
  18 HBase-internal. See the latest documentation of Dropwizard metrics for examples of defining / using
  19 metrics.
  20
  21
  22 HBase-metrics Module
  23 ====================
  24 hbase-metrics module contains implementation of the "HBase Metrics API", including MetricRegistry,
  25 Counter, Histogram, etc. These are highly concurrent implementations of the Metric interfaces.
  26 Metrics in HBase are grouped into different sets (like WAL, RPC, RegionServer, etc). Each group of
  27 metrics should be tracked via a MetricRegistry specific to that group. Metrics can be dynamically
  28 added or removed from the registry with a name. Each Registry is independent of the other
  29 registries and will have it's own JMX context and MetricRecord (when used with Metrics2).
  30
  31
  32 MetricRegistry's themselves are tracked via a global registry (of MetricRegistries) called
  33 MetricRegistries. MetricRegistries.global() can be used to obtain the global instance.
  34 MetricRegistry instances can also be dynamically registered and removed. However, unlike the
  35 MetricRegistry, MetricRegistries does reference counting of the MetricRegistry instances. Only
  36 Metrics in the MetricRegistry instances that are in the global MetricRegistry are exported to the
  37 metric sinks or JMX.
  38
  39
  40 Coprocessor Metrics
  41 ===================
  42 HBase allows custom coprocessors to track and export metrics using the new framework.
  43 Coprocessors and other third party code should only use the classes and interfaces from
  44 hbase-metrics-api module and only the classes that are marked with InterfaceAudience.LimitedPrivate
  45 annotation. There is no guarantee on the compatibility requirements for other classes.
  46
  47 Coprocessors can obtain the MetricRegistry to register their custom metrics via corresponding
  48 CoprocessorEnvironment context. See ExampleRegionObserverWithMetrics and
  49 ExampleMasterObserverWithMetrics classes in hbase-examples module for usage.
  50
  51
  52 Developer Notes
  53 ===============
  54 Historically, HBase has been using Hadoop's Metrics2 framework [3] for collecting and reporting the
  55 metrics internally. However, due to the difficultly of dealing with the Metrics2 framework, HBase is
  56 moving away from Hadoop's metrics implementation to its custom implementation. The move will happen
  57 incrementally, and during the time, both Hadoop Metrics2-based metrics and hbase-metrics module
  58 based classes will be in the source code. All new implementations for metrics SHOULD use the new
  59 API and framework.
  60
  61 Examples of the new framework can be found in MetricsCoprocessor and MetricsRegionServerSourceImpl
  62 classes. See HBASE-9774 [4] for more context.
  63
  64 hbase-metrics module right now only deals with metrics tracking and collection. It does not do JMX
  65 reporting or reporting to console, ganglia, opentsdb, etc. We use Hadoop's Metrics2 for reporting
  66 metrics to different sinks or exporting via JMX. However, this is contained within the
  67 hbase-hadoop2-compat module completely, so that rest of the code does not know anything about the
  68 Metrics2 dependency. HBaseMetrics2HadoopMetricsAdapter is the adapter that can collect metrics
  69 in a MetricRegistry using the metric2 MetricsCollector / MetricRecordBuilder interfaces.
  70 GlobalMetricRegistriesSource is the global Metrics2 Source that collects all of the metrics in all
  71 of the metric registries in the MetricRegistries.global() instance.
  72
  73
  74 References
  75 1. https://hbase.apache.org/book.html#hbase.versioning
  76 2. http://metrics.dropwizard.io/
  77 3. https://hadoop.apache.org/docs/r2.7.2/api/org/apache/hadoop/metrics2/package-summary.html
  78 4. https://issues.apache.org/jira/browse/HBASE-9774