Author: chetanm
Date: Thu Jan 7 09:26:17 2016
New Revision: 1723490
URL: http://svn.apache.org/viewvc?rev=1723490&view=rev
Log:
SLING-4080 - API to capture/measure application-level metrics
Adding docs
Added:
sling/site/trunk/content/documentation/bundles/metric-web-console.png
(with props)
sling/site/trunk/content/documentation/bundles/metrics.mdtext (with props)
Added: sling/site/trunk/content/documentation/bundles/metric-web-console.png
URL:
http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/bundles/metric-web-console.png?rev=1723490&view=auto
==============================================================================
Binary file - no diff available.
Propchange:
sling/site/trunk/content/documentation/bundles/metric-web-console.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: sling/site/trunk/content/documentation/bundles/metrics.mdtext
URL:
http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/bundles/metrics.mdtext?rev=1723490&view=auto
==============================================================================
--- sling/site/trunk/content/documentation/bundles/metrics.mdtext (added)
+++ sling/site/trunk/content/documentation/bundles/metrics.mdtext Thu Jan 7
09:26:17 2016
@@ -0,0 +1,126 @@
+Title: Sling Metrics
+
+Sling Metrics bundle provides integration with [Dropwizard Metrics][1] library
+which provides a toolkit to capture runtime performance statistics in your
+application.
+
+## Features
+
+* Registers a [MetricsService][3] which can be used to create various types of
Metric
+ instances
+* WebConsole Plugin which provides a HTML Reporter for the various Metric
instances
+* Inventory Plugin which dumps the Metric state in plain text format
+
+## Basic Usage
+
+ :::java
+ import org.apache.sling.metrics.Counter;
+ import org.apache.sling.metrics.MetricsService;
+
+ @Reference
+ private MetricsService metricsService;
+
+ private Counter counter;
+
+ @Activate
+ private void activate(){
+ counter = metricsService.counter("sessionCounter");
+ }
+
+ public void onSessionCreation(){
+ counter.inc();
+ }
+
+To make use of `MetricService`
+
+1. Get a reference to `org.apache.sling.metrics.MetricsService`
+2. Initialize the metric e.g. Counter in above case. This avoids
+ any potential lookup cost in critical code paths
+3. Make use of metric instance to capture require stats
+
+Refer to [Metric Getting Started][2] guide to see how various types
+of Metric instances can be used. Note that when using Sling Commons Metric
+bundle class names belong to `org.apache.sling.commons.metrics` package
+
+## API
+
+Sling Metric bundle provides its own Metric classes which are modelled on
+[Dropwizard Metrics][1] library. The metric interfaces defined by Sling bundle
+only provides methods related to data collection.
+
+* [org.apache.sling.commons.metrics.Meter][4] - Similar to [Dropwizard
Meter][dw-meter]
+* [org.apache.sling.commons.metrics.Timer][6] - Similar to [Dropwizard
Timer][dw-timer]
+* [org.apache.sling.commons.metrics.Counter][5] - Similar to [Dropwizard
Timer][dw-counter]
+* [org.apache.sling.commons.metrics.Histogram][7] - Similar to [Dropwizard
Timer][dw-histogram]
+
+Further it provides a `MetricService` which enables creation of different
+type of Metrics like Meter, Timer, Counter and Histogram
+
+### Requirement of wrapper interfaces
+
+* Abstraction - Provides an abstraction around how metrics are collected and
how
+ they are reported and consumed. Most of the code would only be concerned with
+ collecting interesting data. How it gets consumed or reported is
implementation
+ detail
+* Ability to turnoff stats collection - We can easily turn off data collection
+ by switching to NOOP variant of `MetricService` in case it starts adding
appreciable
+ overhead. Turning on and off can also be done on individual metric basis
+
+It also allows us to later extend the type of data collected. For e.g. we can
also collect
+[TimerSeries][8] type of data for each metric without modifying the caller
logic
+
+### Access to Dropwizard Metrics API
+
+Sling Metrics bundle also registers the `MetricRegistry` instance with OSGi
service registry.
+The instances registered has a service property `name` set to `sling` (so as
allow distinguishing
+from any other registered `MetricRegistry` instance). It can be used to get
direct access to Dropwizard
+Metric API if required
+
+ :::java
+ @Reference(target = "(name=sling)")
+ private volatile MetricRegistry dataSource;
+
+Also the wrapper Metric instance can be converted to actual instance via
`adaptTo` calls
+
+ :::java
+ import org.apache.sling.commons.metrics.Counter
+
+ Counter counter = metricService.counter("login");
+ com.codahale.metrics.Counter =
counter.adaptTo(com.codahale.metrics.Counter.class)
+
+## WebConsole Plugin
+
+A Web Console plugin is also provided which is accessible at
+http://localhost:8080/system/console/slingmetrics. It lists down all registered
+metric instances and there state.
+
+
+
+The plugin lists all Metric instances from any `MetricRegistry` instance found
in
+the service registry. If the `MetricRegistry` service has a `name` property
defined
+then that would be prefixed to the Metric names from that registry. This
allows
+use of same name in different registry instances.
+
+## Installation
+
+Add following Maven dependency to your pom.xml:
+
+ :::xml
+ <dependency>
+ <groupId>org.apache.sling</groupId>
+ <artifactId>org.apache.sling.commons.metrics</artifactId>
+ <version>0.0.1-SNAPSHOT</version>
+ </dependency>
+
+[1]: http://metrics.dropwizard.io/
+[dw-meter]: https://dropwizard.github.io/metrics/3.1.0/manual/core/#meters
+[dw-counter]: https://dropwizard.github.io/metrics/3.1.0/manual/core/#counters
+[dw-histogram]:
https://dropwizard.github.io/metrics/3.1.0/manual/core/#histograms
+[dw-timer]: https://dropwizard.github.io/metrics/3.1.0/manual/core/#timers
+[2]: https://dropwizard.github.io/metrics/3.1.0/getting-started/#counters
+[3]:
https://github.com/apache/sling/blob/trunk/bundles/commons/metrics/src/main/java/org/apache/sling/commons/metrics/MetricsService.java
+[4]:
https://github.com/apache/sling/blob/trunk/bundles/commons/metrics/src/main/java/org/apache/sling/commons/metrics/Meter.java
+[5]:
https://github.com/apache/sling/blob/trunk/bundles/commons/metrics/src/main/java/org/apache/sling/commons/metrics/Counter.java
+[6]:
https://github.com/apache/sling/blob/trunk/bundles/commons/metrics/src/main/java/org/apache/sling/commons/metrics/Timer.java
+[7]:
https://github.com/apache/sling/blob/trunk/bundles/commons/metrics/src/main/java/org/apache/sling/commons/metrics/Histogram.java
+[8]:
https://jackrabbit.apache.org/api/2.6/org/apache/jackrabbit/api/stats/TimeSeries.html
\ No newline at end of file
Propchange: sling/site/trunk/content/documentation/bundles/metrics.mdtext
------------------------------------------------------------------------------
svn:eol-style = native
