sling-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r977219 - in /websites/staging/sling/trunk/content: ./ documentation/bundles/metric-web-console.png documentation/bundles/metrics.html
Date Thu, 07 Jan 2016 09:26:52 GMT
Author: buildbot
Date: Thu Jan  7 09:26:52 2016
New Revision: 977219

Log:
Staging update by buildbot for sling

Added:
    websites/staging/sling/trunk/content/documentation/bundles/metric-web-console.png   (with
props)
    websites/staging/sling/trunk/content/documentation/bundles/metrics.html
Modified:
    websites/staging/sling/trunk/content/   (props changed)

Propchange: websites/staging/sling/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Thu Jan  7 09:26:52 2016
@@ -1 +1 @@
-1723083
+1723490

Added: websites/staging/sling/trunk/content/documentation/bundles/metric-web-console.png
==============================================================================
Binary file - no diff available.

Propchange: websites/staging/sling/trunk/content/documentation/bundles/metric-web-console.png
------------------------------------------------------------------------------
    svn:mime-type = image/png

Added: websites/staging/sling/trunk/content/documentation/bundles/metrics.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation/bundles/metrics.html (added)
+++ websites/staging/sling/trunk/content/documentation/bundles/metrics.html Thu Jan  7 09:26:52
2016
@@ -0,0 +1,226 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<!--
+
+    Licensed to the Apache Software Foundation (ASF) under one or more
+    contributor license agreements.  See the NOTICE file distributed with
+    this work for additional information regarding copyright ownership.
+    The ASF licenses this file to You 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.
+-->
+  <head>
+    <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+    <title>Apache Sling - Sling Metrics</title>
+    <link rel="icon" href="/res/favicon.ico">
+    <link rel="stylesheet" href="/res/site.css" type="text/css" media="all">
+    <link rel="stylesheet" href="/res/codehilite.css" type="text/css" media="all">
+  </head>
+  <body>
+    <div class="title">
+      <div class="logo">
+        <a href="//sling.apache.org/">
+          <img border="0" alt="Apache Sling" src="/res/logo.png">
+        </a>
+      </div>
+      <div class="header">
+        <a href="//www.apache.org/">
+          <img border="0" alt="Apache" src="/res/apache.png">
+        </a>
+      </div>
+    </div>
+    
+    <div class="menu"> 
+      <style type="text/css">
+/* The following code is added by mdx_elementid.py
+   It was originally lifted from http://subversion.apache.org/style/site.css */
+/*
+ * Hide class="elementid-permalink", except when an enclosing heading
+ * has the :hover property.
+ */
+.headerlink, .elementid-permalink {
+  visibility: hidden;
+}
+h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover
> .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink
{ visibility: visible }</style>
+<p><strong><a href="/documentation.html">Documentation</a></strong>
<br />
+<a href="/documentation/getting-started.html">Getting Started</a> <br />
+<a href="/documentation/the-sling-engine.html">The Sling Engine</a> <br />
+<a href="/documentation/development.html">Development</a> <br />
+<a href="/documentation/bundles.html">Bundles</a> <br />
+<a href="/documentation/tutorials-how-tos.html">Tutorials &amp; How-Tos</a>
<br />
+<a href="/documentation/configuration.html">Configuration</a>   </p>
+<p><a href="http://s.apache.org/sling.wiki">Wiki</a> <br />
+<a href="http://s.apache.org/sling.faq">FAQ</a>   </p>
+<p><strong>API Docs</strong>  <br />
+<a href="/apidocs/sling8/index.html">Sling 8</a> <br />
+<a href="/apidocs/sling7/index.html">Sling 7</a> <br />
+<a href="/apidocs/sling6/index.html">Sling 6</a> <br />
+<a href="/apidocs/sling5/index.html">Sling 5</a> <br />
+<a href="/javadoc-io.html">Archive at javadoc.io</a>   </p>
+<p><strong>Project info</strong> <br />
+<a href="/downloads.cgi">Downloads</a> <br />
+<a href="http://www.apache.org/licenses/">License</a> <br />
+<a href="/contributing.html">Contributing</a> <br />
+<a href="/news.html">News</a> <br />
+<a href="/links.html">Links</a> <br />
+<a href="/project-information.html">Project Information</a> <br />
+<a href="https://issues.apache.org/jira/browse/SLING">Issue Tracker</a> <br
/>
+<a href="http://ci.apache.org/builders/sling-trunk">Build Server</a> <br />
+<a href="/project-information/security.html">Security</a>   </p>
+<p><strong>Source</strong> <br />
+<a href="http://svn.apache.org/viewvc/sling/trunk">Subversion</a> <br />
+<a href="git://git.apache.org/sling.git">Git</a> <br />
+<a href="https://github.com/apache/sling">Github Mirror</a>   </p>
+<p><strong>Sponsorship</strong> <br />
+<a href="http://www.apache.org/foundation/thanks.html">Thanks</a> <br />
+<a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a>
<br />
+<a href="http://www.apache.org/foundation/buy_stuff.html">Buy Stuff</a>   </p>
+<p><strong><a href="/sitemap.html">Site Map</a></strong></p>
+<!-- no valid ads for now, we'll  reactivate this when needed
+<iframe 
+    src="http://www.apache.org/ads/button.html"
+    style="border-width:0; float: left" frameborder="0" 
+    scrolling="no"
+    width="135" 
+    height="135">
+</iframe>
+-->
+    </div>
+    
+    <div class="main">
+      <div class="breadcrump" style="font-size: 80%;">
+        <a href="/">Home</a>&nbsp;&raquo&nbsp;<a href="/documentation.html">Documentation</a>&nbsp;&raquo&nbsp;<a
href="/documentation/bundles.html">Bundles</a>
+      </div>
+
+      
+      
+      <h1>Sling Metrics</h1>
+      <style type="text/css">
+/* The following code is added by mdx_elementid.py
+   It was originally lifted from http://subversion.apache.org/style/site.css */
+/*
+ * Hide class="elementid-permalink", except when an enclosing heading
+ * has the :hover property.
+ */
+.headerlink, .elementid-permalink {
+  visibility: hidden;
+}
+h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover
> .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink
{ visibility: visible }</style>
+<p>Sling Metrics bundle provides integration with <a href="http://metrics.dropwizard.io/">Dropwizard
Metrics</a> library
+which provides a toolkit to capture runtime performance statistics in your 
+application. </p>
+<h2 id="features">Features<a class="headerlink" href="#features" title="Permanent
link">&para;</a></h2>
+<ul>
+<li>Registers a <a href="https://github.com/apache/sling/blob/trunk/bundles/commons/metrics/src/main/java/org/apache/sling/commons/metrics/MetricsService.java">MetricsService</a>
which can be used to create various types of Metric
+  instances</li>
+<li>WebConsole Plugin which provides a HTML Reporter for the various Metric instances</li>
+<li>Inventory Plugin which dumps the Metric state in plain text format</li>
+</ul>
+<h2 id="basic-usage">Basic Usage<a class="headerlink" href="#basic-usage" title="Permanent
link">&para;</a></h2>
+<div class="codehilite"><pre><span class="kn">import</span> <span
class="nn">org.apache.sling.metrics.Counter</span><span class="o">;</span>
+<span class="kn">import</span> <span class="nn">org.apache.sling.metrics.MetricsService</span><span
class="o">;</span>
+
+<span class="nd">@Reference</span>
+<span class="kd">private</span> <span class="n">MetricsService</span>
<span class="n">metricsService</span><span class="o">;</span>
+
+<span class="kd">private</span> <span class="n">Counter</span> <span
class="n">counter</span><span class="o">;</span>
+
+<span class="nd">@Activate</span>
+<span class="kd">private</span> <span class="kt">void</span> <span
class="nf">activate</span><span class="o">(){</span>
+    <span class="n">counter</span> <span class="o">=</span> <span
class="n">metricsService</span><span class="o">.</span><span class="na">counter</span><span
class="o">(</span><span class="s">&quot;sessionCounter&quot;</span><span
class="o">);</span>
+<span class="o">}</span>
+
+<span class="kd">public</span> <span class="kt">void</span> <span
class="nf">onSessionCreation</span><span class="o">(){</span>
+    <span class="n">counter</span><span class="o">.</span><span
class="na">inc</span><span class="o">();</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>To make use of <code>MetricService</code></p>
+<ol>
+<li>Get a reference to <code>org.apache.sling.metrics.MetricsService</code></li>
+<li>Initialize the metric e.g. Counter in above case. This avoids 
+   any potential lookup cost in critical code paths</li>
+<li>Make use of metric instance to capture require stats</li>
+</ol>
+<p>Refer to <a href="https://dropwizard.github.io/metrics/3.1.0/getting-started/#counters">Metric
Getting Started</a> guide to see how various types
+of Metric instances can be used. Note that when using Sling Commons Metric 
+bundle class names belong to <code>org.apache.sling.commons.metrics</code> package</p>
+<h2 id="api">API<a class="headerlink" href="#api" title="Permanent link">&para;</a></h2>
+<p>Sling Metric bundle provides its own Metric classes which are modelled on 
+<a href="http://metrics.dropwizard.io/">Dropwizard Metrics</a> library. The metric
interfaces defined by Sling bundle
+only provides methods related to data collection. </p>
+<ul>
+<li><a href="https://github.com/apache/sling/blob/trunk/bundles/commons/metrics/src/main/java/org/apache/sling/commons/metrics/Meter.java">org.apache.sling.commons.metrics.Meter</a>
- Similar to <a href="https://dropwizard.github.io/metrics/3.1.0/manual/core/#meters">Dropwizard
Meter</a></li>
+<li><a href="https://github.com/apache/sling/blob/trunk/bundles/commons/metrics/src/main/java/org/apache/sling/commons/metrics/Timer.java">org.apache.sling.commons.metrics.Timer</a>
- Similar to <a href="https://dropwizard.github.io/metrics/3.1.0/manual/core/#timers">Dropwizard
Timer</a></li>
+<li><a href="https://github.com/apache/sling/blob/trunk/bundles/commons/metrics/src/main/java/org/apache/sling/commons/metrics/Counter.java">org.apache.sling.commons.metrics.Counter</a>
- Similar to <a href="https://dropwizard.github.io/metrics/3.1.0/manual/core/#counters">Dropwizard
Timer</a></li>
+<li><a href="https://github.com/apache/sling/blob/trunk/bundles/commons/metrics/src/main/java/org/apache/sling/commons/metrics/Histogram.java">org.apache.sling.commons.metrics.Histogram</a>
- Similar to <a href="https://dropwizard.github.io/metrics/3.1.0/manual/core/#histograms">Dropwizard
Timer</a></li>
+</ul>
+<p>Further it provides a <code>MetricService</code> which enables creation
of different
+type of Metrics like Meter, Timer, Counter and Histogram</p>
+<h3 id="requirement-of-wrapper-interfaces">Requirement of wrapper interfaces<a class="headerlink"
href="#requirement-of-wrapper-interfaces" title="Permanent link">&para;</a></h3>
+<ul>
+<li>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</li>
+<li>Ability to turnoff stats collection - We can easily turn off data collection
+  by switching to NOOP variant of <code>MetricService</code> in case it starts
adding appreciable
+  overhead. Turning on and off can also be done on individual metric basis</li>
+</ul>
+<p>It also allows us to later extend the type of data collected. For e.g. we can also
collect
+<a href="https://jackrabbit.apache.org/api/2.6/org/apache/jackrabbit/api/stats/TimeSeries.html">TimerSeries</a>
type of data for each metric without modifying the caller logic</p>
+<h3 id="access-to-dropwizard-metrics-api">Access to Dropwizard Metrics API<a class="headerlink"
href="#access-to-dropwizard-metrics-api" title="Permanent link">&para;</a></h3>
+<p>Sling Metrics bundle also registers the <code>MetricRegistry</code>
instance with OSGi service registry. 
+The instances registered has a service property <code>name</code> set to <code>sling</code>
(so as allow distinguishing 
+from any other registered <code>MetricRegistry</code> instance). It can be used
to get direct access to Dropwizard 
+Metric API if required</p>
+<div class="codehilite"><pre><span class="nd">@Reference</span><span
class="o">(</span><span class="n">target</span> <span class="o">=</span>
<span class="s">&quot;(name=sling)&quot;</span><span class="o">)</span>
+<span class="kd">private</span> <span class="kd">volatile</span>
<span class="n">MetricRegistry</span> <span class="n">dataSource</span><span
class="o">;</span>
+</pre></div>
+
+
+<p>Also the wrapper Metric instance can be converted to actual instance via <code>adaptTo</code>
calls</p>
+<div class="codehilite"><pre><span class="kn">import</span> <span
class="nn">org.apache.sling.commons.metrics.Counter</span>
+
+<span class="n">Counter</span> <span class="n">counter</span> <span
class="o">=</span> <span class="n">metricService</span><span class="o">.</span><span
class="na">counter</span><span class="o">(</span><span class="s">&quot;login&quot;</span><span
class="o">);</span>
+<span class="n">com</span><span class="o">.</span><span class="na">codahale</span><span
class="o">.</span><span class="na">metrics</span><span class="o">.</span><span
class="na">Counter</span> <span class="o">=</span> <span class="n">counter</span><span
class="o">.</span><span class="na">adaptTo</span><span class="o">(</span><span
class="n">com</span><span class="o">.</span><span class="na">codahale</span><span
class="o">.</span><span class="na">metrics</span><span class="o">.</span><span
class="na">Counter</span><span class="o">.</span><span class="na">class</span><span
class="o">)</span>
+</pre></div>
+
+
+<h2 id="webconsole-plugin">WebConsole Plugin<a class="headerlink" href="#webconsole-plugin"
title="Permanent link">&para;</a></h2>
+<p>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. </p>
+<p><img alt="Metric Plugin" src="/documentation/bundles/metric-web-console.png"
/></p>
+<p>The plugin lists all Metric instances from any <code>MetricRegistry</code>
instance found in 
+the service registry. If the <code>MetricRegistry</code> service has a <code>name</code>
property defined
+then that would be prefixed to the Metric names from that registry. This allows 
+use of same name in different registry instances.</p>
+<h2 id="installation">Installation<a class="headerlink" href="#installation" title="Permanent
link">&para;</a></h2>
+<p>Add following Maven dependency to your pom.xml:</p>
+<div class="codehilite"><pre><span class="nt">&lt;dependency&gt;</span>
+    <span class="nt">&lt;groupId&gt;</span>org.apache.sling<span class="nt">&lt;/groupId&gt;</span>
+    <span class="nt">&lt;artifactId&gt;</span>org.apache.sling.commons.metrics<span
class="nt">&lt;/artifactId&gt;</span>
+    <span class="nt">&lt;version&gt;</span>0.0.1-SNAPSHOT<span class="nt">&lt;/version&gt;</span>
+<span class="nt">&lt;/dependency&gt;</span>
+</pre></div>
+      <div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
+        Rev. 1723490 by chetanm on Thu, 7 Jan 2016 09:26:17 +0000
+      </div>
+      <div class="trademarkFooter"> 
+        Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project
+        logo are trademarks of The Apache Software Foundation. All other marks mentioned
+        may be trademarks or registered trademarks of their respective owners.
+      </div>
+    </div>
+  </body>
+</html>



Mime
View raw message