Hadoop名額架構V2

Package org.apache.hadoop.metrics2 Metrics 2.0

Interface Summary
​​MetricsCollector​​	The metrics collector interface
​​MetricsInfo​​	Interface to provide immutable meta info for metrics
​​MetricsPlugin​​	The plugin interface for the metrics framework
​​MetricsRecord​​	An immutable snapshot of metrics with a timestamp
​​MetricsSink​​	The metrics sink interface
​​MetricsSource​​	The metrics source interface
​​MetricsSystemMXBean​​	The JMX interface to the metrics system
​​MetricsVisitor​​	A visitor interface for metrics

Class Summary
​​AbstractMetric​​	The immutable metric
​​MetricsFilter​​	The metrics filter interface
​​MetricsRecordBuilder​​	The metrics record builder interface
​​MetricsSystem​​	The metrics system interface
​​MetricsTag​​	Immutable tag for metrics (for grouping on host/queue/username etc.)

Exception Summary
​​MetricsException​​	A general metrics exception wrapper

Package org.apache.hadoop.metrics2 描述 Metrics 2.0 綜述 這個包為名額監控的建構和釋出提供一個架構。 這個架構提供了多種方法來很容易地實作名額監控的建構，通過簡單的MetricsSource接口或者甚至更簡單、更簡潔和聲明式的名額注釋。名額監控資料消費的一方隻需要實作MetricsSink接口即可。Producers注冊metrics sources到一個名額監控系統，消費者注冊sink。一個預設的監控系統的實作被提供來基于配置選項整理從source到sink的名額監控資料。所有的名額監控資料可通過标準JMX MBean接口被釋出和查詢。本文檔的目标是架構的使用者。架構開發者可以看設計文檔來檢視架構和實作筆記。設計文檔位址：http://wiki.apache.org/hadoop/HADOOP-6728-MetricsV2 子包 org.apache.hadoop.metrics2.annotation 公共的注釋接口，可以更友善的建構名額監控。 org.apache.hadoop.metrics2.impl 架構的頂層包的接口或者抽象類的一些實作類。Sink插件代碼通常不需要引用這裡的任何類。 org.apache.hadoop.metrics2.lib 實作metrics sources的一些很友善的類，包括Mutable[Gauge*| Counter*| Stat] and MetricsRegistry. org.apache.hadoop.metrics2.filter 内置的名額監控過濾器實作包括GlobFilter 和RegexFilter。 org.apache.hadoop.metrics2.source 内置的 metrics source 實作包括JvmMetrics。 org.apache.hadoop.metrics2.sink 内置的 metrics sink實作包括FileSink org.apache.hadoop.metrics2.util 一些實作metrics sinks等的元件式常用的工具類，例如 MetricsCache。 快速上手 實作metrics sources

Using annotations	Using MetricsSource interface
@Metrics(context="MyContext") class MyStat { @Metric("My metric description") public int getMyMetric() { return 42; } }	class MyStat implements MetricsSource { @Override public void getMetrics(MetricsCollector collector, boolean all) { collector.addRecord("MyStat") .setContext("MyContext") .addGauge(info("MyMetric", "My metric description"), 42); } }

在這個例子中，我們介紹下面這些東西： @Metrics Metrics注釋用來聲明這個類是一個metrics source MyContext 可選項context的name通常用來辨別一個application，一個application的一組子產品或者庫。 MyStat 類的名字呗用作metrics record 的名字，一系列的關于它的名額被報告。例如，你有一個叫CacheStat的record，用來報告你的應用的關于記憶體的使用情況。 @Metric Metric注釋用來辨別一個特定的metric，在這個例子中，metric是getMyMetric 方法的傳回值，傳回值預設是gauge類型，這意味着它可以在兩個方向變化，與counter類型相比，counter類型隻能增加或者保持不變。metric的名字MyMetric，取自getMyMetric 方法的方法名。42是metric的值，可以被任意的java表達式替換。 注意：MetricSource接口更冗長但是更靈活，允許生成多個metric名字和多個record。事實上，注釋接口就是實作了MetricsSource接口。 實作metrics sinks

public class MySink implements MetricsSink {
    public void putMetrics(MetricsRecord record) {
      System.out.print(record);
    }
    public void init(SubsetConfiguration conf) {}
    public void flush() {}
}      

