Mailing-List: contact issues-help@flink.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@flink.apache.org
From: tillrohrmann <git@git.apache.org>
To: issues@flink.incubator.apache.org
Reply-To: issues@flink.incubator.apache.org
References: <git-pr-2158-flink@git.apache.org>
In-Reply-To: <git-pr-2158-flink@git.apache.org>
Subject: [GitHub] flink pull request #2158: [FLINK-4116] Metrics documentation
Content-Type: text/plain
Message-Id: <20160627115018.043A7DFDC3@git1-us-west.apache.org>
Date: Mon, 27 Jun 2016 11:50:17 +0000 (UTC)
archived-at: Mon, 27 Jun 2016 11:50:25 -0000

Github user tillrohrmann commented on a diff in the pull request:

    https://github.com/apache/flink/pull/2158#discussion_r68563243
  
    --- Diff: docs/apis/common/index.md ---
    @@ -1350,3 +1350,211 @@ You may specify program arguments before the job is executed. The plan visualiza
     the execution plan before executing the Flink job.
     
     {% top %}
    +
    +Metrics
    +-------------------
    +
    +Flink exposes a metric system that allows users gather and expose metrics to external systems.
    +
    +### Registering metrics
    +
    +You can access the metric system from any user function that extends [RichFunction]({{ site.baseurl }}/apis/common/index.html#rich-functions) by calling getRuntimeContext().getMetricGroup().
    +This method returns a MetricGroup object on which you can create and register new metrics.
    +
    +If you want to count the number of records your user function has received you could use a Counter like this:
    +
    +{% highlight java %}
    +
    +public class MyMapper extends RichMapFunction<String, Integer> {
    +  private Counter counter;
    +
    +  @Override
    +  public void open(Configuration config) {
    +    // create and register a counter
    +    this.counter = getRuntimeContext().getMetricGroup().counter("myCounter");
    +    ...
    +  }
    +
    +  @public Integer map(String value) throws Exception {
    +    // increment counter
    +    this.counter.inc();
    +    ...
    +  }
    +}
    +
    +{% endhighlight %}
    +
    +### Metric types
    +
    +Flink supports Counters, Gauges and Histograms.
    +
    +A Counter is used to count something. The current value can be in- or decremented using `inc([long n])` or `dec([long n])`.
    +You can create and registers a Counter by calling `counter(String name)` on a MetricGroup. Alternatively, you can pass an instance of your own Counter implementation along with the name.
    +
    +A Gauge provides a value of any type on demand. In order to use a Gauge you must first create a class that implements the `org.apache.flink.metrics.Gauge` interface.
    +There is not restriction for the type of the returned value.
    +You can register a gauge by calling `gauge(String name, Gauge gauge)` on a MetricGroup.
    +
    +A Histogram measure the distribution of long values.
    +You can register one by calling histogram(String name, Histogram histogram) on a MetricGroup.
    +
    +Flink only provides an interface for Histograms, but offers a Wrapper that allows usage of Codahale/DropWizard Histograms. (org.apache.flink.dropwizard.metrics.DropWizardHistogramWrapper)
    +
    +### Scope
    +
    +Every registered metric has an automatically assigned scope which represent the entities it is tied to. By default a metric that is registered in a user function will be scoped to the Operator in which the function runs, the Task/Job it belongs to and the TaskManager/Host it is executed on. This is referred to as the "system scope".
    +
    +You can define an additonal "user scope" by calling the MetricGroup#addGroup((int/String) name) method.
    +
    +{% highlight java %}
    +
    +counter2 = getRuntimeContext().getMetricGroup().addGroup("MyMetrics").counter("myCounter2");
    +
    +{% endhighlight %}
    +
    +The name under which a metric is exported is based on both scopes and the name passed in the `counter() call. The order is always \<system_scope>\<user_scope>\<name>.
    --- End diff --
    
    Don't we insert a scope separating character in between the system, user and name scope?


---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---