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