在這個例子中，有幾個額外的概念： record 與在metric source中建立的record相一緻的對象，在前面的例子中就是MyStat。 conf 去掉字首的sink執行個體的配置對象，是以你可以用get*方法取得任意指定sink的配置。 flush 這個方法在每一次更新周期内被調用，可能牽扯到多個record。被調用時，sink應該嘗試flush所有緩沖的metric到它的後端。但是同步的實作不是必須的。 為了讓使用者使用MyMetrics 和 MySink，他們需要擁有名額監控系統的調用鈎子。在這個例子中，也是在大多數情況下，DefaultMetricsSystem 就足夠了。

DefaultMetricsSystem.initialize("test"); // 每個應用調用一次
DefaultMetricsSystem.register(new MyStat());      

名額監控系統配置 Sink通常在配置檔案中被指定，在hadoop-metrics2-test.properties檔案中，向下面這樣：

test.sink.mysink0.class=com.example.hadoop.metrics.MySink      

配置的文法是：

[prefix].[source|sink|jmx|].[instance].[option]      

在前面的例子中，test是字首，mysink0是一個執行個體的名字。DefaultMetricsSystem 将首先嘗試加載hadoop-metrics2-[prefix].properties檔案，如果沒有發現，嘗試類路徑中預設的配置檔案hadoop-metrics2.properties。注意，執行個體名是任意的，用來辨別一個特定的sink執行個體。星号可以被用來指定預設的選項。 更多例子，可以參考在jvm，rpc，hdfs和mapred中的實作。 Metrics 過濾器 預設的名額監控系統的一個特性是source，context，record/tags和metric的過濾配置。最廉價的過濾名額的方式是在source級别，例如過濾名叫MyMetrics的source。最昂貴的方式是過濾每個監控名額。 這裡有一些例子：

test.sink.file0.class=org.apache.hadoop.metrics2.sink.FileSink
test.sink.file0.context=foo      

在這個例子中，我們配置一個sink執行個體，這個執行個體将隻接受來自foo context的名額監控資料。

test.source.filter.class=org.apache.hadoop.metrics2.filter.GlobFilter
test.*.source.filter.include=foo
test.*.source.filter.exclude=bar      

在這個例子中，我們指定了一個source filter，這個source filter包括foo，不包括bar。當include模式被指定，過濾器在符合白名單配置的source上操作。同樣的，當exclude模式被指定時，符合模式的source被排除在外。當include和exclude兩個配置都出現時，不符合任何一個模式的source也被include。注意，include配置的模式比exclude模式有優先權。 類似的。你可以指定record.filter和metric.filter，它們各自在record和metric級别起作用。過濾器可以被合并以優化過濾的效率。 名額監控建構政策 在前面的例子中，我們展示了一個使用名額監控架構的最簡單的例子。在一個更大的系統中，像hadoop，允許你自定義名額監控的建構，我們建議下面這樣的方式：

@Metrics(about="My metrics description", context="MyContext")
class MyMetrics extends MyInstrumentation {

    @Metric("My gauge description") MutableGaugeInt gauge0;
    @Metric("My counter description") MutableCounterLong counter0;
    @Metric("My rate description") MutableRate rate0;

    @Override public void setGauge0(int value) { gauge0.set(value); }
    @Override public void incrCounter0() { counter0.incr(); }
    @Override public void addRate0(long elapsed) { rate0.add(elapsed); }
}      

注意，在這個例子中，我們介紹下面這些： MyInstrumentation 這通常用一個抽象類（或一個接口）來定義一個儀器接口，例如incrCounter0 ，這個接口允許不同的實作。這可以是一個允許不同名額監控系統在運作時通過配置使用的機制。 Mutable[Gauge*|Counter*|Rate] 這是一些為了metric source的實作管理可變的名額的類庫。它們通過快照為下遊的資料消費者（sink）生成不可變的測量和計數(Metric[Gauge*|Counter*])。特别地，MutableRate ，提供一個測量延遲和操作的吞吐量的方式。在這種特别的情況下，當被快照時，它産生一個Rate0NumOps的計數和兩個Rate0AvgTime。 從以前的系統遷移 以前的名額監控系統的使用者将會注意到例子配置中context字首的缺失。The new metrics system decouples the concept for context (for grouping) with the implementation where a particular context object does the updating and publishing of metrics, which causes problems when you want to have a single context to be consumed by multiple backends. You would also have to configure an implementation instance per context, even if you have a backend that can handle multiple contexts (file, gangalia etc.):

Before	After
context1.class=org.hadoop.metrics.file.FileContext context2.class=org.hadoop.metrics.file.FileContext ... contextn.class=org.hadoop.metrics.file.FileContext	myprefix.sink.file.class=org.hadoop.metrics2.sink.FileSink

在新的名額監控系統中，你可以通過在sink選項中使用context選項來模仿先前的做法：

Before	After