sling-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From chet...@apache.org
Subject svn commit: r1723490 - in /sling/site/trunk/content/documentation/bundles: metric-web-console.png metrics.mdtext
Date Thu, 07 Jan 2016 09:26:17 GMT
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. 
+
+![Metric Plugin](/documentation/bundles/metric-web-console.png)
+
+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



Mime
View raw message