adobe/metrics-client-for-java

Name: metrics-client-for-java

Owner: Adobe Systems Incorporated

Description: An application metrics client for Java integrated with Graphite/OpenTSDB

Created: 2018-03-05 18:27:55.0

Updated: 2018-05-23 18:42:01.0

Pushed: 2018-05-23 18:41:59.0

Homepage:

Size: 130

Language: Java

GitHub Committers

User	Most Recent Commit	# Commits

Other Committers

User	Email	Most Recent Commit	# Commits

README

Metrics Library for Java

An application metrics client integrated with Graphite/OpenTSDB/more to come. Offers the following features:

• sends the metrics in batch to the backend
• fail safe (retry + circuit breaker to not overwhelm the backend)
• send to multiple backends in parallel
  • useful for migrating to one backend to another
  • useful for sending a set of metrics to one backend (e.g. a sub-set of importants metrics used for alerts in Prometheus) and another set to another backend (e.g. all metrics to OpenTSDB).

Usage

Maven

 https://mvnrepository.com/artifact/com.adobe.aam/metrics-all -->
endency>
<groupId>com.adobe.aam</groupId>
<artifactId>metrics-all</artifactId>
<version>1.0.1</version>
pendency>

Gradle

ttps://mvnrepository.com/artifact/com.adobe.aam/metrics-all
ile group: 'com.adobe.aam', name: 'metrics-all', version: '1.0.1'

Sample application

You can find a demo app in this project: Sample Application

Java docs

You can find here the Java docs

Architecture

Sample App: How to use the metrics library

See metrics-sample app, for a fully fledged demo.

Create a metric

There are several metric types available: CounterMetric, AverageMetric, MaxMetric, MinMetric etc.

Average Metric

reate a metric that generates the average of the values.
ic metric = Metric.newInstance("request.time", Metric.Type.AVG);

ic.track(10);
ic.track(20);

ic.get(); // returns (10 + 20) / 2 = 15

Counter

terMetric metric = new CounterMetric("event.pixel");

ic.increment(); // New value is 1
ic.increment(); // New value is 2
ic.add(10); // New value is 12

ic.get(); // returns 12

Send a metric to a backend (e.g. Graphite / OpenTSDB)

How the metric client manages to publish metrics to the backend

By default, the client is able to send metrics to Backend using a retry mechanism guarded by a circuit breaker mechanism. The former ensures metrics are being resent should the initial request fail, providing a way of not losing important metrics. On the other hand, the circuit breaker mechanism makes the client silently aware of a non-responsive Backend backend by discarding all incoming metrics until the service is up and running again.

Nevertheless, one can always switch to a client w/o retry and/or w/o circuit breaker mechanisms depending on the environment needs. For instance, for a testing environment that does not highly rely on metrics, the metric client can be used without retry and circuit breaker mechanisms.

However, there is a great benefit brought by the enablement of both mechanism (via config) - safely and effectively (using retry) sending metrics while not polluting with metrics the memory of the metric client when the Backend is non-responsive. The downside of enabling the circuit breaker is the potential impact on aggregated metrics - each client node might enter into an open circuit at a different time, hence the metrics are prone to inconsistency

References:

• Circuit Breaker
• Failsafe Library

Create a metric client

The MetricClientFactory contains a series of methods to create a metric client. It can use either configuration file(s), a Properties object, a typesafe config etc.

tor {
collectFrequency : 60000ms
sendOnlyRecentlyUpdatedMetrics: true

tags {
    env : prod
    app_name: mywebapp
    region: us-east-1
    cluster: edge1
    useHostname: true
}

publishers: [ 
    {
        name: Graphite Primary
        type: graphite
        host: graphiterelay.com
        port: 2003
        batch_size: 500
    }
]

ava
reate metric client.
icClient metricClient = new MetricClientFactory()
  .create(config.get("monitor.publishers"), config.get("monitor.tags"));

Send metrics

 timeNow = System.currentTimeMillis() / 1000;
icClient.sendAndReset(metric, timeNow);
icClient.flush();

Using a metric agent to monitor your metrics

The metric agent monitors a list of metrics. Every 60 seconds (or other configurable frequency), it sends the current metric values to the specified metric client and resets them to zero.

<Metric> metrics = new ArrayList<>();
dd metrics to the list


icAgentConfig config = ImmutableMetricAgentConfig.builder()
            .sendOnlyRecentlyUpdatedMetrics(config.getBoolean("monitor.sendOnlyRecentlyUpdatedMetrics"))
            .collectFrequency(config.getDuration("monitor.collectFrequency"))
            .addMetrics(metrics)
            .build();

icAgent metricAgent = new MetricAgent(metricClient, config);

icAgent.startAsync();



icAgent.stopAsync();

Codahale integration

This metrics library is integrated with codahale. You can add one or more codahale MetricRegistry to the metric agent and they will be reported to the backend. Advantages for doing this:

• sends the metrics in batch to the backend
• fail safe (retry + circuit breaker)
• resets the metrics once sent to the backend (useful for Codahale Counters due to https://github.com/dropwizard/metrics/issues/143)
• send to multiple backends in parallel

Build

To build this project:

t clone git@github.com:adobe/metrics-client-for-java.git
 metrics-client-for-java/
gradlew build

Bugs and Feedback

For bugs, questions and discussions please use the GitHub Issues.

LICENSE

Copyright 2018 Adobe Systems Incorporated

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.